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

クエリにサブスクライブ

サブスクリプションに名前を付けることをお勧めします。 これにより、サブスクライブを見つけて管理しやすくなります。 サブスクリプション名は一意である必要があります。 既存のサブスクリプションと同じ名前のサブスクリプションを追加しようとすると、エラーがスローされます。

クエリをサブスクライブするには、次の手順に従います。

1. 読み取りおよび書込みを対象とするオブジェクトのクエリ。

2. クエリ結果に対して subscribe()を呼び出して、クエリに一致するオブジェクトの同期サブスクリプションを作成します。

3. nameプロパティを含むSubscriptionOptionsオブジェクトをsubscribe()に渡します。

const subOptions = {
  name: "All completed tasks",
};
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe(subOptions);
const completedTasksSubscription = realm.subscriptions.findByName(
  "All completed tasks"
);
// ...work with the subscribed results list or modify the subscription

const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe({ name: "All completed tasks" });
const completedTasksSubscription = realm.subscriptions.findByName(
  "All completed tasks"
);
// ...work with the subscribed results list or modify the subscription

サブスクリプション名なしのクエリへのサブスクライブ

ほとんどの場合、サブスクライブに名前を付ける必要があります。 含めない場合、名前は null に設定されます。

名前なしのクエリ サブスクライブでfiltered()を使用する場合、サブスクリプション識別子はfilteredクエリに基づきます。 つまり、クエリstringが変更されるたびに、subscribe() は新しいサブスクリプションを作成します。

const config = {
  schema: [Task],
  sync: {
    user: app.currentUser,
    flexible: true,
  },
};
const realm = await Realm.open(config);
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe();
// ...work with the subscribed results list

const config: Realm.Configuration = {
  schema: [Task],
  sync: {
    user: app.currentUser!,
    flexible: true,
  },
};
const realm = await Realm.open(config);
const completedTasks = await realm
  .objects(Task)
  .filtered('status == "completed"')
  .subscribe();
// ...work with the subscribed results list

クエリ サブスクリプションが同期するまで待機する

クエリの結果をサブスクライブする場合、同期されたデータがダウンロードされるまで、その結果にはオブジェクトが含まれません。 同期されたオブジェクトのダウンロードが完了するまで待機する必要がある場合は、 waitForSyncを使用します。 サブスクリプションとダウンロードのを処理する方法によって異なる動作を指定できます。

この例では、デフォルトの動作であるFirstTimeオプションを使用しています。 FirstTime動作のサブスクライブは、サブスクリプションが最初に作成されたときにのみ同期が完了することを待機します。

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Only waits for sync to finish on the initial sync.
await completedTasks.subscribe({
  behavior: WaitForSync.FirstTime,
  name: "First time sync only",
});

サポートされているその他のWaitForSyncオプションは次のとおりです。

• Always: アプリを起動するたびに一致するオブジェクトをダウンロードするまで待機します。 アプリは起動時にインターネットに接続する必要があります。

• Never: 一致するオブジェクトがダウンロードされるのを待たない。 アプリは、アプリが初めて起動するときにユーザーが認証するためにインターネット接続を必要としますが、キャッシュされた認証情報を使用して以降の起動ではオフラインで開くことができます。

オプションで、同期ダウンロードの実行時間を制限するには、 timeoutの値を指定します。

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Add subscription with timeout
// If timeout expires before sync is completed, currently-downloaded
// objects are returned and sync download continues in the background.
const taskSubscription = await completedTasks.subscribe({
  behavior: WaitForSync.Always,
  timeout: 500,
});

クエリからのサブスクライブの解除

unsubscribe()を使用して、クエリの結果からサブスクライブを解除できます。

import { WaitForSync } from "realm";
// Get tasks that have a status of "in progress".
const completedTasks = realm
  .objects(Task)
  .filtered("status == 'completed'");
// Only waits for sync to finish on the initial sync.
await completedTasks.subscribe({
  behavior: WaitForSync.FirstTime,
  name: "First time sync only",
});
// Unsubscribe
completedTasks.unsubscribe();

これにより、サブスクリプションを手動で削除するのと同様に、アクティブなサブスクリプションのリストからサブスクリプションが削除されます。

重複するオブジェクトを含む別のサブスクリプションが存在する場合、 unsubscribe()を呼び出した後も結果リストにはオブジェクトが含まれることがあります。

unsubscribe()を呼び出すと、関連付けられているサブスクライブが削除されます。 サブスクリプションは名前で削除されます。 名前がない場合、 unsubscribe()は、 unsubscribe()を呼び出したクエリと完全に一致するクエリをすべて削除します。

unsubscribe()メソッドは、削除されたサブスクリプションに一致するオブジェクトが Realm から削除される前にを返します。 新しいサブスクライブセットに基づいて、同期はバックグラウンドで続行されます。

すべてのサブスクリプションを取得する

柔軟に同期された Realm を使用する場合、 Realm.subscriptionsを通じてサブスクリプションのコレクションであるSubscriptionSetにアクセスできます。 プロパティ。

// get the SubscriptionSet for the realm
const subscriptions = realm.subscriptions;

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

サブスクリプションは、 Realm クエリの結果に基づいています。

次の例では、 completedとprogressMinutesが App Services App でクエリ可能なフィールドとして設定されています。 クライアント コードでは、フィルタリングされたクエリを作成し、その結果をサブスクライブします。

• 完了したタスク

• 120 時間以上かかったタスクを完了しました progressMinutes

const tasks = realm.objects("Task");
const longRunningTasks = tasks.filtered(
  'status == "completed" && progressMinutes > 120'
);
await realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(longRunningTasks, {
    name: "longRunningTasksSubscription",
  });
  mutableSubs.add(realm.objects("Team"), {
    name: "teamsSubscription",
  });
});

初期サブスクリプションの設定

Flexible Sync レルムからの読み取りまたは書込みを行う前に、少なくとも 1 つのサブスクリプションが必要です。 Realm を開くときに初期サブスクリプションを追加できます。

初期サブスクリプションを設定するには、Realm のSyncConfigurationにinitialSubscriptionsフィールドを含めます。 initialSubscriptionsオブジェクト内に、クエリをサブスクライブするコールバックにupdateフィールド セットを追加します。

const config = {
  schema: [Task],
  sync: {
    user: app.currentUser,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(realm.objects(Task).filtered("status == 'in progress'"), {
          name: "In progress tasks",
        });
      },
      rerunOnOpen: true,
    },
  },
};
const realm = await Realm.open(config);

const config: Realm.Configuration = {
  schema: [Task],
  sync: {
    user: app.currentUser!,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(realm.objects(Task).filtered("status == 'in progress'"), {
          name: "In progress tasks",
        });
      },
      rerunOnOpen: true,
    },
  },
};
const realm = await Realm.open(config);

デフォルトでは、初期サブスクリプションは、Realm が初めて開かれたときにのみ作成されます。 アプリを起動するたびにアプリがこの初期サブスクリプションを再実行する必要がある場合は、 rerunOnOpenをtrueに設定できます。 動的時間範囲やサブスクライブの静的変数の再計算が必要なその他のクエリを再実行するには、この操作が必要になる場合があります。

サブスクリプションのステータスを確認

サブスクリプション状態をチェックして、サーバーがサブスクリプションを確認し、デバイスがデータをローカルにダウンロードしているかどうかを確認できます。

サブスクリプション状態を使用して、次のことが可能です。

• Trigger error handling

• トランザクションが保留中か完了したかを表示する

• サブスクリプションセットがスーパー秒されているときを見つけ、サブスクリプションの変更を書き込むにはサブスクリプションセットの新しいインスタンスを取得する必要があります

Node.js v 12.0.0 サブスクリプションのステータスを取得するために使用できるSubscriptionSetState 列挙型を追加しました。

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

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

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

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(
    tasks.filtered('status == "completed" && progressMinutes > 180'),
    {
      name: "longRunningTasksSubscription",
    }
  );
});

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

サブスクリプションは、次の方法で削除できます。

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

• 特定の名前の単一のサブスクライブを削除

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

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

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

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

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific query
  mutableSubs.remove(tasks.filtered('owner == "Ben"'));
});

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific name
  mutableSubs.removeByName("longRunningTasksSubscription");
});

let subscriptionReference;
realm.subscriptions.update((mutableSubs) => {
  subscriptionReference = mutableSubs.add(realm.objects("Task"));
});
// later..
realm.subscriptions.removeSubscription(subscriptionReference);

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeByObjectType("Team");
});

// Remove unnamed subscriptions.
let numberRemovedSubscriptions = 0;
await realm.subscriptions.update((mutableSubs) => {
  numberRemovedSubscriptions = mutableSubs.removeUnnamed();
});

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeAll();
});

API 効率

「クエリへのサブスクライブ」セクションで説明されているsubscribe()とunsubscribe() API を使用して複数のサブスクリプションを管理する場合、サブスクリプションを手動で管理する場合にバッチ更新を実行する場合より効率が低くなります。

複数のサブスクライブ変更を行う際のパフォーマンスを向上させるには、 subscriptions API を使用して 1 回のトランザクションですべてのサブスクライブを更新します。 方法については、「サブスクリプションの手動管理 」を参照してください。

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

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

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

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