Manage Sync Subscriptions - Kotlin SDK

Subscribe to Object Types

Subscription sets are based on object type. You might have multiple subscriptions if you have many types of Realm objects. You can also have multiple subscriptions on the same object type.

However, if you use linked objects, asymmetric objects, or geospatial data in your app, refer the following sections for additional information:

Initial Subscriptions

Debes tener al menos una suscripción antes de poder leer o guardar en el realm.

Subscribe to a Query

You can .subscribe() to a query to create a subscription for objects matching a specific query:

// Subscribe to a specific query
val realmResults = realm.query<Task>("progressMinutes >= $0", 60)
    .subscribe()
// Subscribe to all objects of a specific type
val realmQuery = realm.query<Team>()
realmQuery.subscribe()

Esto crea una suscripción sin nombre y la agrega MutableSubscriptionSet a, en lugar de requerir que agregue manualmente la suscripción al conjunto de suscripciones.

// Add a subscription named "team_developer_education"
val results = realm.query<Team>("teamName == $0", "Developer Education")
    .subscribe("team_developer_education")

Update a Query Subscription

You can update a named query subscription with a new query by setting updateExisting to true:

// Create a subscription named "bob_smith_teams"
val results = realm.query<Team>("$0 IN members", "Bob Smith")
    .subscribe("bob_smith_teams")
// Add another subscription with the same name with `updateExisting` set to true
// to replace the existing subscription
val updateResults =
        realm.query<Team>("$0 IN members AND teamName == $1", "Bob Smith", "QA")
            .subscribe("bob_smith_teams", updateExisting = true)

Esto actualiza la suscripción automáticamente, en lugar de requerir que se actualice manualmente la suscripción en el set de suscripción.

Wait for a Query Subscription to Sync

When you subscribe to a query's results set, that set does not contain objects until it syncs. If your app creates objects, you may not need to download synced data before the user works with it. However, if your app requires data from the server before the user can work with it, you can specify that the app should wait for data to sync. This blocks app execution until data syncs from the server.

val results = realm.query<Team>("$0 IN members", "Bob Smith")
    .subscribe("bob_smith_teams", updateExisting = false, WaitForSync.ALWAYS)
// After waiting for sync, the results set contains all the objects
// that match the query - in our case, 1
println("The number of teams that have Bob Smith as a member is ${results.size}")

Esta opción utiliza la enumeración WaitForSync, cuyos valores son:

• FIRST_TIME: (por defecto) Esperar a descargar los objetos coincidentes cuando tu app cree inicialmente la suscripción. De lo contrario, retornar sin esperar nuevas descargas. La aplicación debe tener una conexión a Internet para descargar los datos cuando inicialmente agregues la suscripción. Opcionalmente se puede especificar un valor de timeout.

• ALWAYS: Wait to download matching objects every time the .subscribe() method is called. The app must have an internet connection to download the data. You can optionally specify a timeout value.

• 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 almacenadas en caché.

Add a Subscription

Puedes añadir una suscripción sin nombre o una suscripción con nombre.

To manually create a subscription, add the subscription in a subscriptions update block. You append each new subscription to the client's Realm subscriptions.

realm.subscriptions.update {
    add(
        realm.query<Task>("progressMinutes >= $0",60)
    )
}

You can also specify a subscription name when you create the subscription:

// Add a subscription named "team_dev_ed"
realm.subscriptions.update { realm ->
        add(
            realm.query<Team>("teamName == $0", "Developer Education"),
            name = "team_dev_ed"
        )
    }

// Bootstrap the realm with an initial query to subscribe to
val flexSyncConfig =
    SyncConfiguration.Builder(user, setOf(Team::class, Task::class))
        .initialSubscriptions { realm ->
            add(
                realm.query<Team>("$0 IN members", "Bob Smith"),
                "bob_smith_teams"
            )
        }
        .build()

// `rerunOnOpen` lets the app recalculate this query every time the app opens
val rerunOnOpenConfig =
    SyncConfiguration.Builder(user, setOf(Team::class, Task::class))
        .initialSubscriptions(rerunOnOpen = true) { realm ->
            add(
                realm.query<Team>("completed == $0", false)
            )
        }
        .build()

Espere a que los cambios de suscripción se sincronicen

Writing an update to the subscription set locally is only one component of changing a subscription. After the local subscription change, the client synchronizes with the server to resolve any updates to the data due to the subscription change. This could mean adding or removing data from the synced realm.

Utilice el método de construcción SyncConfiguration.waitForInitialRemoteData() para forzar que su aplicación se bloquee hasta que los datos de suscripción del cliente se sincronicen con el backend antes de abrir el reino:

// Update the list of subscriptions
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Jane Doe"),
        "jane_doe_teams"
    )
}
// Wait for subscription to fully synchronize changes
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))

You can also use SubscriptionSet.waitForSynchronization() to delay execution until subscription sync completes after instantiating a sync connection.

Subscription Set State

Utilice la propiedad SubscriptionSet.state para leer el estado actual del conjunto de suscripciones.

SUPERCEDED (sic -- nótese la ortografía alternativa) es un SubscriptionSetState que puede ocurrir cuando otro hilo escribe una suscripción en una instancia diferente del conjunto de suscripciones. Si el estado se convierte SUPERCEDED en, debe obtener una nueva instancia del conjunto de suscripciones antes de poder escribir en él.

Update Subscriptions with a New Query

Puede actualizar las suscripciones utilizando SubscriptionSet.update().

In this example, we use MutableSubscriptionSet.add(). to update the query for the subscription named "bob_smith_teams". You must set the updateExisting parameter to true to update a subscription with add():

// Create a subscription named "bob_smith_teams"
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams"
    )
}
// Set `updateExisting` to true to replace the existing
// "bob_smith_teams" subscription
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members AND $1 IN members", "Bob Smith", "Jane Doe"),
        "bob_smith_teams", updateExisting = true
    )
}

You cannot update subscriptions created without a name. However, you can look up unnamed subscriptions by their query, remove them from the subscription set, then add a new subscription with an updated query:

// Search for the subscription by query
val subscription =
    realm.subscriptions.findByQuery(
        realm.query<Team>("teamName == $0", "Developer Education")
    )
// Remove the returned subscription and add the updated query
if (subscription != null) {
    realm.subscriptions.update {
        remove(subscription)
        add(
            realm.query<Team>("teamName == $0", "DevEd"),
            "team_developer_education"
        )
    }
}

Eliminar suscripciones

To remove subscriptions, you can:

• Remove a single subscription query

• Remove all subscriptions to a specific object type

• Remove all subscriptions

• Remover todas las suscripciones sin nombre

Cuando elimina una consulta de suscripción, Realm elimina de forma asincrónica los datos sincronizados que coinciden con la consulta del dispositivo cliente.

realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams"
    )
}
// Wait for synchronization to complete before updating subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// Remove subscription by name
realm.subscriptions.update {
    remove("bob_smith_teams")
}

realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams")
}
// Wait for synchronization to complete before updating subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// Remove all subscriptions to type Team
realm.subscriptions.update {
    removeAll(Team::class)
}

// Remove all subscriptions
realm.subscriptions.update {
    removeAll()
}

// Remove all unnamed (anonymous) subscriptions
realm.subscriptions.update {
    removeAll(anonymousOnly = true)
}

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.

API Efficiency

Administrar varias suscripciones con la .subscribe() API (descrita en la sección "Suscribirse a consultas") es menos eficiente que realizar actualizaciones por lotes cuando se administran manualmente mediante la API de conjuntos de suscripciones. Para un mejor rendimiento al realizar cambios en varias suscripciones, utilice la subscriptions.update API (descrita en la sección "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.