Administrar suscripciones de sincronización flexible - Swift SDK

Suscribirse a tipos de objetos

Los conjuntos de suscripciones se basan en el tipo de objeto. Es posible que tenga varias suscripciones si tiene varios tipos de objetos de Realm. También puede tener varias suscripciones para el mismo tipo de objeto.

Sin embargo, tenga en cuenta lo siguiente si utiliza relaciones u objetos asimétricos en su aplicación:

Permisos

Las suscripciones funcionan en conjunto con los permisos para determinar qué datos sincronizar con la aplicación cliente. La aplicación cliente solo ve el subconjunto de datos que coincide con las suscripciones y los permisos del usuario conectado.

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.

Suscribirse a una consulta

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 agrega MutableSubscriptionSet a, de forma similar a crear una suscripción manualmente.

Suscribirse a una consulta con un nombre de suscripción

Si su aplicación funciona con múltiples suscripciones o si desea actualizar una suscripción, es posible que desee agregar un nombre cuando se suscriba a una consulta.

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

Espere a que se sincronice una suscripción de consulta

Al suscribirse al conjunto Results de una consulta, este no contiene objetos hasta que se sincroniza. Si su aplicación crea objetos, es posible que no necesite descargar los datos sincronizados antes de que el usuario pueda trabajar con ellos. Sin embargo, si su aplicación requiere datos del servidor antes de que el usuario pueda trabajar con ellos, puede especificar que una suscripción 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: Esperar a que se descarguen los objetos coincidentes cuando la aplicación crea la suscripción. De lo contrario, regresar sin esperar nuevas descargas. La aplicación debe tener conexión a internet la primera vez que se agrega la suscripción.

• .always: Esperar a descargar los objetos coincidentes cuando se ejecuta .subscribe(). La aplicación debe tener conexión a internet cuando se ejecuta .subscribe().

• .never: Nunca esperes para descargar los objetos coincidentes. La aplicación necesita conexión a internet para que el usuario se autentique la primera vez que se inicia, pero puede abrirse sin conexión en los siguientes inicios usando credenciales en caché.

Opcionalmente, puede especificar un timeout valor de tipo 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.

Un conjunto Results aún puede contener objetos después de llamar a .unsubscribe() si existe otra suscripción que contiene objetos superpuestos.

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.

Suscribirse a una consulta limitada por actores

Puede suscribirse a una consulta limitada al actor en 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

O suscríbete a una consulta sobre un actor personalizado:

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 reinos limitados por actores, consulte Usar reino con actores - Swift SDK.

Añadir una suscripción

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
}

Puede agregar varias suscripciones dentro de un bloque de actualización de suscripciones, incluidas suscripciones de diferentes tipos de objetos.

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"
         }
      }
   }
}

Estado del conjunto de suscripción

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.

Actualizar suscripciones con una nueva consulta

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

Para eliminar suscripciones, puedes:

• Eliminar una sola consulta de suscripción

• Eliminar todas las suscripciones a un tipo de objeto específico

• Remover todas las suscripciones sin nombre

• Eliminar todas las suscripciones

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
}

Eficiencia de la API

Añadir varias suscripciones con las .subscribe() .unsubscribe() API y descritas en la sección "Suscribirse a consultas" es menos eficiente que realizar actualizaciones por lotes al gestionar las suscripciones manualmente..subscribe() Cada, el SDK de Swift abre un nuevo bloque de actualización. Para un mejor rendimiento al añadir varias suscripciones, utilice la subscriptions.update API descrita en la sección "Gestionar suscripciones manualmente".

Actualizaciones de grupo para un mejor rendimiento

Cada transacción de escritura para un conjunto de suscripciones tiene un coste de rendimiento. Si necesita realizar varias actualizaciones a un objeto de Realm durante una sesión, considere mantener los objetos editados en memoria hasta que se completen todos los cambios. Esto mejora el rendimiento de la sincronización al escribir solo el objeto completo y actualizado en su reino, en lugar de cada cambio.

Requisitos de suscripción a campos consultables indexados

Añadir un campo consultable indexado a tu aplicación puede mejorar el rendimiento de consultas simples sobre datos con particiones estrictas. Por ejemplo, una aplicación donde las consultas asignan datos de forma estricta a un dispositivo, tienda o usuario,user_id == $0, “641374b03725038381d2e1fb” como, es una buena candidata para un campo consultable indexado. Sin embargo, un campo consultable indexado tiene requisitos específicos para su uso en una suscripción de consultas:

• El campo consultable indexado debe usarse en todas las consultas de suscripción. No puede faltar en la consulta.

• El campo consultable indexado debe usar una comparación == o IN con una constante al menos una vez en la consulta de suscripción. Por ejemplo, user_id == $0, "641374b03725038381d2e1fb" o store_id IN $0, {1,2,3}.

Opcionalmente, puede incluir una comparación AND siempre que el campo consultable indexado 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).

Las consultas de sincronización flexibleno válidas en un campo consultable indexado incluyen consultas donde:

• El campo consultable indexado no usa AND con el resto de la consulta. Por ejemplo, store_id IN {1,2,3} OR region=="Northeast" no es válido porque usa OR en lugar de AND. De igual manera, store_id == 1 AND active_promotions < 5 OR num_employees < 10 no es válido porque AND solo se aplica al término contiguo, no a toda la consulta.

• 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.

• A la consulta le falta por completo el campo consultable indexado. Por ejemplo, region=="Northeast o truepredicate no son válidos porque no contienen dicho campo.

Operadores de consulta no admitidos en Flexible Sync

La sincronización flexible presenta algunas limitaciones al usar operadores RQL. Al escribir la suscripción de consulta que determina qué datos sincronizar, el servidor no admite estos operadores. Sin embargo, aún puede usar todas las funciones de RQL para consultar el conjunto de datos sincronizados en la aplicación cliente.

Las consultas que no distinguen entre mayúsculas y minúsculas ([c]) no pueden usar índices eficazmente. Por lo tanto, no se recomiendan, ya que podrían causar problemas de rendimiento.

Flexible Sync solo admite @count para campos de matriz.

Consultas de lista

Flexible Sync admite la consulta de listas mediante 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 }"

Si un campo consultable tiene un valor de matriz, puedes consultar para ver si contiene un valor constante:

// 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

La sincronización flexible no admite consultas sobre propiedades en objetos incrustados ni enlaces. Por ejemplo, obj1.field == "foo".

Límite de tamaño de consulta

El límite de tamaño para cualquier suscripción de consulta en su conjunto de suscripciones es de kB. Superar este límite genera 256 un error "LimitsExceeded".