Manage Flexible Sync Subscriptions - Swift SDK

Subscribe to Object Types

Subscription sets are based on object type. You might have multiple subscriptions if you have many types of Realm objects. You can also have multiple subscriptions on the same object type.

However, note the following if you use relationships or asymmetric objects in your app:

Permisos

Subscriptions work hand-in-hand with permissions to determine what data to Sync to your client application. The client application only sees the subset of data that matches your subscriptions which also matches the permissions of the logged-in user.

Esta página detalla cómo administrar las suscripciones de clientes para Sincronización Flexible. Para obtener información sobre cómo configurar permisos para Sincronización Flexible, consulte: Reglas y permisos de Sincronización Flexible.

Subscribe to a Query

Con un usuario autenticado y una configuración de Sincronización Flexible, puede abrir un dominio sincronizado y consultar los objetos que desea leer y escribir. Puede usar la función "subscribe()" para crear una suscripción de Sincronización Flexible para los objetos que coincidan con la consulta:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Task.self)
    .where { $0.progressMinutes >= 60 }.subscribe()
// Go on to work with subscribed results

Esto crea una suscripción sin nombre y la añade a la MutableSubscriptionSet, similar a crear una suscripción manualmente.

Subscribe to a Query with a Subscription Name

If your app works with multiple subscriptions, or if you want to update a subscription, you may want to add a name when you subscribe to a query.

Posteriormente, puedes usar este nombre para actualizar una query de suscripción, comprobar una suscripción por nombre o eliminar la query por nombre.

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Wait for a Query Subscription to Sync

When you subscribe to a query's Results set, that set does not contain objects until it syncs. If your app creates objects, you may not need to download synced data before the user works with it. However, if your app requires data from the server before the user can work with it, you can specify that a subscription should waitForSync:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Team.self)
    .where { $0.members.contains("Bob Smith") }
    .subscribe(
        name: "bob_smith_teams",
        waitForSync: .onCreation)
// After waiting for sync, the results set contains all the objects
// that match the query - in our case, 1
print("The number of teams that have Bob Smith as a member is \(results.count)")

Esta opción utiliza el enum RLMWaitForSyncMode, cuyos casos son:

• .onCreation: Wait to download matching objects when your app creates the subscription. Otherwise, return without waiting for new downloads. The app must have an internet connection the first time you add the subscription.

• .always: Wait to download matching objects when .subscribe() is executed. The app must have an internet connection when .subscribe() is executed.

• .never: Never wait to download matching objects. The app needs an internet connection for the user to authenticate the first time the app launches, but can open offline on subsequent launches using cached credentials.

You can optionally specify a timeout value of type TimeInterval.

Darse de baja de una consulta

Puede cancelar la suscripción al conjunto de una Results consulta utilizando la API .unsubscribe():

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Task.self).where { $0.completed == false }.subscribe()
// Go on to work with subscribed results.
// Later...
results.unsubscribe()

Esto elimina la suscripción de, de forma MutableSubscriptionSet similar a eliminar una suscripción manualmente.

A Results set may still contain objects after calling .unsubscribe() if another subscription exists that contains overlapping objects.

Llamar a .unsubscribe() no espera a que se eliminen los objetos del dominio. No hay ninguna API que espere a que .unsubscribe() se sincronice con el servidor.

Subscribe to an Actor-Confined Query

Puedes suscribirte a una query restringida por actor en el MainActor:

let realm = try await Realm(configuration: flexSyncConfig, actor: MainActor.shared)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Or subscribe to a query on a custom actor:

let realm = try await Realm(configuration: flexSyncConfig, actor: CustomGlobalActor.shared)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Para obtener más información sobre los ámbitos confinados de actor, consulte Usar Realm con Actores - Swift SDK.

Add a Subscription

Agrega una suscripción en un bloque de actualización de suscripciones. Se añade cada nueva suscripción a las suscripciones del cliente en Realm.

let realm = try await getRealmWithSingleSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithSingleSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
       subscriptions.append(
          QuerySubscription<Team> {
             $0.teamName == "Developer Education"
          })
    }
    return realm
}

You can add multiple subscriptions within a subscription update block, including subscriptions of different object types.

let realm = try await getRealmWithMultipleSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithMultipleSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.append(
            QuerySubscription<Task>(name: "completed-tasks") {
                 $0.completed == true
        })
        subscriptions.append(
            QuerySubscription<Team> {
              $0.teamName == "Developer Education"
        })
    }
    return realm
}

var flexSyncConfig = user.flexibleSyncConfiguration(initialSubscriptions: { subs in
    subs.append(
        QuerySubscription<Team> {
               $0.teamName == "Developer Education"
            })
})

// Set the date a week ago and the date a week from now, as those are the dates we'll use
// in the Flexible Sync query. `rerunOnOpen` lets the app recalculate this query every
// time the app opens.
let secondsInAWeek: TimeInterval = 604800
let dateLastWeek = (Date.now - secondsInAWeek)
let dateNextWeek = (Date.now + secondsInAWeek)
var flexSyncConfig = user.flexibleSyncConfiguration(initialSubscriptions: { subs in
    subs.append(
        QuerySubscription<Task> {
            $0.dueDate > dateLastWeek && $0.dueDate < dateNextWeek
        })
}, rerunOnOpen: true)

let realm = try await subscribeToObjectsOfAType()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func subscribeToObjectsOfAType() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.append(QuerySubscription<Team>(name: "all_teams"))
    }
    XCTAssertEqual(subscriptions.count, 1) // :remove
    return realm
}

let realm = try await checkAndAddSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func checkAndAddSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    let foundSubscription = subscriptions.first(named: "user_team")
    try await subscriptions.update {
        if foundSubscription != nil {
            foundSubscription!.updateQuery(toType: Team.self, where: {
                 $0.teamName == "Developer Education"
            })
        } else {
            subscriptions.append(
                QuerySubscription<Team>(name: "user_team") {
                  $0.teamName == "Developer Education"
               })
        }
    }
    return realm
}

Espere a que los cambios de suscripción se sincronicen

Actualizar el conjunto de suscripciones localmente es solo un componente del cambio de suscripción. Después del cambio de suscripción local, el realm se sincroniza con el servidor para resolver cualquier actualización de datos debido al cambio de suscripción. Esto podría significar agregar o remover datos del realm sincronizado.

let subscriptions = realm.subscriptions
subscriptions.update({
   subscriptions.append(
      QuerySubscription<Task> {
         $0.assignee == "John Doe"
      })
}, onComplete: { error in // error is optional
    if error == nil {
       // Flexible Sync has updated data to match the subscription
    } else {
       // Handle the error
    }
 })

@MainActor
func changeSubscription() async throws {
   let subscriptions = realm.subscriptions
   try await subcriptions.update {
      subscriptions.remove {
         QuerySubscription<Task> {
            $0.assignee == "Joe Doe"
         }
      }
   }
}

Subscription Set State

Utilice la propiedad SubscriptionSet.state para leer el estado actual del conjunto de suscripciones.

El superseded estado es un SyncSubscriptionState que puede ocurrir cuando otro subproceso actualiza una suscripción en una instancia diferente del conjunto de suscripciones. Si el estado cambia superseded a, debe obtener una nueva instancia del conjunto de suscripciones para poder actualizarlo.

Update Subscriptions with a New Query

Se puede actualizar la query de una suscripción utilizando updateQuery. En este ejemplo, buscamos una subscripción que coincida con nuestra query y luego la actualizamos con una nueva query.

let realm = try await getRealmWithUpdatedSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithUpdatedSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        if let foundSubscription = subscriptions.first(ofType: Team.self, where: {
            $0.teamName == "Developer Education"
        }) {
            foundSubscription.updateQuery(toType: Team.self, where: {
                $0.teamName == "Documentation"
            })
        }
    }
    return realm
}

También puedes buscar una suscripción por nombre. En este ejemplo, buscamos una consulta de suscripción por nombre y la actualizamos con una nueva consulta.

let realm = try await getRealmWithUpdatedSubscriptionName()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithUpdatedSubscriptionName() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    let foundSubscription = subscriptions.first(named: "user-team")
    try await subscriptions.update {
        foundSubscription?.updateQuery(toType: Team.self, where: {
             $0.teamName == "Documentation"
        })
    }
    return realm
}

Eliminar suscripciones

To remove subscriptions, you can:

• Remove a single subscription query

• Remove all subscriptions to a specific object type

• Remover todas las suscripciones sin nombre

• Remove all subscriptions

Cuando elimina una consulta de suscripción, Realm elimina de forma asincrónica los datos sincronizados que coinciden con la consulta del dispositivo cliente.

let realm = try await getRealmAfterRemovingSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    // Look for a specific subscription, and then remove it
    let foundSubscription = subscriptions.first(named: "docs-team")
    try await subscriptions.update {
        subscriptions.remove(foundSubscription!)
    }
    // Or remove a subscription that you know exists without querying for it
    try await subscriptions.update {
        subscriptions.remove(named: "existing-subscription")
    }
    return realm
}

let realm = try await getRealmAfterRemovingAllSubscriptionsToAnObjectType()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingAllSubscriptionsToAnObjectType() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.removeAll(ofType: Team.self)
    }
    return realm
}

let realm = try await Realm(configuration: flexSyncConfig)
// Add 2 subscriptions, one named and one unnamed.
let results = try await realm.objects(Team.self).where { $0.teamName == "Developer Education" }.subscribe(name: "team_developer_education")
let results2 = try await realm.objects(Task.self).where { $0.completed == false }.subscribe()
// Later, remove only the unnamed one
let subscriptions = realm.subscriptions
try await subscriptions.update {
    subscriptions.removeAll(unnamedOnly: true)
}

let realm = try await getRealmAfterRemovingAllSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingAllSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.removeAll()
    }
    return realm
}

API Efficiency

Adding several subscriptions with the .subscribe() and .unsubscribe() APIs described in the Subscribe to Queries section is less efficient than performing batch updates when you manually manage subscriptions. On every .subscribe(), the Swift SDK opens a new update block. For better performance adding multiple subscriptions, use the subscriptions.update API described in the Manually Manage Subscriptions section.

Actualizaciones de grupos para mejorar el rendimiento

Every write transaction for a subscription set has a performance cost. If you need to make multiple updates to a Realm object during a session, consider keeping edited objects in memory until all changes are complete. This improves sync performance by only writing the complete and updated object to your realm instead of every change.

Requisitos de suscripción a campos consultables indexados

Adding an indexed queryable field to your App can improve performance for simple queries on data that is strongly partitioned. For example, an app where queries strongly map data to a device, store, or user, such as user_id == $0, “641374b03725038381d2e1fb”, is a good candidate for an indexed queryable field. However, an indexed queryable field has specific requirements for use in a query subscription:

• The indexed queryable field must be used in every subscription query. It cannot be missing from the query.

• The indexed queryable field must use an == or IN comparison against a constant at least once in the subscription query. (El campo consultable debe utilizar una comparación o contra una constante al menos una vez en la consulta de suscripción.) For example, user_id == $0, "641374b03725038381d2e1fb" or store_id IN $0, {1,2,3}. (Por ejemplo, o .)

Opcionalmente, puedes incluir una comparación de AND siempre que el campo indexado consultable se compare directamente con una constante usando == o IN al menos una vez. Por ejemplo, store_id IN {1,2,3} AND region=="Northeast" o store_id == 1 AND (active_promotions < 5 OR num_employees < 10).

Invalid Flexible Sync queries on an indexed queryable field include queries where:

• The indexed queryable field does not use AND with the rest of the query. For example store_id IN {1,2,3} OR region=="Northeast" is invalid because it uses OR instead of AND. Similarly, store_id == 1 AND active_promotions < 5 OR num_employees < 10 is invalid because the AND only applies to the term next to it, not the entire query.

• El campo consultable indexado no se utiliza en un operador de igualdad. Por ejemplo, store_id > 2 AND region=="Northeast" no es válido porque solo utiliza el operador > con el campo consultable indexado y no tiene una comparación de igualdad.

• The query is missing the indexed queryable field entirely. For example, region=="Northeast or truepredicate are invalid because they do not contain the indexed queryable field.

Unsupported Query Operators in Flexible Sync

Flexible Sync has some limitations when using RQL operators. When you write the query subscription that determines which data to sync, the server does not support these query operators. However, you can still use the full range of RQL features to query the synced data set in the client application.

Las queries que no distinguen entre mayúsculas y minúsculas ([c]) no pueden usar índices de manera eficaz. Como resultado, no se recomiendan las queries que no distinguen entre mayúsculas y minúsculas, ya que podrían provocar problemas de rendimiento.

Flexible Sync only supports @count for array fields.

List Queries

Flexible Sync admite la consulta de listas usando el operador IN.

Puede consultar una lista de constantes para ver si contiene el valor de un campo consultable:

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

If a queryable field has an array value, you can query to see if it contains a constant value:

// Query an array-valued queryable field for a constant value
"'comedy' IN genres"

// Invalid Flexible Sync query. Do not do this!
"{'comedy', 'horror', 'suspense'} IN genres"
// Another invalid Flexible Sync query. Do not do this!
"ANY {'comedy', 'horror', 'suspense'} != ANY genres"

Objetos incrustados o vinculados

Flexible Sync does not support querying on properties in Embedded Objects or links. For example, obj1.field == "foo".

Query Size Limit

The size limit for any given query subscription in your subscription set is 256 kB. Exceeding this limit results in a LimitsExceeded Error.