Elasticsearch:ドキュメントの書き込み、読み取り、クエリ操作

ドキュメントの書き込みと読み取り

単一ドキュメント API：

以下のルールに従ってください：

• 単一ドキュメントのリクエストでは、1つの Slice のみ指定できます。カンマ区切りのリストや _all は使用できません。

• index、create、または update は、auto_create_slice=true が設定されている場合、存在しない Slice を自動的に登録できます。読み取りおよび削除操作は Slice を自動的に登録せず、存在しない Slice を指定すると HTTP 404 が返されます。

• ドキュメントは、コレクション、ビジネス Slice 名、および _id の組み合わせによって一意に特定されます。異なる Slice は同じ _id を使用できます。アプリケーションがドキュメントを読み取り、更新、または削除する場合、対応する Slice を指定する必要があります。_id だけでテナントを区別しないでください。

• Bulk リクエストには、Bulk セクションで説明されている別の Slice 自動登録クォータが適用されます。

• wait_for_active_shardsは、Agent エンジンの書き込みパスでレプリカを待機する条件としては使用されません。ほとんどの場合、バックグラウンドリフレッシュによってクエリの可視性が提供されます。書き込みリクエストが返される前にデータを検索可能にする必要がある場合は、後述の適用条件下で refresh=wait_for を使用します。

• ベクトル値はデフォルトでは返されません。通常の読み取りおよび検索操作は、ビジネスで必要なフィールドのみを返します。ベクトル値の検証またはエクスポートについては、「必要に応じたベクトル値の読み取り」をご参照ください。

  応答では、_index と _routing は、リクエストで使用されたコレクション名とビジネス Slice 名の代わりに、基盤となるインデックス名とシステムが生成した内部 Slice 識別子 (slice_uid) を返す場合があります。後続のリクエストでは引き続きビジネス名を使い、これらの内部値を返さないでください。詳細については、「リクエストターゲットと応答識別子」をご参照ください。

リフレッシュとクエリの可視性

通常の書き込みでは、refreshを渡さないでください。バックグラウンドでの自動リフレッシュを待機してください。書き込みが成功したということは、データが永続化されたことを意味します。ID によるドキュメントの読み取りと条件による検索では、可視性の動作が異なります。次のセクションでは、シナリオに合った読み取り方法とリフレッシュ動作の選択方法について説明します。

GET /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a

Bulk

各 Bulk アイテムは、アクションメタデータ内で独自の _slice を提供できます。例については、「クイックスタートの Bulk 書き込み例」をご参照ください。バッチ全体が同じ Slice に書き込まれる場合は、URL でデフォルト値を指定することもできます：

POST /knowledge-chunks/_bulk?_slice=tenant-a
{ "index": { "_id": "chunk-2001" } }
{ "tenant_id": "tenant-a", "document_id": "doc-account-security", "title": "Account security settings", "content": "An administrator can enable multi-factor authentication on the security settings page." }

アイテム内の _slice の値は、URL のデフォルト値をオーバーライドできます。各 Bulk リクエストは、最大 512 個の存在しない Slice を自動的に登録します。既存の Slice はこの制限にはカウントされません。名前空間モードでは、ドキュメントフィールドから Slice を派生させません。ドキュメント本文に tenant_id のようなフィールドが含まれていても、実際の書き込み場所は _slice によって決定されます。返された各アイテムの結果を確認して、書き込みが成功したことを確認してください。エラー処理については、「一般的な API 規則」をご参照ください。

MGet

MGet を使用して、既知の ID を持つ複数のドキュメントを1つのリクエストで読み取ります。各アイテムは異なる Slice をターゲットにできます：

POST /knowledge-chunks/_mget
{
  "docs": [
    { "_id": "chunk-1001", "_slice": "tenant-a" },
    { "_id": "chunk-1001", "_slice": "tenant-b" }
  ]
}

これら2つのアイテムは、異なるテナントから同じ ID のドキュメントを読み取ります。クイックスタートのサンプルデータを使用すると、返されるタイトルは「Refund and return policy」と「Track shipment status」です。ご自身のデータをクエリする場合は、found、ビジネスフィールド、および各アイテムのエラーに基づいて結果を判断してください。URL の _slice は、各アイテムがオーバーライドできるデフォルト値として機能します。各アイテムは、正確に1つの Slice に解決される必要があります。

インデックスの再作成

インデックスの再作成を呼び出す前に、「コレクションのインデックス再作成に関する API サポート範囲」、特にスクリプト、送信先パイプライン、およびリモートソースに関する制限事項を確認してください。

通常のインデックスとコレクション間、またはコレクション間でデータを移行する場合は、インデックスの再作成を使用します。同じコレクション内で Slice をコピーするには、「Copy Slice」を使用します。

ソースがコレクションの場合、リクエストボディで source._slice を明示的に指定する必要があります。そうしないと、リクエストは HTTP 400 を返します。送信先がコレクションの場合、1つの送信先 Slice のみ指定でき、送信先の値は ={slice} 形式を使用する必要があります。

タスクを実行する前に、送信先コレクションを作成し、ソースドキュメントを受け入れられるマッピングを設定し、「Backing の事前作成」に従って容量を準備し、送信先 Slice を登録します。移行するソースデータが検索可能であることを確認してください。インデックスの再作成は後続の書き込みを継続的に同期しないため、本番への切り替え前に増分データも処理する必要があります。

デフォルトでは、インデックスの再作成はドキュメントの _id を保持し、送信先で同じ ID を持つドキュメントを上書きする可能性があります。複数のソース Slice を1つの送信先 Slice にマージする前に、ドキュメント ID がそれらの Slice 間でも一意であることを確認してください。そうでない場合は、それらを異なる送信先 Slice に移行するか、アプリケーションがドキュメントをインポートする前に新しい一意の ID を生成するようにしてください。

次の例では、非同期実行、単一タスク、バッチあたり 500 ドキュメント、および秒間 500 ドキュメントの目標レートを使用しています。これらの設定から始めて、オンラインワークロードへの移行の影響を制御し、ワークロードに基づいて調整してください。requests_per_second は、秒間 HTTP リクエスト数ではなく、バッチ間のドキュメント数によってスロットルします：

POST /_reindex?wait_for_completion=false&slices=1&requests_per_second=500
{
  "source": {
    "index": "source-knowledge-chunks",
    "_slice": "tenant-a",
    "size": 500
  },
  "dest": {
    "index": "target-knowledge-chunks",
    "_slice": "=tenant-archive"
  }
}

応答から task の値を保存し、completed=true になるまで GET /_tasks/{task_id} を定期的にポーリングします。結果の error、failures、および version_conflicts を確認してください。タスクの完了は、すべての送信先データが検索可能であることを意味するものではありません。切り替え前に、バックグラウンドリフレッシュを待ち、送信先の結果を検証し、アクセスされる Slice をプリウォームしてください。

以下のルールに注意してください：

• source._slice は、1つの Slice、複数の Slice、または _all をサポートします。インデックスの再作成リクエストボディは source.routing を受け付けず、これを渡すと HTTP 400 が返されます。

• 送信先は "_slice": "=slice-name" または "routing": "=slice-name" を使用できますが、両方は使用できません。先頭の = は保持する必要があります。

• 送信先 Slice が存在しない場合、auto_create_slice=true が設定されている場合にのみ自動的に登録されます。

• トップレベルの slices パラメーターは、Elasticsearch のインデックス再作成の並列度を指定するものであり、ビジネス Slice の数とは無関係です。

• コレクションから通常のインデックスに書き込む際に、ルーティングを保持する必要がない場合は、"dest": { "routing": "discard" } を設定します。

クエリ範囲の指定

このセクションでは、Agent エンジンバージョンが追加する Slice クエリ範囲について説明します。その他のエンドポイントパラメーターは、標準的な Elasticsearch API のセマンティクスに従います。既知の制限事項については、「API サポート範囲」をご参照ください。

1つのクエリで最大 1,024 個の Slice を指定できます。HTTP リクエスト行の長さ制限も適用されます。Slice 名が長い場合、リクエストは数制限に達する前に too_long_http_line_exception を返す可能性があります。Slice 名を短くするか、リクエストを複数のクエリに分割してください。

コレクションクエリは、デフォルトでクエリとプリウォーミングのアフィニティを有効にします。この設定が有効な間、アフィニティルールはリクエスト内の preference をオーバーライドし、応答は追加の通知を行いません。preference を使用してノード選択を制御するには、管理者がこの設定を無効にする必要があります。この設定はクラスター全体に適用されるため、無効にするとすべてのコレクションに適用されます。

本番環境のクエリでは、_slice=_allを使用しないでください。このパラメーターはコレクション全体を検索し、シャードリクエスト、集約、およびクエリノードでのオブジェクトストレージ読み取りのオーバーヘッドは、Backing とシャードの数とともに増加します。アプリケーションは、1つの既知の Slice または少数の既知の Slice を指定する必要があります。GET /knowledge-chunks/_search?_slice=_all は、真にすべてのデータを必要とする専用の分析、監査、または O&M タスクにのみ使用し、コレクション全体の負荷を評価し、同時実行数を制限し、タイムアウトを設定した後にのみ使用してください。

ベータ段階でBranch Slice (ベータ版)を使用する場合、複数 Slice クエリと _slice=_all は、スコープにまだ通常の Slice に変換されていないブランチが含まれている場合、HTTP 409 を返します。この機能を使用しないワークロードは影響を受けません。

クエリリストに存在しない Slice が含まれる可能性がある場合は、ignore_missing_slice を使用します：

GET /knowledge-chunks/_search?_slice=tenant-a,tenant-b&ignore_missing_slice=true

存在しない可能性のあるオプションの Slice については、ignore_missing_slice=true を設定して、1つの Slice が見つからないためにバッチ全体をリトライすることを避けてください。このパラメーターがない場合、いずれかの Slice が存在しないとリクエスト全体が HTTP 404 を返します。このパラメーターは名前付きの Slice にのみ影響します。_slice=_all と一緒に使用すると、パラメーターはエラーなしで無視されます。

以下のクエリ エンドポイントは、同じ Slice スコープ パラメーターをサポートしています：

• Search および Count

• Multi search

• Search template

• Async search

• Validate query

• Search shards

• Update by query および Delete by query

  Explain は、ドキュメントがクエリに一致する理由を説明します。1つの Slice のみ指定できます。カンマ区切りのリストや _all は使用できません：

POST /knowledge-chunks/_explain/chunk-1001?_slice=tenant-a
{
  "query": {
    "match": { "content": "refund" }
  }
}

Update by query、Delete by query、およびコレクションをターゲットとするインデックスの再作成操作では、ターゲット Slice を明示的に指定する必要があります。そうしないと、リクエストは HTTP 400 で拒否されます。

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.search.default_to_all_slices": true
  }
}