Administrar suscripciones de sincronización - SDK de Node.js

Suscribirse a una consulta

Le recomendamos que asigne un nombre a sus suscripciones. Esto facilita su búsqueda y gestión. Los nombres de las suscripciones deben ser únicos. Intentar agregar una suscripción con el mismo nombre que una ya existente genera un error.

Para suscribirse a una consulta:

1. Consulta los objetos que quieres leer y escribir.

2. Llamar subscribe() en los resultados de la consulta para crear una suscripción de sincronización para los objetos que coincidan con la consulta.

3. Pase un objeto SubscriptionOptions que contenga la propiedad name a subscribe().

const subOptions = {
  name: "All completed tasks",
};
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe(subOptions);
const completedTasksSubscription = realm.subscriptions.findByName(
  "All completed tasks"
);
// ...work with the subscribed results list or modify the subscription

const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe({ name: "All completed tasks" });
const completedTasksSubscription = realm.subscriptions.findByName(
  "All completed tasks"
);
// ...work with the subscribed results list or modify the subscription

Suscribirse a una consulta sin un nombre de suscripción

Generalmente, deberías asignar un nombre a tus suscripciones. Si no, el nombre se establece como nulo.

Si usa filtered() en una suscripción de consulta sin nombre, el identificador de la suscripción se basa en la consulta filtered. Esto significa que cada vez que cambie la cadena de consulta, subscribe() creará una nueva suscripción.

const config = {
  schema: [Task],
  sync: {
    user: app.currentUser,
    flexible: true,
  },
};
const realm = await Realm.open(config);
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe();
// ...work with the subscribed results list

const config: Realm.Configuration = {
  schema: [Task],
  sync: {
    user: app.currentUser!,
    flexible: true,
  },
};
const realm = await Realm.open(config);
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe();
// ...work with the subscribed results list

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 los objetos sincronizados terminen de descargarse, utilice waitForSync. Puede especificar diferentes comportamientos para sus suscripciones y cómo gestionan la escritura de las descargas.

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.

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Only waits for sync to finish on the initial sync.
await completedTasks.subscribe({
  behavior: WaitForSync.FirstTime,
  name: "First time sync only",
});

Las otras opciones admitidas WaitForSync 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, puede especificar un valor timeout para limitar el tiempo que dura la descarga sincronizada:

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Add subscription with timeout
// If timeout expires before sync is completed, currently-downloaded
// objects are returned and sync download continues in the background.
const taskSubscription = await completedTasks.subscribe({
  behavior: WaitForSync.Always,
  timeout: 500,
});

Darse de baja de una consulta

Para cancelar la suscripción a los resultados de una query utilizando unsubscribe():

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Only waits for sync to finish on the initial sync.
await completedTasks.subscribe({
  behavior: WaitForSync.FirstTime,
  name: "First time sync only",
});
// Unsubscribe
completedTasks.unsubscribe();

Esto elimina la suscripción de la lista de suscripciones activas, de forma similar a eliminar una suscripción manualmente.

Una lista de resultados aún puede contener objetos después de llamar a unsubscribe() si existe otra suscripción que contiene objetos superpuestos.

Al llamar a unsubscribe(), se elimina la suscripción asociada. Las suscripciones se eliminan por nombre. Si no tienen nombre, unsubscribe() elimina cualquier consulta que coincida exactamente con la consulta en la que se llama a unsubscribe().

El método unsubscribe() regresa 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.

Obtenga todas las suscripciones

Al utilizar un reino sincronizado flexible, puede acceder SubscriptionSet a, una colección de suscripciones, a través de la propiedad realm.subscriptions.

// get the SubscriptionSet for the realm
const subscriptions = realm.subscriptions;

Añadir una suscripción

Las suscripciones se basan en los resultados de las consultas de reino.

En el siguiente ejemplo, se han establecido completed y progressMinutes como campos consultables en una aplicación de App Services. En el código del cliente, creamos consultas filtradas y luego nos suscribimos a sus resultados:

• Tareas completadas

• Tareas completadas que han ocupado 120 progressMinutes

const tasks = realm.objects("Task");
const longRunningTasks = tasks.filtered(
  'status == "completed" && progressMinutes > 120'
);
await realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(longRunningTasks, {
    name: "longRunningTasksSubscription",
  });
  mutableSubs.add(realm.objects("Team"), {
    name: "teamsSubscription",
  });
});

Establecer suscripciones iniciales

Debes tener al menos una suscripción para poder leer o escribir en un reino de sincronización flexible. Puedes añadir una suscripción inicial al abrir un reino.

Para initialSubscriptions configurar las suscripciones iniciales, incluya el campo en la configuración de sincronización de su dominio. Dentro del initialSubscriptions objeto, agregue un update campo configurado para una devolución de llamada que se suscriba a las consultas:

const config = {
  schema: [Task],
  sync: {
    user: app.currentUser,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(realm.objects(Task).filtered("status == 'in progress'"), {
          name: "In progress tasks",
        });
      },
      rerunOnOpen: true,
    },
  },
};
const realm = await Realm.open(config);

const config: Realm.Configuration = {
  schema: [Task],
  sync: {
    user: app.currentUser!,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(realm.objects(Task).filtered("status == 'in progress'"), {
          name: "In progress tasks",
        });
      },
      rerunOnOpen: true,
    },
  },
};
const realm = await Realm.open(config);

De forma predeterminada, las suscripciones iniciales solo se crean la primera vez que se abre un reino. Si su aplicación necesita volver a ejecutar esta suscripción inicial cada vez que se inicia, puede establecer rerunOnOpen en true. Podría ser necesario hacerlo para volver a ejecutar intervalos de tiempo dinámicos u otras consultas que requieran volver a calcular las variables estáticas de la suscripción.

Comprueba el estado de las suscripciones

Puede comprobar el estado de la suscripción para ver si el servidor ha reconocido la suscripción y el dispositivo ha descargado los datos localmente.

Puede utilizar el estado de suscripción para:

• Manejo de errores de activación

• Mostrar si la transacción está pendiente o se ha completado

• Descubre cuándo se reemplaza un conjunto de suscripciones y deberías obtener una nueva instancia del conjunto de suscripciones para guardar un cambio de suscripción.

Node.js v12.0.0 agregó la enumeración SubscriptionSetState que puede usar para obtener el estado de una suscripción.

Actualizar suscripciones con una nueva consulta

Puede actualizar una suscripción con nombre mediante una nueva consulta. Para actualizar la consulta de una suscripción, pase la nueva consulta y una opción de suscripción con el nombre de la suscripción que desea actualizar al método MutableSubscriptionSet.add(). Al igual que al añadir una nueva suscripción, debe actualizarla dentro de una transacción llamando a subscriptions.update().

En el siguiente ejemplo, las tareas de larga ejecución se redefinen como cualquier tarea que haya tomado más de 180 minutos.

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(
    tasks.filtered('status == "completed" && progressMinutes > 180'),
    {
      name: "longRunningTasksSubscription",
    }
  );
});

Eliminar suscripciones

Puedes eliminar suscripciones de varias maneras:

• Eliminar una sola suscripción con una consulta específica

• Eliminar una sola suscripción con un nombre específico

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

• Remover todas las suscripciones sin nombre

• 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((mutableSubs) => {
  // remove a subscription with a specific query
  mutableSubs.remove(tasks.filtered('owner == "Ben"'));
});

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific name
  mutableSubs.removeByName("longRunningTasksSubscription");
});

let subscriptionReference;
realm.subscriptions.update((mutableSubs) => {
  subscriptionReference = mutableSubs.add(realm.objects("Task"));
});
// later..
realm.subscriptions.removeSubscription(subscriptionReference);

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeByObjectType("Team");
});

// Remove unnamed subscriptions.
let numberRemovedSubscriptions = 0;
await realm.subscriptions.update((mutableSubs) => {
  numberRemovedSubscriptions = mutableSubs.removeUnnamed();
});

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeAll();
});

Eficiencia de la API

Administrar múltiples suscripciones con las subscribe() unsubscribe() API y descritas en la sección Suscribirse a consultas es menos eficiente que realizar actualizaciones por lotes cuando administra las suscripciones manualmente.

Para un mejor rendimiento al realizar varios cambios en las suscripciones, use la subscriptions API para actualizar todas las suscripciones en una sola transacción. Para saber cómo, consulte "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.

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