Administrar suscripciones de sincronización - SDK de Flutter

Suscribirse a una consulta

Puedes suscribirte al RealmResults de una consulta mediante el método subscribe(). Al llamarlo, el SDK crea la nueva suscripción y la añade MutableSubscriptionSet al, de forma similar a la creación manual de una suscripción.

Opcionalmente, puede pasar un nombre de suscripción único para la consulta. Si agrega una suscripción con el mismo nombre que una suscripción existente, el SDK la sobrescribirá.

Si no se especifica un nombre de suscripción, este se establece en null y el identificador de la suscripción se basa en la cadena de consulta. Esto significa que cada vez que cambia la cadena de consulta, subscribe() crea una nueva suscripción.

Para suscribirse a una consulta, pase los siguientes argumentos a subscribe():

• RealmResults query: Obligatorio. Un RealmResults objeto que puede crearse mediante el lenguaje de consulta Realm.

• String name: Opcional. Nombre de la suscripción al que puedes referenciar.

• bool update: Opcional. Si es verdadero, al agregar una suscripción con un nombre existente, se reemplaza la consulta existente por la nueva. Si es falso, el SDK genera una excepción para suscripciones duplicadas. Úselo solo con suscripciones con nombre.

En el siguiente ejemplo, nos suscribimos a dos nuevas consultas con nombre.

final boatQuery = realm.all<Boat>();
final bigPlaneQuery = realm.query<Plane>("numSeats > 100");
final boatSubscription = await boatQuery.subscribe(name: "boats");
final planeSubscription =
    await bigPlaneQuery.subscribe(name: "big-planes");

Espere a que se sincronice una suscripción de consulta

Al suscribirse a los resultados de una consulta, estos no contienen objetos hasta que se descargan los datos sincronizados. Si necesita esperar a que se descarguen los objetos sincronizados, configure la opción waitForSyncMode.

Este ejemplo utiliza la opción firstTime, que es el comportamiento predeterminado. Una suscripción con el comportamiento firstTime solo espera a que finalice la sincronización al crearse la suscripción.

final bigPlaneQuery = realm.query<Plane>("numSeats > 100");
final planeSubscription = await bigPlaneQuery.subscribe(
  name: "firstTimeSync",
  waitForSyncMode: WaitForSyncMode.firstTime,
);

Las otras opciones admitidas waitForSyncMode son:

• always: Espera a que se descarguen los objetos coincidentes cada vez que se inicia la aplicación. La aplicación debe tener conexión a internet cada vez que se inicia.

• neverNo 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, puedes especificar un token de cancelación para limitar cuánto tiempo sigue ejecutar la sincronizar descargar:

final bigPlaneQuery = realm.query<Plane>("numSeats > 200");
final planeSubscription = await bigPlaneQuery.subscribe(
  name: "alwaysWaitSync",
  waitForSyncMode: WaitForSyncMode.always,
  cancellationToken: TimeoutCancellationToken(Duration(seconds: 5)),
);

Darse de baja de una consulta

Las suscripciones persisten entre sesiones de usuario a menos que las canceles. Puedes cancelar la suscripción a los resultados de una consulta mediante unsubscribe().

Esto elimina la suscripción de la lista de suscripciones activas, de forma similar a eliminarla manualmente. Tenga en cuenta que la lista de resultados puede seguir conteniendo objetos después de llamar unsubscribe() a si existe otra suscripción con objetos superpuestos.

Al llamar a unsubscribe() en una consulta, el SDK elimina cualquier suscripción con consultas que coincidan exactamente con la consulta en la que se llama a unsubscribe(). Este método retorna antes de que se eliminen del dominio los objetos que coinciden con la suscripción eliminada. La sincronización continúa en segundo plano según el nuevo conjunto de suscripciones.

planeQuery.unsubscribe();
trainQuery.unsubscribe();

Obtener suscripciones

Al utilizar Flexible Sync, puede acceder a un SubscriptionSet, una colección de suscripciones, a través de la Realm.subscriptions propiedad.

Puede utilizar este conjunto de suscripciones para agregar consultas a esta lista de suscripciones y actualizar las suscripciones existentes, como se muestra en los ejemplos a continuación.

final subscriptions = realm.subscriptions;

Agregar una consulta al conjunto de suscripciones

Debe realizar todas las mutaciones en las suscripciones establecidas dentro de un bloque de actualización. Para crear un bloque de actualización, llame a SubscriptionSet.update().

La función de devolución de llamada del bloque de actualización incluye un objeto MutableSubscriptionSet() como argumento. Puede modificar su método en SubscriptionSet para agregar una consulta a la suscripción.

El método MutableSubscriptionSet.add() toma tres argumentos:

• RealmResults query: Obligatorio. Un RealmResults objeto que puede crearse mediante la consulta del lenguaje de consulta Realm.

• String name: Opcional. Nombre de la suscripción al que puedes referenciar.

• bool update: Opcional. Si es verdadero, al agregar una suscripción con un nombre existente, se reemplaza la consulta existente por la nueva. Úselo solo con suscripciones con nombre.

Puede agregar una sola consulta o agrupar varias consultas dentro de un bloque SubscriptionSet.update. Actualizar las consultas es una operación costosa para el servidor. Le recomendamos encarecidamente que diseñe su aplicación para minimizar las actualizaciones de suscripciones. Puede lograrlo creando todas las suscripciones en un único bloque de actualización la primera vez que el usuario inicia la aplicación y agrupando los cambios posteriores en el conjunto de suscripciones.

En el siguiente ejemplo, nos suscribimos a dos consultas.

final planeQuery = realm.all<Plane>();
final longTrainQuery = realm.query<Train>("numCars >= 5");
realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.add(planeQuery, name: "planes");
  mutableSubscriptions.add(longTrainQuery,
      name: 'long-trains', update: true);
});
await realm.subscriptions.waitForSynchronization();

Actualizar suscripciones con una nueva consulta

Puede actualizar una suscripción con nombre con una nueva consulta. Para actualizar la consulta de una suscripción, abra un bloque de actualización con SubscriptionSet.update(). En la función de devolución de llamada del bloque de actualización, pase los siguientes argumentos a MutableSubscriptionSet.add():

• La nueva consulta

• El nombre de la suscripción que desea actualizar

• update: true

No se puede actualizar una suscripción sin nombre. También se puede eliminar la suscripción sin nombre y crear una nueva con la consulta deseada.

En el siguiente ejemplo, los trenes largos se redefinen como cualquier tren que tenga más de 10 vagones.

final longerTrainQuery = realm.query<Train>("numCars > 10");
realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.add(longerTrainQuery,
      name: 'long-trains', update: true);
});

Eliminar suscripciones

Para eliminar suscripciones del conjunto de suscripciones, puede:

• Eliminar una sola suscripción con la consulta indicada

• Eliminar una sola suscripción con el nombre especificado

• Eliminar una sola suscripción con la referencia de suscripción

• Eliminar todas las suscripciones para un tipo de objeto Realm

• Eliminar todas las suscripciones

Cuando elimina una consulta de suscripción, el servidor también elimina los datos sincronizados del dispositivo cliente.

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.removeByQuery(realm.all<Plane>());
});

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.removeByName('long-trains');
});

final sub = realm.subscriptions[0];
realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.remove(sub);
});

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.removeByType<Train>();
});

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.clear();
});

Espere a que los cambios de suscripción se sincronicen

Modificar el conjunto de suscripciones dentro de un bloque de actualización es solo una parte del proceso de cambio de una suscripción. Tras el cambio de suscripción local, el dominio se sincroniza con el servidor para resolver cualquier actualización de datos debida al cambio de suscripción. Esto incluye añadir o eliminar datos del dominio sincronizado.

Utilice Realm.subscriptions.waitForSynchronization() para esperar a que el servidor confirme este conjunto de suscripciones. Si el servidor rechaza el cambio, se genera una excepción.

Puede ocurrir una excepción si:

• Te suscribes a una consulta no compatible. Suscribirte a una consulta no compatible pausará la sincronización. Para reanudarla, elimina la consulta no compatible.

• Está realizando una acción no válida, como agregar un objeto que no coincide con una suscripción. Esto activa un reinicio del cliente: se borran los datos del dominio y se crea una nueva copia sin ninguna suscripción en el conjunto.

await realm.subscriptions.waitForSynchronization();

Estado de suscripción

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

El superseded estado es un SubscriptionSetState 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.

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

Eficiencia de la API

Administrar varias suscripciones con la .subscribe() API (descrita en la sección "Suscribirse a consultas") es menos eficiente que realizar actualizaciones por lotes cuando se administran manualmente mediante la API de conjuntos de suscripciones. Para un mejor rendimiento al realizar cambios en varias suscripciones, utilice la subscriptions.update API (descrita en la sección "Administrar 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.