Gerenciar assinaturas de sincronização - React Native SDK

Inscrever-se em uma query

Recomendamos que você nomeie suas assinaturas. Isso torna mais fácil encontrar e gerenciar suas assinaturas. Os nomes das assinaturas devem ser exclusivos. Tentar adicionar uma assinatura com o mesmo nome de uma assinatura existente substitui a assinatura existente.

Para assinar uma query:

1. Consulte os objetos que você deseja ler e gravar.

2. Ligue para subscribe() nos resultados da query para criar uma assinatura de sincronização para objetos correspondentes à query.

3. Passe um objeto SubscriptionOptions que contenha a propriedade name para 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...
    <></>
  );
};

Na maioria das vezes, você deve dar um nome às suas assinaturas. Caso contrário, o nome está definido como null.

Se você usar filtered() em uma assinatura de query sem nome, o identificador de assinatura será baseado na query filtered. Isto significa que toda vez que sua string de query for alterada, o subscribe() criará uma nova assinatura.

Referência da API

• subscribe()

• Opções de assinatura

• zero

Aguarde uma assinatura de query para sincronizar

Quando você assina os resultados de uma query, os resultados não contêm objetos até que os dados sincronizados sejam baixados. Quando for necessário aguardar o término do download dos objetos sincronizados, configure a opção waitForSync.

Este exemplo utiliza a opção FirstTime , que é o comportamento padrão. Uma assinatura com comportamento FirstTime somente aguarda a sincronização terminar quando uma assinatura é criada pela primeira vez.

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

As outras opções WaitForSync suportadas são:

• Always: Aguarde o download dos objetos correspondentes toda vez que seu aplicativo for iniciado. O aplicativo deve ter uma conexão com a Internet em cada lançamento.

• Never: Nunca espere para baixar objetos correspondentes. O aplicativo precisa de uma conexão com a Internet para que o usuário se autentique na primeira vez que o aplicativo for iniciado, mas pode ser aberto off-line nas inicializações subsequentes usando credenciais em cache.

Opcionalmente, você pode especificar um valor timeout para limitar quanto tempo o download de sincronização é executado:

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

Referência da API

• Aguarde a sincronização

Cancelar assinatura de uma query

As assinaturas persistem entre as sessões de usuário, a menos que você cancele a assinatura delas. Você pode cancelar a assinatura dos resultados de uma query usando unsubscribe().

Isso remove a assinatura da lista de assinaturas ativas, semelhante à remoção manual de uma assinatura.

Uma lista de resultados ainda pode conter objetos após ligar para unsubscribe() se houver outra assinatura que contenha objetos sobrepostos.

Quando você chama unsubscribe(), a assinatura associada é removida. As assinaturas são removidas por nome. Se eles não tiverem um nome, unsubscribe() remove todas as queries que correspondam exatamente à que você chama unsubscribe().

O método unsubscribe() retorna antes que os objetos correspondentes à assinatura removida sejam excluídos do domínio. A sincronização continua em segundo plano com base no novo conjunto de assinaturas.

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

Referência da API

• unsubscribe()

Acessar todas as assinaturas

Dentro de um RealmProvider configurado para Flexible Sync, você pode acessar um SubscriptionSet. Um conjunto de subscrições é uma coleção de todas as subscrições da sua aplicação.

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

Referência da API

• Conjunto de assinaturas

Adicionar uma assinatura

No exemplo seguinte, completed e progressMinutes foram definidos como campos consultáveis em um aplicativo do App Services. No código do cliente, criamos queries filtradas e, em seguida, assinamos seus resultados:

• Tarefas concluídas

• Tarefas concluídas que assumiram mais de 120 progressMinutes

Observe que useQuery() precisa de uma assinatura ativa para retornar os resultados. Se nenhuma assinatura tiver sido adicionada ainda, useQuery() retornará um resultado vazio, que não é um 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 um domínio com assinaturas iniciais

Você deve ter pelo menos uma assinatura antes de ler ou escrever em um domínio Flexible Sync. As assinaturas iniciais permitem definir assinaturas ao configurar um território sincronizado.

Para abrir um domínio sincronizado com assinaturas iniciais, adicione uma propriedade initialSubscriptions a uma configuração de sincronização do RealmProvider.

Você não pode utilizar os ganchos da biblioteca @realm/react useQuery e useObject ao configurar assinaturas iniciais. Em vez disso, utilize as operações de leitura e escrita do 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>}
    />
  );
}

Por padrão, as assinaturas iniciais são criadas somente na primeira vez que um domínio é aberto. Se seu aplicativo precisar executar novamente essa assinatura inicial toda vez que o aplicativo for iniciado, você poderá definir rerunOnOpen como true. Talvez seja necessário fazer isso para executar novamente intervalos de tempo dinâmicos ou outras queries que exijam um novo cálculo de variáveis estáticas para a assinatura.

Referência da API

• Configuração flexível de sincronização

Verifique o status das assinaturas

Você pode verificar o estado da assinatura para ver se o servidor reconheceu a assinatura e se o dispositivo baixou os dados localmente.

Você pode usar o estado da assinatura para:

• Acione o tratamento de erros

• Mostrar se a transação está pendente ou foi concluída

• Descubra quando um conjunto de assinaturas é substituído e você deve obter uma nova instância do conjunto de assinaturas para gravar uma alteração de assinatura

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 adicionou o enum SubscriptionSetState que você pode usar para obter o status de uma assinatura.

Atualizar assinaturas com uma nova query

Você pode atualizar uma assinatura nomeada com uma nova query. Para atualizar a query de uma assinatura, passe a nova query e uma opção de assinatura com o nome da assinatura que você deseja atualizar para o método MutableSubscriptionSet.add() . Como adicionar uma nova assinatura, você deve atualizar uma assinatura dentro de uma transação ligando para subscriptions.update().

O exemplo a seguir redefine tarefas de longa duração como quaisquer tarefas que levem mais de 180 minutos.

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

Referência da API

• MutableSubscriptionSet.add()

• SubScriptionSet.update()

• SubscriptionOptions.throwOnUpdate

Remover subscrições

Os conjuntos de assinaturas persistem entre sessões, mesmo que você não inclua mais a assinatura em seu código. As informações de assinatura são armazenadas no arquivo de banco de dados da região sincronizada. Você deve remover explicitamente uma assinatura para que pare de tentar sincronizar os dados correspondentes.

Você pode remover assinaturas das seguintes maneiras:

• Remover uma única assinatura com uma query específica

• Remover uma única assinatura com um nome específico

• Remover todas as assinaturas de um modelo de objeto específico

• Remover todas as assinaturas sem nome

• Remover todas as assinaturas

Quando você remove uma query de assinatura, o servidor também remove os dados sincronizados do dispositivo cliente.

Os exemplos desta seção pressupõem que você esteja trabalhando com @realm/react e um RealmProvider configurado corretamente.

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

Eficiência da API

O gerenciamento de várias assinaturas com as APIs subscribe() e unsubscribe() descritas na seção Assinar queries é menos eficiente do que executar atualizações em lote quando você gerencia assinaturas manualmente.

Para obter melhor desempenho ao fazer várias alterações na assinatura, use a API subscriptions para atualizar todas as assinaturas em uma única transação. Para saber como, consulte Gerenciar assinaturas manualmente.

Atualizações de grupo para melhorar o desempenho

Cada transação de escrita para um conjunto de assinaturas tem um custo de desempenho. Se você precisar fazer várias atualizações em um objeto do Realm durante uma sessão, considere manter objetos editados na memória até que todas as alterações sejam concluídas. Isso melhora o desempenho da sincronização, gravando apenas o objeto completo e atualizado em seu domínio, em vez de cada alteração.

Requisitos de inscrição de campos de query indexados

Adicionar um campo de query indexado à sua aplicação pode melhorar o desempenho de queries simples em dados fortemente particionados. Por exemplo, uma aplicação onde as queries mapeiam fortemente os dados para um dispositivo, armazém ou usuário, como user_id == $0, “641374b03725038381d2e1fb”, é uma boa candidata para um campo de query indexado. No entanto, um campo de query indexado tem requisitos específicos para uso em uma inscrição de query:

• O campo de query indexado deve ser usado em todas as inscrições de query. Não pode estar faltando na query.

• O campo de query indexado deve usar uma comparação == ou IN com uma constante pelo menos uma vez na query de inscrição. Por exemplo, user_id == $0, "641374b03725038381d2e1fb" ou store_id IN $0, {1,2,3}.

Opcionalmente, você pode incluir uma comparação AND, desde que o campo consultável indexado seja comparado diretamente com uma constante usando == ou IN pelo menos uma vez. Por exemplo, store_id IN {1,2,3} AND region=="Northeast" ou store_id == 1 AND (active_promotions < 5 OR num_employees < 10).

As consultas inválidas do Flexible Sync em um campo indexado que pode ser consultado incluem consultas em que:

• O campo de consulta indexado não utiliza AND com o resto da consulta. Por exemplo store_id IN {1,2,3} OR region=="Northeast" é inválido porque usa OR em vez de AND. Da mesma forma, store_id == 1 AND active_promotions < 5 OR num_employees < 10 é inválido porque o AND só se aplica ao termo ao lado, não à consulta inteira.

• O campo de consulta indexado não é utilizado em um operador de igualdade. Por exemplo store_id > 2 AND region=="Northeast" é inválido porque utiliza apenas o operador > com o campo de consulta indexado e não tem uma comparação de igualdade.

• A query está totalmente ausente do campo de query indexado. Por exemplo, region=="Northeast ou truepredicate são inválidos porque não contêm o campo de query indexado.

Operadores de consulta não suportados na sincronização flexível

A Flexible Sync tem algumas limitações ao usar operadores RQL. Quando você escreve a assinatura de consulta que determina quais dados sincronizar, o servidor não oferece suporte a esses operadores de consulta. No entanto, você ainda pode usar toda a gama de recursos de RQL para consultar o conjunto de dados sincronizado no aplicativo cliente.

Queries que não diferenciam maiúsculas de minúsculas ([c]) não podem usar índices de forma eficaz. Sendo assim, queries que não diferenciam maiúsculas de minúsculas não são recomendadas, pois podem causar problemas de desempenho.

A sincronização flexível suporta apenas @count para campos de array.

Listar queries

A sincronização flexível oferece suporte às listas de query usando o operador IN .

Você pode consultar uma lista de constantes para ver se ela contém o valor de um campo de consulta:

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

Se um campo de query tiver um valor de array, você poderá consultar para ver se ele contém um 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 incorporados ou vinculados

A sincronização Flexível não oferece suporte à consulta de propriedades em objetos ou links embarcados. Por exemplo, obj1.field == "foo".

Limite de tamanho da query

O limite de tamanho para qualquer assinatura de query em seu conjunto de assinaturas é de 256 kB. Exceder esse limite resulta em um erro de LimitsExceeded.