Elasticsearch:データコピー：Copy Slice

Copy はドキュメントを 1 つずつ書き換えるため、処理時間と読み取りおよび書き込みのオーバーヘッドの両方がデータ量に応じて増加します。

Copy のデータセマンティクス

Copy はデータの独立したコピーを生成し、ソース Slice を元の場所に残します。以下のリストは、コピー先 Slice がどのように割り当てられ、Copy 中にドキュメントがどのように処理されるかを説明します。

• ソース Slice とコピー先 Slice は同じ Collection に属し、同じ名前であってはなりません。

• Copy の開始時に、コピー先 Slice に検索可能なドキュメントが含まれていてはなりません。含まれている場合、Copy は target_not_empty を返します。このチェックはコピー先 Slice をロックしないため、同時書き込みによって同じ ID を持つドキュメント間で競合が発生する可能性があります。

• コピー先 Slice が存在しない場合、auto_create_slice=false の場合でも、Copy は通常の Slice に対する Collection の現在の割り当てルールに基づいて、コピー先 Slice を自動的に登録します。コピー先 Slice がすでに存在する場合、Copy はそのバッキングとシャードの場所を使用します。後で発生した受付失敗によって、新しく登録されたコピー先 Slice が自動的に削除されることはありません。

• Copy はバッキングやシャードをまたいでデータをコピーできます。ソース Slice とコピー先 Slice は、異なるシャード数とルーティングパーティション設定を使用でき、ドキュメントはコピー先の設定に基づいて再インデックス化されます。

• Copy API には、コピー先のバッキングやシャードを指定するパラメーターはありません。また、新しいコピー先 Slice とソース Slice が異なるシャード上に配置されることを保証するものではありません。後続のバッキングのシャード数やルーティングパーティション設定を調整した場合、それ以降に作成されたバッキングのみが新しい設定を使用します。Copy は、既存のコピー先 Slice のシャードレイアウトを変更しません。詳細については、「後続のバッキングで有効になる設定」をご参照ください。

• Copy は作成のみの書き込みを使用し、コピー先 Slice 内の同じ _id を持つ既存のドキュメントを上書きしません。競合は version_conflicts でカウントされ、残りのドキュメントは引き続きコピーされます。Copy の完了後、このフィールドを確認し、ビジネス要件に基づいて同じ ID を持つドキュメントを処理してください。

• Copy は、routing_field によって参照されるフィールドを含むドキュメントの内容を保持します。たとえば、routing_field=cluster_id の場合に cluster-a が cluster-b にコピーされると、挿入先ドキュメントの cluster_id は cluster-a のままです。後で Index または Bulk を使用してドキュメントをコピー先 Slice に書き戻すには、_slice=cluster-b を明示的に指定し、ドキュメント内の cluster_id を cluster-b に変更する必要があります。ドキュメントを変更せずに書き戻し、_slice または routing を省略すると、フィールド値によってドキュメントはソース Slice にルーティングされます。コピー先 Slice を明示的に指定してもソースのフィールド値を保持した場合、デフォルトの検証では HTTP 400 が返されます。この動作をバイパスするために検証を無効にしないでください。アプリケーションがトラフィックを切り替える前に、書き込みロジックを調整してください。

• ベクトルクラスターモードでは、Copy はドキュメントのみをコピーし、Slice の中心ベクトルはコピーしません。自動的に登録されたコピー先 Slice には中心ベクトルがないため、自動的な Slice 選択には参加しません。コピー先 Slice を参加させるには、中心ベクトルを別途登録するか、Copy を実行する前に中心ベクトルを持つ空のコピー先 Slice を登録する必要があります。

• Copy の実行中、ソース Slice とコピー先 Slice の両方が読み書き可能なままです。したがって、結果はソース Slice のアトミックなポイントインタイムスナップショットではありません。

• ソース Slice は、ドキュメントを再構築するために必要な完全な _source を保持する必要があります。_source が無効になっている場合、または合成 _source が使用されている場合、Copy は拒否されます。空ではない _source.includes が設定されている場合や、_source.excludes がインデックス作成、ソート、copy_to、またはマルチフィールドでまだ使用されているコンテンツを除外する場合も、Copy は拒否されます。インデックスから安全に復元できるフィールドのみを除外した場合は、動作する可能性があります。サーバー側の検証結果が優先されます。

• 現在、ソース Slice のマッピングに semantic_text などの推論フィールドが含まれている場合、Copy はサポートされていません。

• デフォルトまたは最終のインジェストパイプラインは、Copy の実行中には再実行されません。

• ドキュメントは、コピー先 Slice の現在のマッピングに基づいて再適用されます。たとえば、新しく追加されたマルチフィールドはコピー先 Slice で生成されます。Copy の実行中に結果の解釈に影響を与える可能性のあるマッピングの変更は避けてください。

コピー先シャード設定の調整 (任意)

シャード設定を調整する必要がない場合は、直接 Copy を開始してください。Copy API はコピー先のバッキングを指定できないため、コピー先 Slice が異なる数のプライマリシャードまたはルーティングパーティションを使用するようにするには、Copy を開始する前に次の手順を完了してください。

1. 「Collection の更新」を使用して後続のバッキングのパラメーターを設定し、次に「バッキングを事前作成」してください。複数のバッキングを事前作成すると、システムは新しい Slice の割り当てルールを random に切り替えます。

2. コピー先が作成したばかりのバッキングを使用する必要がある場合は、割り当てルールを last に戻してください。

3. コピー先 Slice を登録してください。

4. コピー先 Slice の backing_index が新しいバッキングを使用していることを確認してから、Copy を開始してください。

Copy：操作の開始

Copy を開始する前に、ソースデータが検索可能であり、コピー先が新しい Slice または検索可能なドキュメントのない Slice であることを確認してください。ソースドキュメントは、「Copy のデータセマンティクス」で説明されている _source とマッピングの要件を満たす必要があります。Copy はソースデータを読み取ってコピー先 Slice に書き込みますが、進行中の書き込みは自動的に同期されません。トラフィックを切り替える前に、増分データを別途処理してください。

次のリクエストを送信してください。{collection}、{source}、{target} を Collection 名、ソース Slice 名、コピー先 Slice 名に置き換えてください。

POST /_slice_collection/{collection}/slices/{source}/_copy/{target}

クエリパラメーター：

リクエスト本文のパラメーターはすべて任意です：

次の例では、ワーカー 1 つ、バッチあたり 500 ドキュメント、合計レート 500 ドキュメント/秒で開始します。これらは初期負荷を制御するためのサンプル値であり、デフォルト値やスループットの保証ではありません。調整する前に、ドキュメントサイズ、ソースクエリのオーバーヘッド、およびコピー先の書き込み負荷を評価してください。

POST /_slice_collection/knowledge-chunks/slices/tenant-a/_copy/tenant-a-copy?wait_for_completion=false
{
  "workers": 1,
  "batch_size": 500,
  "requests_per_second": 500
}

非同期リクエストは HTTP 202 Accepted を返します。レスポンスから copy_id を保存し、サーバーが返す status_url と cancel_url を使用してください。Location レスポンスヘッダーもステータスクエリ URL を提供します。レスポンスの例：

{
  "copy_id": "opaque-copy-id",
  "completed": false,
  "timed_out": false,
  "state": "RUNNING",
  "source": "tenant-a",
  "target": "tenant-a-copy",
  "progress": { "total": 0, "created": 0, "version_conflicts": 0 },
  "status_url": "/_slice_collection/knowledge-chunks/_copy/opaque-copy-id",
  "cancel_url": "/_slice_collection/knowledge-chunks/_copy/opaque-copy-id/_cancel"
}

レスポンスに workers が含まれるのは、実行の並行性が決定された後であり、その値は常に 0 より大きくなります。送信直後に返されるレスポンスにこのフィールドが含まれていると想定しないでください。Copy が失敗した場合、レスポンスには失敗の原因を説明する error も含まれます。

copy_id は不透明な識別子であり、コロンなどの URL 予約文字を含む場合があります。ステータスクエリ URL を自分で作成する場合は、識別子を URL エンコードしてください。レスポンスで返された status_url と cancel_url を使用してください。

進行中の Copy 操作のレスポンスには、progress オブジェクトが含まれます。result を使用するのは state=SUCCEEDED の場合のみです。FAILED および CANCELLED 状態でも progress を使用して、Copy が終了する前に完了した作業を報告します。3 つの終了状態はすべて、completed=true と、経過時間をミリ秒単位で示す took を含みます。version_conflicts は、対応する progress または result オブジェクトに表示されます。

デフォルトの wait_for_completion=true を使用すると、timeout 期間内に Copy が終了状態になった場合、API は HTTP 200 を返します。待機がタイムアウトした場合、API は timed_out=true とともに HTTP 202 を返し、Copy はバックグラウンドで実行を継続します。クライアントを切断しても、Copy は自動的にキャンセルされません。

Copy：ステータスのクエリ

次のリクエストを送信してください。<copy_id> を開始リクエストが返した copy_id に置き換えてください。

GET /_slice_collection/knowledge-chunks/_copy/<copy_id>

成功したステータスクエリは、state=FAILED の場合を含め、常に HTTP 200 を返します。HTTP ステータスコードのみに依存せず、常に state と error を確認してください。

一定間隔で Copy のステータスをクエリし、Copy が終端状態になったらポーリングを停止します。SUCCEEDED は Copy が完了したことを意味しますが、すべての宛先データが検索可能になったわけではありません。結果を検証したり、トラフィックを切り替えたりする前に、バックグラウンドリフレッシュを待ってから、宛先スライスのクエリ結果を確認してください。コールドクエリのレイテンシーがワークロードにとって重要である場合は、事前に宛先スライスをウォームアップしてください。Copy が長時間 RUNNING 状態にあり、進行が遅い場合、サーバーはメモリプレッシャーが原因でバッチサイズを自動的に縮小した可能性があります。これは自己保護動作であるため、すぐに Copy をキャンセルして再試行するのではなく、一定間隔でクエリを続行してください。

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.copy.reservation_retention": "1d"
  }
}

Copy：操作のキャンセル

次のリクエストを送信してください。<copy_id> を開始リクエストが返した copy_id に置き換えてください。

POST /_slice_collection/knowledge-chunks/_copy/<copy_id>/_cancel

コピーをキャンセルしても、宛先スライスやすでにコピーされたドキュメントは削除されません。非同期のキャンセルが受け入れられると、API は state=CANCELLING とともに HTTP 202 を返します。 completed=true になるまでステータスのポーリングを続行してください。これにより、通常は state=CANCELLED が返されます。キャンセルが有効になる前にコピーが成功または失敗した場合、対応する最終状態が返されます。コピーが終了すると、レスポンスに cancel_url は含まれなくなります。すでに終了したコピー操作をキャンセルすると、現在の状態と HTTP 200 が返されます。

エラーコード

次の表に、Copy API が起動時に返すエラーを示します。

次のステップ

Copy が完了したら、アプリケーションレイヤーで Copy のステータスと結果を確認し、ビジネス設定を通じてサービスのトラフィックをコピー先 Slice に切り替えてください。

Copy と Branch の選択に関する情報については、「書き込み可能なデータブランチ：Branch Slice (ベータ版)」をご参照ください。