Elasticsearch:ブランチスライス (ベータ版)

前提条件

• ソースとターゲットは同じコレクションに属し、マッピングとインデックス設定を共有します。独立した書き込みはドキュメントのコンテンツにのみ影響します。

• ターゲットとソースは、同じバッキングの同じシャード上に存在します。ソースを含むバッキングの index.routing_partition_size は、デフォルト値の 1 である必要があります。値が 1 より大きい場合、ブランチの作成はサポートされません。 Copy Slice の使用をご検討ください。

• ターゲットは新しい名前を使用する必要があり、既存のスライスを引き継ぐことはできません。重複リクエストと名前の競合については、「新しいブランチの作成」および「一般的なエラー」をご参照ください。

• アカウントには、コレクションに対する manage 権限が必要です。この権限の設定方法については、「コレクションの権限」をご参照ください。

ブランチスライスを利用する前に、お使いのユースケースで以下の制限が許容可能かをご確認ください：

• リクエスト全体の失敗 — ターゲットがアクティブなブランチ (まだ通常のスライスに変換されていないブランチターゲット) である間、ターゲットを含む複数スライスリクエストまたは _slice=_all リクエストは、部分的な結果ではなく HTTP 409 を返します。同期的な _warm_slice リクエストも HTTP 409 を返し、Explain はサポートされません。

• 不完全な結果 — 複数行を返す CAT リクエスト、または s=docs.count でソートする CAT リクエストは、ターゲット自体に書き込まれたデータのみをカウントします。

• ソースの状態 — ソーススライスがまだアクティブなブランチである場合、wait_for_commit=false のみがサポートされます。wait_for_commit=true を指定すると HTTP 400 が返されます。

• 継承の深さ — 最大 8 階層の継承がサポートされています。

• クォータ — 同じシャードで準備中のブランチ数、アクティブなブランチ数、およびブランチのメタデータサイズに制限が適用されます。制限に達すると、新しいブランチの作成のみが拒否されます。既存のブランチとそのデータへの読み書きは引き続き処理されます。

• リトライ可能な非可用性 — ブランチの状態が移行中であるか、読み取りに必要なコミット済みデータが一時的に利用できない場合、読み取りおよび派生操作はリトライ可能な HTTP 503 を返します。

詳細については、「アクティブフェーズ中の動作の違い」および「一般的なエラー」をご参照ください。ブランチスライスと Copy Slice の比較については、「関連情報」をご参照ください。

新しいブランチの作成

次のリクエストを送信してブランチを作成します：

PUT /_slice_collection/{collection}/slices/{source}/_branch/{target}

次のクエリパラメーターがサポートされています：

リクエストボディは省略するか、{} に設定できます。現在、オプションは次のフィールドのみです：

次の例では、ソーススライス tenant-a からブランチ tenant-a-preview を作成します：

PUT /_slice_collection/knowledge-chunks/slices/tenant-a/_branch/tenant-a-preview
{}

最初の作成が成功すると、HTTP 201 が返されます：

{
  "target_slice": "tenant-a-preview",
  "target_uid": "opaque-target-uid",
  "wait_for_commit": false
}

target_uid はターゲットの内部IDであり、同じ作成リクエストによる結果であるかを確認するために使用されます。その内容を解析したり、_slice として使用したりしないでください。ターゲットにアクセスするには、レスポンス内の target_slice であるユーザー指定名 tenant-a-preview を引き続き指定します。

同じアクティブなブランチ関係に対して同じリクエストを再度送信すると、べき等となり、HTTP 200 と同じ target_uid が返されます。この API は既存のターゲットを引き継ぎません。ターゲット名が使用中であるか、他の競合が作成を妨げる場合、HTTP 409 が返されます。HTTP 409 が返されるシナリオの一覧については、「一般的なエラー」をご参照ください。

リクエストがタイムアウトしても、すでに永続化された作成の進行状況はロールバックされません。タイムアウトしたからといって、作成がロールバックされたと判断しないでください。ターゲットスライスをクエリして利用可能かどうかを確認し、「一般的なエラー」で説明されているようにリトライを処理してください。

作成レスポンスが返された後、ターゲットが読み取り可能であり、期待されるデータを返すことを確認します。確認方法については、「クエリとドキュメント数の検証」をご参照ください。

PUT /_slice_collection/knowledge-chunks/slices/tenant-a/_branch/tenant-a-durable-preview
{
  "wait_for_commit": true
}

読み書きのセマンティクス

作成レスポンスが返された後、ターゲットはすぐに 単一スライス に対する GET、MGet、および Search に使用できます。ドキュメントリクエストでは、引き続き _slice=tenant-a-preview を指定してターゲットを選択します。パラメーターと権限は、通常のスライスと同じです。次のリクエストはターゲットスライスを検索します：

GET /knowledge-chunks/_search?_slice=tenant-a-preview

ブランチターゲットには、以下の読み書きルールが適用されます：

• 通常の利用では、ターゲットは作成時に固定されたソースデータバージョンを読み取ります。その後ソースに書き込まれたドキュメントは、ターゲットに自動的に表示されることは ありません。デフォルトの wait_for_commit=false に適用される初期の障害復旧の例外については、「新しいブランチの作成」にある wait_for_commit の値に関する説明をご参照ください。

• ターゲットに対する Index、Update、および Delete 操作はターゲットにのみ影響し、 ソースを変更することはありません。

• ブランチは、継承されたドキュメント内のビジネスフィールドをターゲット名に変更しません。routing_field が設定されている場合、ターゲットへの後続の書き込みはターゲットスライスを選択する必要があり、書き込まれたドキュメント内のルーティングフィールドはターゲットと一致する必要があります。そうでない場合、ドキュメントはソースフィールドの値に基づいてソースに書き戻されるか、明示的に指定されたスコープがフィールドと一致しないために書き込みが拒否される可能性があります。

• 継承されたドキュメントと同じ _id を持つドキュメントをターゲットに書き込むと、新しいドキュメントは継承されたビュー内の古いドキュメントを上書きします。

• ターゲットから継承されたドキュメントを削除すると、そのドキュメントはターゲット内でのみ非表示になります。ソース内のドキュメントは影響を受けません。

• ターゲットを削除するには、標準の「スライスの削除」 API を使用します。ブランチ関係が解放された後、同じ名前のターゲットを通常のスライスとして再度登録できます。新しいスライスは、古いブランチによって継承されたデータを表示できません。

ブランチターゲットは、新しいブランチのソースとしても使用できます。この場合、wait_for_commit=false のみがサポートされ、true を指定すると HTTP 400 が返されます。 最大 8 階層の継承がサポートされています。

ブランチターゲットからブランチを作成する場合、次のルールが適用されます：

• システムは、进行中の書き込みを待たずに、ターゲットの最新の完全なコミット済みビューをキャプチャします。

• 書き込みが新しいブランチに含まれるかどうかは、その書き込みが実際にキャプチャされたコミット済みバージョンにすでに含まれているかどうかによって決まります。

• クライアントがリクエストを送信した時刻を、書き込みのカットオフとして使用することはできません。

アクティブフェーズ中の動作の違い

ターゲットが通常のスライスに変換される前は、アクティブなブランチと呼ばれます。このフェーズでは以下の点で動作が異なります。これらのうち一部は、部分的な結果を返す代わりにリクエスト全体が失敗する原因となります。この機能を利用する前に、お使いのユースケースでこれらの制限が許容可能かをご確認ください：

すべてのスライスを対象とする統計または検索リクエストがある場合は、ブランチを作成する前に、これらのリクエストがアクティブなブランチを含むことで失敗する可能性があるかどうかを評価してください。すぐに複数スライスのクエリを実行する必要がある場合は、このターゲットを個別にクエリするか、通常のスライスに変換された後にリトライしてください。

通常のスライスへの自動変換

ブランチターゲットは、バックグラウンドで自動的に通常のスライスに変換されます。この変換では、表示可能な完全な履歴を一度スキャンし、継承されたデータをターゲット自体のデータとして書き込みます。プロセス全体で、 読み取りや書き込みがフリーズすることはありません。変換が完了すると、アクティブフェーズで説明したすべての動作の違いがなくなります。

変換はバックグラウンドでスケジュールされます。トリガー条件には、作成からの一定時間の経過、上書きまたは削除された継承ドキュメント数が特定のしきい値に達すること、およびブランチのメタデータが特定のサイズに達することが含まれます。これらは スケジューリングの条件であり、完了の期限、更新回数の制限、または書き込み拒否の制限ではありません。特定のしきい値は、ベータ版では変更される可能性のある内部値です。条件を満たしても変換がすぐに完了するわけではなく、条件を満たさなくてもターゲットでの通常の読み書きには影響しません。

バックグラウンドタスクのバックログや、1 回の実行に対するメモリ割り当ての不足によって、既存のターゲットに対する GET、Search、Index、Update、または Delete 操作が失敗することはありません。システムはバックグラウンドタスクをキャンセルしてリトライします。すでに成功した変換結果と後続の書き込みは有効なままです。

ターゲットが通常のスライスに変換されたかどうかを確認するには、実際のアプリケーションリクエストにおいてアクティブなブランチの制限が解消されるかどうかを観察してください。頻繁な _slice=_all クエリやウォーミングタスクの繰り返し送信によって変換の進行状況を探らないでください。単一スライスの読み書きは、変換を待つ必要はありません。

クエリとドキュメント数の検証

ブランチを作成した後、ターゲットが読み取り可能であり、期待されるデータを返すことを確認します。1 つのリクエストでソースとターゲットを個別にクエリするには、 Multi Search を使用し、各サブリクエストで 1 つのスライスのみを選択します：

POST /knowledge-chunks/_msearch
{ "_slice": "tenant-a" }
{ "query": { "match_all": {} } }
{ "_slice": "tenant-a-preview" }
{ "query": { "match_all": {} } }

リクエストボディは NDJSON 形式であり、改行で終わる必要があります。各サブリクエストは個別に結果またはエラーを返すため、アプリケーション側で各項目をチェックする必要があります。この方法では、スライスをまたいだ統一されたソートや集計結果は自動的に生成されません。

ターゲット内の検索可能なドキュメントの総数を確認するには、ターゲットスライスを直接クエリします。include_doc_count=true は追加のデータクエリを実行するため、低頻度の検証に適しています。スライスの存在を確認するだけでよい場合は、このパラメーターを省略します：

GET /_slice_collection/knowledge-chunks/slices/tenant-a-preview?include_doc_count=true

ブランチの状態が移行中であるか、読み取りに必要なコミット済みデータが一時的に利用できない場合、現在のノードは一時的に完全なブランチデータを提供できないことがあります。読み取りまたは派生操作は、 リトライ可能な HTTP 503 を返します。リトライの仕様については、「一般的なエラー」をご参照ください。

一般的なエラー

特定の数とサイズの制限については、「ブランチスライス (ベータ版) の制限」をご参照ください。

関連情報

ブランチスライスと Copy Slice のどちらを選択するかについては、「ブランチスライスと Copy Slice の比較」をご参照ください。