Manage Sync Subscriptions - React Native SDK

Subscribe to a Query

We recommend that you name your subscriptions. This makes finding and managing your subscriptions easier. Subscription names must be unique. Trying to add a subscription with the same name as an existing subscription overwrites the existing subscription.

To subscribe to a query:

1. Query for the objects that you want to read and write.

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

3. Pasa un objeto SubscriptionOptions que contiene 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...
    <></>
  );
};

Most of the time, you should give your subscriptions a name. If you don't, the name is set to 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

• subscribe()

• Opciones de suscripción

• Nulo

Wait for a Query Subscription to Sync

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 por defecto. Una suscripción con el comportamiento FirstTime solo espera que la sincronización termine cuando se crea por primera vez una 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...
    <></>
  );
};

The other supported WaitForSync options are:

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

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

Opcionalmente puedes especificar un valor timeout para limitar cuánto tiempo dura la descarga de la sincronización:

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

Subscriptions persist across user sessions unless you unsubscribe from them. You can unsubscribe from a query's results using 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.

Cuando llamas a unsubscribe(), se elimina la suscripción asociada. Las suscripciones se eliminan por nombre. Si no tienen un nombre, unsubscribe() remueve cualquier query que coincida exactamente con la que llamas en unsubscribe().

The unsubscribe() method returns before objects matching the removed subscription are deleted from the realm. Sync continues in the background based on the new set of subscriptions.

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

• unsubscribe()

Access All Subscriptions

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

• SubscriptionSet

Add a Subscription

In the following example, completed and progressMinutes have been set as queryable fields in an App Services App. In the client code, we create filtered queries and then subscribe to their results:

• Completed tasks

• Tareas completadas que han superado los 120 progressMinutes

Note that useQuery() needs an active subscription to return results. If no subscription has been added yet, useQuery() returns an empty result, which is not a valid query for 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>}
    />
  );
}

Configure a Realm with Initial Subscriptions

You must have at least one subscription before you can read from or write to a Flexible Sync realm. Initial subscriptions let you define subscriptions when you configure a synced realm.

To open a synced realm with initial subscriptions, add an initialSubscriptions property to a RealmProvider's sync configuration.

You can't use the @realm/react library hooks useQuery and useObject when setting initial subscriptions. Instead, use the Realm.js read and write operations.

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>}
    />
  );
}

By default, initial subscriptions are only created the first time a realm is opened. If your app needs to rerun this initial subscription every time the app starts, you can set rerunOnOpen to true. You might need to do this to rerun dynamic time ranges or other queries that require a recomputation of static variables for the subscription.

Referencia de API

• FlexibleSyncConfiguration

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.

You can use subscription state to:

• Trigger error handling

• 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 added the SubscriptionSetState enum that you can use to get the status of a subscription.

Update Subscriptions with a New Query

You can update a named subscription with a new query. To update a subscription's query, pass the new query and a subscription option with the name of the subscription that you want to update to the MutableSubscriptionSet.add() method. Like adding a new subscription, you must update a subscription within a transaction by calling subscriptions.update().

The following example, redefines long-running tasks as any tasks that take more than 180 minutes.

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

Referencia de API

• MutableSubscriptionSet.add()

• SubscripciónSet.update()

• SubscriptionOptions.throwOnUpdate

Eliminar suscripciones

Subscription sets persist across sessions, even if you no longer include the subscription in your code. Subscription information is stored in the synced realm's database file. You must explicitly remove a subscription for it to stop attempting to sync matching data.

Puedes remover suscripciones de las siguientes formas:

• Remueve una sola suscripción con una query específica

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

• Remove all subscriptions to a specific object model

• Remover todas las suscripciones sin nombre

• Remove all subscriptions

When you remove a subscription query, the server also removes synced data from the client device.

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();
});

API Efficiency

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 lograr un mejor rendimiento al realizar cambios en varias suscripciones, utiliza la subscriptions API para actualizar todas las suscripciones en una sola transacción. Para aprender cómo, consulta Administrar suscripciones manualmente.

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.