托管同步订阅 - Kotlin SDK

订阅对象类型

订阅集基于对象类型。如果您有多种类型的 Realm 对象，则可能有多个订阅。您还可以对同一对象类型拥有多个订阅。

但是，如果您在应用中使用了关联对象、不对称对象或地理空间数据，请参阅以下部分以了解更多信息：

首次订阅

必须至少有一个订阅，才能读取或写入域。

订阅查询

您可以对查询执行.subscribe()操作，为与特定查询匹配的对象创建订阅：

// 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()

这会创建一个未命名的订阅并将其添加到MutableSubscriptionSet中，而不是要求您手动将该订阅添加到订阅集。

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

更新查询订阅

您可以通过将updateExisting设置为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)

这会自动更新订阅，而无需您手动更新订阅集中的订阅。

等待查询订阅同步

当您订阅查询的结果集时，该结果集在同步之前不包含对象。 如果应用程序创建对象，则可能无需在用户使用同步数据之前进行下载。 但是，如果您的应用程序需要来自服务器的数据才能让用户使用，则您可以指定应用程序应等待数据同步。 这会阻止应用执行，直到数据从服务器同步。

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

此选项使用WaitForSync枚举，其值为：

• FIRST_TIME：（默认）在应用程序最初创建订阅时等待下载匹配对象。 否则，无需等待新下载即可返回。 当您最初添加订阅时，应用程序必须具有互联网连接才能下载数据。 您可以选择指定一个timeout值。

• ALWAYS：每次调用.subscribe()方法时等待下载匹配对象。 应用程序必须有互联网连接才能下载数据。 您可以选择指定一个timeout值。

• NEVER：永远不要等待下载匹配对象。 该应用需要互联网连接才能让用户在首次启动应用时进行身份验证，但可以在后续启动时使用缓存的凭证离线打开。

添加订阅

您可以添加未命名订阅或已命名订阅。

要手动创建订阅，请将订阅添加到订阅更新区块中。 您将每个新订阅附加到客户端的 Realm 订阅中。

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

您还可以在创建订阅时指定订阅名称：

// 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()

等待订阅更改同步

在本地写入订阅集的更新只是更改订阅的其中一个组成部分。 本地订阅更改后，客户端会与服务器同步，以解决由于订阅更改而导致的任何数据更新问题。这可能意味着在同步 Realm 中添加或删除数据。

使用SyncConfiguration.waitForInitialRemoteData()构建器方法强制应用程序处于阻塞状态，直到客户端订阅数据同步到后端，然后再打开 Realm：

// 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"))

还可以使用SubscriptionSet.waitForSynchronization()延迟执行，直到实例化同步连接后订阅同步完成。

订阅设置状态

使用SubscriptionSet.state属性读取订阅集的当前状态。

SUPERCEDED （原文如此 — 请注意备用拼写）是另一个线程在订阅集的不同实例上写入订阅时可能发生的 SubscriptionSetState。如果状态变为SUPERCEDED ，则必须先获取订阅集的新实例，然后才能写入。

使用新查询更新订阅

您可以使用SubscriptionSet.update() 更新订阅。

在此示例中，我们使用MutableSubscriptionSet.add() 。更新名为"bob_smith_teams"的订阅的查询。必须将updateExisting参数设置为true才能使用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
    )
}

您无法更新在没有名称的情况下创建的订阅。 但是，您可以通过查询查找未命名的订阅，将其从订阅集中删除，然后使用更新的查询添加新订阅：

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

删除订阅

要删除订阅，您可以：

• 删除单个订阅查询

• 删除特定对象类型的所有订阅

• 删除所有订阅

• 删除所有未命名的订阅

当您删除订阅查询时，Realm 会异步删除与客户端设备中的查询匹配的同步数据。

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

已索引可查询字段订阅的要求

向应用添加索引可查询字段可以提高对强分区数据进行简单查询的性能。例如，如果查询将数据强映射到设备、商店或用户的应用（例如user_id == $0, “641374b03725038381d2e1fb” ，则非常适合使用索引可查询字段。但是，在查询订阅中使用索引化可查询字段有特定的要求：

• 每个订阅查询中都必须使用索引化可查询字段。查询中不能缺少该字段。

• 在订阅查询中，索引化可查询字段必须使用 == 或 IN 进行至少一次针对常量的比较。例如，user_id == $0, "641374b03725038381d2e1fb" 或 store_id IN $0, {1,2,3}。

可以选择包含 AND 比较，前提是使用 == 或 IN 将索引化可查询字段直接与常量进行至少一次比较。例如，store_id IN {1,2,3} AND region=="Northeast" 或 store_id == 1 AND (active_promotions < 5 OR num_employees < 10)。

对索引化可查询字段的无效灵活同步查询包括以下情况的查询：

• 索引化可查询字段未将 AND 与查询的其余部分结合使用。例如，store_id IN {1,2,3} OR region=="Northeast" 是无效的，因为它使用了 OR 而不是 AND。同样，store_id == 1 AND active_promotions < 5 OR num_employees < 10 也是无效的，因为 AND 仅适用于其旁边的词，而不适用于整个查询。

• 索引化可查询字段未在相等运算符中使用。例如，store_id > 2 AND region=="Northeast" 是无效的，因为它仅将 > 运算符与索引化可查询字段结合使用，而没有相等比较。

• 查询中完全没有索引化可查询字段。例如，region=="Northeast 和 truepredicate 都是无效的，因为它们不含索引化可查询字段。

灵活同步中不支持的查询运算符

使用 RQL 操作符时，Flexible Sync有一些限制。当您编写确定要同步哪些数据的查询订阅时，服务器不支持这些查询操作符。但是，您仍然可以使用全部的 RQL 功能来查询客户端应用中的同步数据集。

不区分大小写的查询 ([c]) 无法有效地使用索引。因此，不建议使用不区分大小写的查询，因为它们可能会导致性能问题。

灵活同步仅支持数组字段的 @count。

列出查询

灵活同步支持使用 IN 运算符来查询列表。

可以查询常量列表，查看其中是否包含可查询字段的值：

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

如果某个可查询字段具有数组值，则可以通过查询确定其中是否包含常量值：

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

嵌入式对象或关联对象

灵活同步不支持查询嵌入式对象或链接中的属性。例如，obj1.field == "foo"。

API 效率

通过订阅集 API 手动管理订阅时，使用“订阅查询”部分中描述的.subscribe() API 管理多个订阅比执行批量更新效率低。为了在进行多项订阅更改时获得更好的性能，请使用“手动管理订阅”部分中描述的subscriptions.update API。

更新群组以提高性能

订阅集的每个写入事务都会产生性能成本。如果需要在会话期间对 Realm 对象进行多次更新，请考虑将编辑的对象保留在内存中，直到所有更改完成。这通过仅将完整且更新的对象写入 Realm 而不是每次更改来提高同步性能。