Administrar suscripciones de sincronización - SDK de React Native

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. Si intenta agregar una suscripción con el mismo nombre que una ya existente, esta se sobrescribirá.

Para suscribirse a una consulta:

1. Consulta los objetos que quieres leer y escribir.

2. Llame a 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().

import React, {useEffect, useState} from 'react';
import {useRealm, useQuery} from '@realm/react';
import {View, Text, FlatList} from 'react-native';
import {Bird} from '../../models';
import {Subscription} from 'realm/dist/bundle';
export const BasicSubscription = () => {
  const realm = useRealm();
  // Get all local birds that have not been seen yet.
  const seenBirds = useQuery(Bird, collection =>
    collection.filtered('haveSeen == true'),
  );
  const [seenBirdsSubscription, setSeenBirdsSubscription] =
    useState<Subscription | null>();
  useEffect(() => {
    // Create an async function so that we can `await` the
    // promise from `.subscribe()`.
    const createSubscription = async () => {
      await seenBirds.subscribe({
        name: 'Birds I have seen',
      });
    };
    createSubscription().catch(console.error);
    // Get the subscription...
    const subscription = realm.subscriptions.findByName('Birds I have seen');
    // ... and set it to a stateful variable or manage it in `useEffect`.
    setSeenBirdsSubscription(subscription);
  }, []);
  return (
    // Work with the subscribed results list or modify the subscription...
    <></>
  );
};

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

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.

Referencia de API

• suscribir()

• Opciones de suscripción

• nulo

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

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 React, {useEffect, useState} from 'react';
import {BSON, WaitForSync} from 'realm';
import {useRealm, useQuery} from '@realm/react';
import {View, Text, Button, TextInput, FlatList} from 'react-native';
import {Bird} from '../../models';
import {Subscription} from 'realm/dist/bundle';
export const WaitFirstTime = () => {
  const realm = useRealm();
  const [birdName, setBirdName] = useState('Change me!');
  // Get local birds that have been marked as "haveSeen".
  const seenBirds = useQuery(Bird, collection =>
    collection.filtered('haveSeen == true'),
  );
  const [seenBirdsSubscription, setSeenBirdsSubscription] =
    useState<Subscription | null>();
  useEffect(() => {
    const createSubscription = async () => {
      // Only wait for sync to finish on the initial sync.
      await seenBirds.subscribe({
        behavior: WaitForSync.FirstTime,
        name: 'First time sync only',
      });
    };
    createSubscription().catch(console.error);
    // Get the subscription...
    const subscription = realm.subscriptions.findByName('First time sync only');
    // ... and set it to a stateful variable or manage it in `useEffect`.
    setSeenBirdsSubscription(subscription);
  }, []);
  return (
    // Work with the subscribed results list or modify the subscription...
    <></>
  );
};

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:

export const AlwaysWait = () => {
  const realm = useRealm();
  // Get all local birds that have not been seen yet.
  const unSeenBirds = useQuery(Bird, collection =>
    collection.filtered('haveSeen == false'),
  );
  const [unSeenBirdsSubscription, setUnseenBirdsSubscription] =
    useState<Subscription | null>();
  useEffect(() => {
    const createSubscription = async () => {
      // Add subscription with timeout.
      // If timeout expires before sync is completed, currently-downloaded
      // objects are returned and sync download continues in the background.
      await unSeenBirds.subscribe({
        behavior: WaitForSync.Always,
        name: 'Always wait',
        timeout: 500,
      });
    };
    createSubscription().catch(console.error);
    // Get the subscription...
    const subscription = realm.subscriptions.findByName('Always wait');
    // ... and set it to a stateful variable or manage it in `useEffect`.
    setUnseenBirdsSubscription(subscription);
  }, []);
  return (
    // Work with the subscribed results list or modify the subscription...
    <></>
  );
};

Referencia de API

• waitForSync

Darse de baja de una consulta

Las suscripciones se mantienen entre sesiones de usuario a menos que las canceles. Puedes cancelar la suscripción a los resultados de una consulta usando 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.

import React, {useEffect, useState} from 'react';
import {useRealm, useQuery} from '@realm/react';
import {View, Text, Button} from 'react-native';
import {Bird} from '../../models';
import {Subscription} from 'realm/dist/bundle';
export const Unsubscribe = () => {
  const realm = useRealm();
  const birds = useQuery(Bird);
  const unsubscribeFromQuery = () => {
    birds.unsubscribe();
  };
  return (
    <View>
      <Button
        title="Unsubscribe"
        onPress={() => {
          unsubscribeFromQuery();
        }}
      />
    </View>
  );
};

Referencia de API

• cancelar suscripción()

Acceder a todas las suscripciones

Dentro de un RealmProvider configurado para Flexible Sync, puedes acceder a un SubscriptionSet. Un SubscriptionSet es una colección de todas las suscripciones de tu aplicación.

import React, {useEffect, useState} from 'react';
import {Text, FlatList} from 'react-native';
import {useRealm, useQuery} from '@realm/react';
import {Bird} from '../Models/Bird';
function SubscriptionManager() {
  const realm = useRealm();
  // Pass object model to useQuery and filter results.
  // This does not create a subscription.
  const seenBirds = useQuery(Bird, birds => {
    return birds.filtered('haveSeen == true');
  });
  const [subscriptions, setSubcriptions] = useState<
    App.Sync.SubscriptionSet | undefined
  >();
  useEffect(() => {
    const createSubscription = async () => {
      // Create subscription for filtered results.
      await realm.subscriptions.update(mutableSubs => {
        mutableSubs.add(seenBirds, {name: 'seen birds'});
      });
    };
    createSubscription().catch(console.error);
    // Set to state variable.
    setSubcriptions(realm.subscriptions);
  }, []);
  return (
    <FlatList
      data={subscriptions}
      keyExtractor={subscription => subscription.id.toString()}
      renderItem={({item}) => <Text>{item.name}</Text>}
    />
  );
}

Referencia de API

• Conjunto de suscripciones

Añadir una suscripción

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

Tenga en cuenta que useQuery() necesita una suscripción activa para devolver resultados. Si aún no se ha añadido ninguna suscripción, useQuery() devuelve un resultado vacío, que no es un query válido para MutableSubscriptionSet.add().

import React, {useEffect} from 'react';
import {Text, FlatList} from 'react-native';
import {useRealm, useQuery} from '@realm/react';
function SubscriptionManager() {
  const realm = useRealm();
  const seenBirds = useQuery(Bird, birds => {
    return birds.filtered('haveSeen == true');
  });
  useEffect(() => {
    realm.subscriptions.update(
      (mutableSubs: Realm.App.Sync.MutableSubscriptionSet) => {
        // Create subscription for filtered collection.
        mutableSubs.add(seenBirds, {name: 'seenBirds'});
      },
    );
  });
  return (
    <FlatList
      data={seenBirds}
      keyExtractor={item => item._id.toString()}
      renderItem={({item}) => <Text>{item._id.toString()}</Text>}
    />
  );
}

Configurar un reino con suscripciones iniciales

Debe tener al menos una suscripción para poder leer o escribir en un dominio de sincronización flexible. Las suscripciones iniciales le permiten definir suscripciones al configurar un dominio sincronizado.

Para abrir un reino sincronizado con suscripciones iniciales, agregue una propiedad initialSubscriptions a la configuración de sincronización de un RealmProvider.

No se pueden usar los @realm/react ganchos useQuery y de la biblioteca useObject al configurar las suscripciones iniciales. En su lugar, se deben usar las operaciones de lectura y escritura de Realm.js.

import React from 'react';
import {AppProvider, UserProvider} from '@realm/react';
// get realm context from createRealmContext()
import {RealmContext} from '../RealmConfig';
import {Text, FlatList} from 'react-native';
const {RealmProvider, useQuery} = RealmContext;
function AppWrapper() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          sync={{
            flexible: true,
            initialSubscriptions: {
              update(subs, realm) {
                subs.add(realm.objects('Turtle'));
              },
            },
            onError: console.log,
          }}>
          <SubscriptionManager />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
}
function SubscriptionManager() {
  // Pass object model to useQuery to get all objects of type `Turtle`.
  // These results automatically update with changes from other devices
  // because we created a subscription with `initialSubscriptions`.
  const allTurtles = useQuery('Turtle');
  return (
    <FlatList
      data={allTurtles}
      keyExtractor={turtle => turtle._id.toString()}
      renderItem={({item}) => <Text>{item._id}</Text>}
    />
  );
}

De forma predeterminada, las suscripciones iniciales solo se crean la primera vez que se abre un dominio. 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 un nuevo cálculo de las variables estáticas de la suscripción.

Referencia de API

• Configuración de sincronización flexible

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.

import React, {useEffect} from 'react';
import {Text, View} from 'react-native';
import {useRealm, useQuery} from '@realm/react';
import {Bird} from '../Models/Bird';
function SubscriptionManager() {
  const realm = useRealm();
  const seenBirds = useQuery(Bird, birds => {
    return birds.filtered('haveSeen == true');
  });
  useEffect(() => {
    realm.subscriptions.update(
      (mutableSubs: Realm.App.Sync.MutableSubscriptionSet) => {
        // Create subscription for filtered collection.
        mutableSubs.add(seenBirds, {name: 'seenBirds'});
      },
    );
  });
  // Returns state of all subscriptions, not individual subscriptions.
  // In this case, it's just the subscription for `Bird` objects where
  // `haveSeen` is true.
  const allSubscriptionState = realm.subscriptions.state;
  return (
    <View>
      <Text >
        Status of all subscriptions: {allSubscriptionState}
      </Text>
    </View>
  );
}

Realm.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().

El siguiente ejemplo redefine las tareas de larga ejecución como cualquier tarea que tome más de 180 minutos.

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

Referencia de API

• Conjunto de suscripciones mutables.add()

• SubscripciónSet.update()

• Opciones de suscripción.throwOnUpdate

Eliminar suscripciones

Los conjuntos de suscripciones persisten entre sesiones, incluso si ya no se incluye la suscripción en el código. La información de la suscripción se almacena en el archivo de base de datos del dominio sincronizado. Debe eliminar explícitamente una suscripción para que deje de intentar sincronizar los datos coincidentes.

Puedes remover suscripciones de las siguientes formas:

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

Los ejemplos de esta sección suponen que está trabajando con @realm/react y un RealmProvider configurado correctamente.

import {useEffect} from 'react';
// get realm context from createRealmContext()
import {RealmContext} from '../RealmConfig';
const {useRealm} = RealmContext;
function SubscriptionManager() {
  const realm = useRealm();
  useEffect(() => {
    realm.subscriptions.update(mutableSubs => {
      // Remove subscription for object type `Turtle`,
      // which we added in `initialSubscriptions`.
      mutableSubs.removeByObjectType('Turtle');
    });
  });
  return (
    // ...
  );
}

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