Flexible Sync サブスクリプションの管理 - .NET SDK

サブスクリプションを追加する

Realm から読み取りまたは書込み (write) する前に、少なくとも 1 つのサブスクリプションが必要です。 初期化後にサブスクリプションを追加するのではなく、Flexible Sync を構成するときに 1 つ以上の初期サブスクリプションを作成する必要があります。

var config = new FlexibleSyncConfiguration(app.CurrentUser)
{
    PopulateInitialSubscriptions = (realm) =>
    {
        var myItems = realm.All<Item>().Where(n => n.OwnerId == myUserId);
        realm.Subscriptions.Add(myItems);
    }
};
// The process will complete when all the user's items have been downloaded.
var realm = await Realm.GetInstanceAsync(config);

var query = realm.All<Team>().Where(t => t.Name == "MyTeam");
await query.SubscribeAsync();
// you can also pass a SubscriptionOptions object:
var query2 = realm.All<Team>().Where(t => t.Name == "DevelopmentTeam");
await query2.SubscribeAsync(
    new SubscriptionOptions() { Name = "devTeamSubscription" });

realm.Subscriptions.Update(() =>
{
    // Subscribe to all long running items, and name
    // the subscription "longRunningItems"
    var longRunningTasksQuery = realm.All<Item>()
        .Where(t => t.ProgressMinutes > 120);
    realm.Subscriptions.Add(longRunningTasksQuery,
        new SubscriptionOptions() { Name = "longRunningItems" });
    // Subscribe to all of Ben's Items
    realm.Subscriptions.Add(realm.All<Item>()
        .Where(t => t.Owner == "Ben"));
    // Subscribe to all Teams, name the subscription
    // 'teamsSubscription', and throw an error if
    // this subscription name already exists.
    realm.Subscriptions.Add(realm.All<Team>(),
        new SubscriptionOptions()
        { Name = "teams", UpdateExisting = false });
});

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

新しいクエリを使用して 名前付きサブスクライブ を更新できます。 サブスクライブのクエリを更新するには、新しいクエリと、更新するサブスクリプションの名前を指定してサブスクライブ オプションをSubscriptionSet.Add()メソッドに渡します。 新しいサブスクライブを追加するのと同様に、 SubscriptionSet.Update()メソッドを呼び出して更新ブロック内でサブスクライブを更新する必要があります。

次の例では、長時間実行されているタスクは、130 分以上かかったタスクであるように再定義されています。

realm.Subscriptions.Update(() =>
{
    var updatedLongRunningTasksQuery = realm.All<Item>()
        .Where(t => t.Status == "completed" && t.ProgressMinutes > 130);
    realm.Subscriptions.Add(updatedLongRunningTasksQuery,
        new SubscriptionOptions() { Name = "longRunningTasks" });
});

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

サブスクリプションセットからサブスクリプションを削除するには、次の操作を実行します。

• 指定されたクエリを使用して単一のサブスクライブを削除

• 指定された名前の単一のサブスクライブを削除

• 指定されたサブスクライブの単一のサブスクライブを削除

• 特定のタイプのすべてのサブスクライブを削除する

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

サブスクリプション クエリを削除すると、サーバーはクライアント デバイスから同期されたデータも削除します。

realm.Subscriptions.Update(() =>
{
    // remove a subscription by it's query
    var query = realm.All<Item>().Where(i => i.Owner == "Ben");
    realm.Subscriptions.Remove(query);
});

realm.Subscriptions.Update(() =>
{
    // remove a named subscription
    var subscriptionName = "longRunningItemsSubscription";
    realm.Subscriptions.Remove(subscriptionName);
});

realm.Subscriptions.Update(() =>
{
    // remove all subscriptions of the "Team" Class Name
    realm.Subscriptions.RemoveAll("Team");
    // Alernatively, remove all subscriptions of the "Team" object type
    realm.Subscriptions.RemoveAll<Team>();
});

realm.Subscriptions.Update(() =>
{
    // remove all subscriptions, including named subscriptions
    realm.Subscriptions.RemoveAll(true);
});

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

アップデート ブロック内でサブスクリプションセットをミューテーションすることは、サブスクリプション変更の一部に相当します。 ローカル サブスクリプションの変更後、Realm はサーバーと同期して、サブスクリプションの変更によるデータの更新を解決します。 これは、同期された Realm からデータを追加または削除することを意味します。

SubscriptionSet.WaitForSynchronizationAsync()メソッドを使用して、サーバーがこのサブスクライブのセットを確認するのを待機します。 サーバーが変更を拒否した場合、 SubscriptionSetStateはエラー状態になり、例外がスローされます。

次の場合、例外が発生する可能性があります。

• サポートされていないクエリは にサブスクライブされます。 サポートされていないクエリをサブスクライブすると、同期が一時停止されます。 同期を再開するには、サポートされていないクエリを削除します。

• サブスクライブに一致しないオブジェクトの追加など、無効なアクションを実行している。 これにより、クライアント リセットがトリガーされます。データが Realm から削除され、セット内にサブスクライブなしでデータの新しいコピーが作成されます。

try
{
    await realm.Subscriptions.WaitForSynchronizationAsync();
}
catch (SubscriptionException ex)
{
    // do something in response to the exception or log it
    Console.WriteLine($@"The subscription set's state is Error and synchronization is paused:  {ex.Message}");
}

サブスクリプション状態

サブスクリプションセットの現在の状態を読み取るには、 SubscriptionSet.Stateプロパティを使用します。

Superseded状態はSubscriptionSetStateであり、サブスクリプションセットの別のインスタンスで別のスレッドがサブスクリプションを更新するときに発生する可能性があります。 状態がSupersededになった場合は、更新する前にサブスクライブ セットの新しいインスタンスを取得する必要があります。

インデックス付きクエリ可能なフィールドのサブスクリプション要件

インデックス付きのクエリ可能なフィールドをアプリに追加すると、厳密にパーティション化されたデータに対する単純なクエリのパフォーマンスが向上します。 たとえば、クエリがデバイス、ストア、またはユーザーにデータを厳密にマッピングするアプリ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 エラー が発生します。