Gerencie assinaturas Flexible Sync - Swift SDK

Assine tipos de objetos

Os conjuntos de assinaturas são baseados no tipo de objeto. Você pode ter várias assinaturas se tiver muitos tipos de objetos do Realm. Você também pode ter várias assinaturas no mesmo tipo de objeto.

No entanto, observe o seguinte se você usar relacionamentos ou objetos assimétricos em seu aplicativo:

Permissões

As assinaturas funcionam lado a lado com as permissões para determinar quais dados devem ser sincronizados com seu aplicativo cliente. O aplicativo cliente só vê o subconjunto de dados que corresponde às suas assinaturas, que também corresponde às permissões do usuário conectado.

Esta página detalha como gerenciar assinaturas de clientes para Flexible Sync. Para obter informações sobre a configuração de permissões para o Flexible Sync, consulte: Regras do Flexible Sync & Permissions (Permissões do Flexible Sync).

Inscrever-se em uma query

Com um usuário autenticado e uma configuração Flexible Sync, você pode abrir um realm sincronizado e uma query para os objetos que deseja ler e gravar. Você pode .subscribe() a essa query para criar uma assinatura Flexible Sync para objetos correspondentes à query:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Task.self)
    .where { $0.progressMinutes >= 60 }.subscribe()
// Go on to work with subscribed results

Isso cria uma assinatura sem nome e a adiciona ao MutableSubscriptionSet, semelhante à criação manual de uma assinatura.

Assinar uma query com um nome de assinatura

Se seu aplicativo funcionar com várias assinaturas ou se você quiser atualizar uma assinatura, talvez queira adicionar um nome ao assinar uma query.

Posteriormente, você poderá usar esse nome para atualizar a query de uma assinatura, verificar se há uma assinatura por nome ou remover a query por nome.

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Aguarde uma assinatura de query para sincronizar

Quando você assina o conjunto Results de uma query, esse conjunto não contém objetos até que seja sincronizado. Se o seu aplicativo criar objetos, talvez você não precise baixar os dados sincronizados antes de o usuário trabalhar com ele. No entanto, se seu aplicativo exigir dados do servidor antes que o usuário possa trabalhar com ele, você pode especificar que uma assinatura deve ser waitForSync:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Team.self)
    .where { $0.members.contains("Bob Smith") }
    .subscribe(
        name: "bob_smith_teams",
        waitForSync: .onCreation)
// After waiting for sync, the results set contains all the objects
// that match the query - in our case, 1
print("The number of teams that have Bob Smith as a member is \(results.count)")

Esta opção utiliza o enum RLMWaitForSyncMode, cujos casos são:

• .onCreation: Espere para baixar objetos correspondentes quando seu aplicativo criar a assinatura. Caso contrário, volte sem aguardar novos downloads. O aplicativo deve ter uma conexão com a internet na primeira vez que você adicionar a assinatura.

• .always: Espere para baixar objetos correspondentes quando .subscribe() for executado. O aplicativo deve ter uma conexão de internet quando o .subscribe() for executado.

• .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 abrir offline em inicializações subsequentes usando credenciais armazenadas em cache.

Opcionalmente, você pode especificar um valor timeout do tipo TimeInterval.

Cancelar assinatura de uma query

Você pode cancelar a assinatura do conjunto Results de uma consulta usando a API .unsubscribe() :

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Task.self).where { $0.completed == false }.subscribe()
// Go on to work with subscribed results.
// Later...
results.unsubscribe()

Isso remove a assinatura do MutableSubscriptionSet, de forma semelhante à remoção manual de uma assinatura.

Um conjunto de Results ainda pode conter objetos depois de chamar .unsubscribe() se existir outra assinatura que contenha objetos sobrepostos.

Chamar .unsubscribe() não espera que os objetos sejam removidos do domínio. Não há API para esperar que .unsubscribe() sincronize com o servidor.

Assinar uma query confinada ao ator

Você pode se inscrever em uma query confinada ao ator no MainActor:

let realm = try await Realm(configuration: flexSyncConfig, actor: MainActor.shared)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Ou assine uma query sobre um ator personalizado:

let realm = try await Realm(configuration: flexSyncConfig, actor: CustomGlobalActor.shared)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Para obter mais informações sobre realms confinados a atores, consulte Use Realm with Actors - Swift SDK.

Adicionar uma assinatura

Adicione uma assinatura em um bloco de atualização de assinaturas. Você anexa cada nova assinatura às assinaturas do Realm do cliente.

let realm = try await getRealmWithSingleSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithSingleSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
       subscriptions.append(
          QuerySubscription<Team> {
             $0.teamName == "Developer Education"
          })
    }
    return realm
}

Você pode adicionar várias assinaturas dentro de um bloco de atualização de assinatura, incluindo assinaturas de diferentes tipos de objetos.

let realm = try await getRealmWithMultipleSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithMultipleSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.append(
            QuerySubscription<Task>(name: "completed-tasks") {
                 $0.completed == true
        })
        subscriptions.append(
            QuerySubscription<Team> {
              $0.teamName == "Developer Education"
        })
    }
    return realm
}

var flexSyncConfig = user.flexibleSyncConfiguration(initialSubscriptions: { subs in
    subs.append(
        QuerySubscription<Team> {
               $0.teamName == "Developer Education"
            })
})

// Set the date a week ago and the date a week from now, as those are the dates we'll use
// in the Flexible Sync query. `rerunOnOpen` lets the app recalculate this query every
// time the app opens.
let secondsInAWeek: TimeInterval = 604800
let dateLastWeek = (Date.now - secondsInAWeek)
let dateNextWeek = (Date.now + secondsInAWeek)
var flexSyncConfig = user.flexibleSyncConfiguration(initialSubscriptions: { subs in
    subs.append(
        QuerySubscription<Task> {
            $0.dueDate > dateLastWeek && $0.dueDate < dateNextWeek
        })
}, rerunOnOpen: true)

let realm = try await subscribeToObjectsOfAType()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func subscribeToObjectsOfAType() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.append(QuerySubscription<Team>(name: "all_teams"))
    }
    XCTAssertEqual(subscriptions.count, 1) // :remove
    return realm
}

let realm = try await checkAndAddSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func checkAndAddSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    let foundSubscription = subscriptions.first(named: "user_team")
    try await subscriptions.update {
        if foundSubscription != nil {
            foundSubscription!.updateQuery(toType: Team.self, where: {
                 $0.teamName == "Developer Education"
            })
        } else {
            subscriptions.append(
                QuerySubscription<Team>(name: "user_team") {
                  $0.teamName == "Developer Education"
               })
        }
    }
    return realm
}

Aguarde as alterações na assinatura para sincronizar

Atualizar o conjunto de assinaturas localmente é apenas um componente da alteração de uma assinatura. Após a alteração da assinatura local, o território sincroniza com o servidor para resolver quaisquer atualizações nos dados devido à alteração da assinatura. Isso pode significar adicionar ou remover dados do domínio sincronizado.

let subscriptions = realm.subscriptions
subscriptions.update({
   subscriptions.append(
      QuerySubscription<Task> {
         $0.assignee == "John Doe"
      })
}, onComplete: { error in // error is optional
    if error == nil {
       // Flexible Sync has updated data to match the subscription
    } else {
       // Handle the error
    }
 })

@MainActor
func changeSubscription() async throws {
   let subscriptions = realm.subscriptions
   try await subcriptions.update {
      subscriptions.remove {
         QuerySubscription<Task> {
            $0.assignee == "Joe Doe"
         }
      }
   }
}

Estado do conjunto de assinaturas

Use a propriedade SubscriptionSet.state para ler o estado atual do conjunto de assinaturas.

O estado superseded é um SyncSubscriptionState que pode ocorrer quando outro tópico atualiza uma assinatura em uma instância diferente do conjunto de assinatura. Se o estado se tornar superseded, você deverá obter uma nova instância do conjunto de assinaturas antes de poder atualizá-lo.

Atualizar assinaturas com uma nova query

Você pode atualizar a query de uma assinatura usando updateQuery. Neste exemplo, procuramos uma assinatura que corresponda à nossa query e a atualizamos com uma nova query.

let realm = try await getRealmWithUpdatedSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithUpdatedSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        if let foundSubscription = subscriptions.first(ofType: Team.self, where: {
            $0.teamName == "Developer Education"
        }) {
            foundSubscription.updateQuery(toType: Team.self, where: {
                $0.teamName == "Documentation"
            })
        }
    }
    return realm
}

Você também pode pesquisar uma assinatura pelo nome . Neste exemplo, pesquisamos uma query de assinatura por nome e a atualizamos com uma nova query.

let realm = try await getRealmWithUpdatedSubscriptionName()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithUpdatedSubscriptionName() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    let foundSubscription = subscriptions.first(named: "user-team")
    try await subscriptions.update {
        foundSubscription?.updateQuery(toType: Team.self, where: {
             $0.teamName == "Documentation"
        })
    }
    return realm
}

Remover subscrições

Para remover assinaturas, você pode:

• Remover uma query de assinatura única

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

• Remover todas as assinaturas sem nome

• Remover todas as assinaturas

Quando você remove uma query de assinatura, o Realm remove assíncronamente os dados sincronizados que corresponderam à query do dispositivo cliente.

let realm = try await getRealmAfterRemovingSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    // Look for a specific subscription, and then remove it
    let foundSubscription = subscriptions.first(named: "docs-team")
    try await subscriptions.update {
        subscriptions.remove(foundSubscription!)
    }
    // Or remove a subscription that you know exists without querying for it
    try await subscriptions.update {
        subscriptions.remove(named: "existing-subscription")
    }
    return realm
}

let realm = try await getRealmAfterRemovingAllSubscriptionsToAnObjectType()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingAllSubscriptionsToAnObjectType() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.removeAll(ofType: Team.self)
    }
    return realm
}

let realm = try await Realm(configuration: flexSyncConfig)
// Add 2 subscriptions, one named and one unnamed.
let results = try await realm.objects(Team.self).where { $0.teamName == "Developer Education" }.subscribe(name: "team_developer_education")
let results2 = try await realm.objects(Task.self).where { $0.completed == false }.subscribe()
// Later, remove only the unnamed one
let subscriptions = realm.subscriptions
try await subscriptions.update {
    subscriptions.removeAll(unnamedOnly: true)
}

let realm = try await getRealmAfterRemovingAllSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingAllSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.removeAll()
    }
    return realm
}

Eficiência da API

Adicionar 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. A cada .subscribe(), o Swift SDK abre um novo bloco de atualização. Para obter melhor desempenho adicionando várias assinaturas, use a API subscriptions.update descrita na seção 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 Flexible Sync 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 assinatura é de 256 kB. Exceder esse limite resulta em um erro de LimitsExceeded.