同期サブスクリプションの管理 - Kotlin SDK

オブジェクト タイプへのサブスクライブ

サブスクリプション セットはオブジェクトタイプに基づいています。 Realm オブジェクトのタイプが多い場合は、複数のサブスクリプションがあることがあります。 同じオブジェクトタイプに対して複数のサブスクライブを設定することもできます。

ただし、アプリ内でリンクされたオブジェクト、非対称オブジェクト、または地理空間データを使用する場合は、追加情報について次のセクションを参照してください。

最初のサブスクリプション

Realm から読み取りまたは書込み (write) する前に、少なくとも 1 つのサブスクリプションが必要です。

クエリにサブスクライブ

クエリに.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()

サブスクリプションの変更が同期されるまで待機する

サブスクリプション セットへの更新をローカルに書き込むことは、サブスクリプション変更の 1 つの要素のみです。 ローカル サブスクリプションの変更後、クライアントはサーバーと同期して、サブスクリプションの変更によるデータの更新を解決します。 これは、同期された Realm からデータを追加または削除することを意味します。

SyncConfiguration.waitForInitial remoteData()の使用 ビルダ メソッドを使用して、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.rateプロパティを使用します。

SUPERCEDED （旧 状態がSUPERCEDEDになった場合は、サブスクライブセットの新しいインスタンスを取得した後に、サブスクライブセットに書き込む必要があります。

新しいクエリによるサブスクリプションの更新

SubscriptionSet.update() を使用してサブスクライブを更新できます。

この例ではMutableSubscriptionSet.add()を使用します。 "bob_smith_teams"という名前のサブスクライブのクエリを更新します。 add()でサブスクリプションを更新するには、 updateExistingパラメータをtrueに設定する必要があります。

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

サブスクリプションの削除

サブスクリプションを削除するには、次の方法があります。

• 1 つのサブスクライブ クエリを削除

• 特定のオブジェクトタイプへのすべてのサブスクライブを削除

• すべてのサブスクライブを削除

• 名前のないサブスクライブをすべて削除します

サブスクリプション クエリを削除すると、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”など）は、インデックス付きクエリ可能なフィールドの候補となります。 ただし、インデックス付きのクエリ可能なフィールドには、クエリ サブスクリプションで使用するための特定の要件があります。

• インデックス付きクエリ可能なフィールドは、すべてのサブスクライブ クエリで使用する必要があります。 クエリから欠落することはできません。

• インデックス付きクエリ可能なフィールドは、サブスクライブ クエリで少なくとも 1 回、定数に対して==またはINの比較を使用する必要があります。 たとえば、 user_id == $0, "641374b03725038381d2e1fb"やstore_id IN $0, {1,2,3}などです。

オプションとして、インデックス付きクエリ可能なフィールドが==またはINを少なくとも 1 回使用して定数と直接比較される限り、 AND比較を含めることができます。 たとえば、 store_id IN {1,2,3} AND region=="Northeast"やstore_id == 1 AND (active_promotions < 5 OR num_employees < 10)などです。

インデックス付きクエリ可能なフィールドに対する無効なFlexible Sync クエリには、次のクエリが含まれます。

• インデックス付きクエリ可能なフィールドは、クエリの残りの部分で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は、インデックス付きクエリ可能なフィールドが含まれていないため無効です。

Flexible Sync でサポートされていないクエリ演算子

RQL 演算子を使用する場合、Flexible Sync にはいくつかの制限があります。 同期するデータを決定するクエリ サブスクリプションを書込む場合、サーバーはこれらのクエリ演算子をサポートしていません。 ただし、RQL 機能の全範囲を使用して、クライアント アプリケーション内の同期されたデータセットをクエリすることはできます。

大文字と小文字を区別しないクエリ（ [c] ）は、インデックスを効果的に使用できません。 その結果、大文字と小文字を区別しないクエリはパフォーマンスの問題を引き起こす可能性があるため、推奨されません。

Flexible Sync は、配列フィールドの@countのみをサポートします。

クエリをリストする

Flexible Sync は、 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"

埋め込みオブジェクトまたはリンクされたオブジェクト

Flexible Sync は、 埋め込みオブジェクトまたはリンク のプロパティに対するクエリをサポートしていません。 たとえば、 obj1.field == "foo" 。

クエリ サイズの制限

サブスクリプションセット内の特定のクエリ サブスクライブのサイズ制限は256 kBです。 この制限を超えると、 LimitsExceeded エラー が発生します。

API 効率

「クエリへのサブスクライブ」セクションで説明されている.subscribe() API を使用して複数のサブスクリプションを管理する場合、 サブスクリプション セット API を通じてサブスクリプションを手動で管理する場合、バッチ更新を実行するより効率が低くなります。 複数のサブスクリプション変更を行う際のパフォーマンスを向上させるには、「サブスクリプションの手動管理」セクションで説明されているsubscriptions.update API を使用します。

パフォーマンス向上のためのグループ更新

サブスクリプションセットのすべての書込みトランザクション (write transaction) にはパフォーマンス コストがかかります。 セッション中に Realm オブジェクトを複数更新する必要がある場合は、すべての変更が完了するまで編集されたオブジェクトをメモリ内に保持することを検討してください。 これにより、すべての変更ではなく、完全で更新されたオブジェクトのみが Realm に書き込まれるため、同期のパフォーマンスが向上します。