Elasticsearch:使用ガイド

前提条件

• Alibaba Cloud Elasticsearch サービスを有効化しており、AI Engine Edition インスタンスを作成済みまたは作成予定です。

• インスタンスの VPC、vSwitch、IP アドレスホワイトリスト、およびクライアントネットワークを計画済みです。

• ビジネスデータに基づいてマッピングを設計済みです。ベクトル検索のシナリオでは、ベクトルモデル、次元、類似性メトリック、および更新方法も決定する必要があります。

• ご利用のアカウントに必要な権限が付与されています。Collection 管理には通常 manage、データ読み取りには read、データ書き込みには write が必要です。詳細については、「Collection 権限」をご参照ください。

インスタンスの作成

購入項目およびページレイアウトは、リージョン、バージョン、製品フェーズによって変更される場合があります。以下の手順は、実際のコンソールページに基づいています。AI Engine Edition でサポートされているリージョンおよびゾーンは、購入ページの実際の購入可能項目に基づいています。

1. Alibaba Cloud Elasticsearch コンソールにログインし、インスタンス作成ページに移動します。

2. AI Engine Edition を選択し、コンソールで提供されているリージョンおよびゾーンを選択します。このインスタンスタイプの Elasticsearch バージョンは固定されています。作成ページにはバージョン 9.x が表示され、これは変更できません。インスタンス作成後、インスタンス一覧またはインスタンス詳細ページで具体的なバージョン番号を確認できます。

3. 書き込みワークロードに基づいて インデックスノード を構成し、クエリワークロードに基づいて 検索ノード を構成します。その他のオプションコンポーネントは、コンソールに基づいています。

4. VPC、vSwitch、ユーザー名、パスワードを構成します。IP アドレスホワイトリストは作成ページでは構成されません。インスタンス作成後、インスタンスのセキュリティ構成ページで構成します。

5. 構成とコストを確認し、インスタンスを作成します。インスタンスステータスが 利用可能 に変更されたら、Elasticsearch および Kibana のアクセスアドレスを記録します。

   ノードスペック、最小ノード数、専用マスターノード構成は、購入ページの現在の購入可能項目に基づいています。

ノード数およびスペックは、書き込みスループット、クエリ同時実行数、ベクトルインデックス構築、アクティブデータセット、およびキャッシュ要件に基づいて決定する必要があります。ノード調整および課金ルールの具体的な操作は、コンソールに基づいています。

インスタンスへの接続

Kibana Dev Tools、Elasticsearch 互換クライアント、または任意の HTTP クライアントを使用して、インスタンスにアクセスできます。インスタンスアドレス、ネットワークホワイトリスト、証明書、および認証方式は、インスタンス詳細ページに基づいています。

AI Engine Edition のアクセスドメイン名はネットワークタイプによって異なります。ドメイン名は、リクエストが最初に接続するノードロールを決定するだけであり、リクエストタイプを制限しません。クラスターは、実際に処理を行うノードロールにリクエストを転送します。

プライベートネットワーク経由でインスタンスにアクセスする場合、両方のドメイン名が読み取りおよび書き込み操作をサポートします。本番環境でのアクセスでは、検索ノードのネットワーク帯域幅消費を削減するために、クエリリクエストにはデフォルトのプライベートネットワークドメイン名を、書き込みリクエストにはインデックスノードのプライベートネットワークドメイン名を使用してください。これは、Bulk 書き込み、大きな結果を返すクエリ、または高同時実行シナリオで特に重要です。パブリックネットワーク経由でインスタンスにアクセスする場合は、読み取りおよび書き込みリクエストの両方にデフォルトのパブリックネットワークドメイン名を使用してください。

たとえば、インスタンス ID が es-cn-xxx の場合、インデックスノードのプライベートネットワークドメイン名は es-cn-xxx-index.elasticsearch.aliyuncs.com です。プロトコル、ポート、およびネットワークアクセス方法は、コンソールに表示されている情報に基づいています。

インスタンスはデフォルトで HTTP を使用します。コンソールで HTTPS を有効化した場合は、クライアント接続プロトコルを HTTPS に切り替えてください。

Kibana Dev Tools で次のリクエストを実行して、接続を確認します。

GET /

AI Engine Edition 9.99.0 は、Elasticsearch カーネルバージョン 9.5.0 に対応しています。そのため、このリクエストによって返される version.number はカーネルバージョン番号であり、コンソールに表示されている 9.99.0 とは異なります。実際の Elasticsearch バージョンは、クラスター API 応答に基づいています。カスタムプラグインをインストールする場合は、AI Engine Edition に一致する 9.99.0 バージョン番号を使用してください。

cURL を使用する場合は、インスタンスアドレスと認証情報を置き換えてください。本番環境では、スクリプトやコマンド履歴にパスワードをプレーンテキストで保存しないでください。

curl --user '{username}:{password}' 'http://{elasticsearch-endpoint}/'

公式クライアントを使用する場合は、ご利用のインスタンスバージョンの API 互換性ドキュメントに基づいてクライアントバージョンを選択し、クライアント接続プールを再利用してください。リクエストごとに新しいクライアントを作成しないでください。

アクセス規則

• アプリケーションは常に Collection 名または Collection Alias を介してデータにアクセスします。

• 名前空間モードでは、書き込みおよびクエリは _slice を介して名前空間を指定します。_slice を指定しないクエリは失敗します。すべての Slices をクエリするには、明示的に _slice=_all を使用します。一部のドキュメントおよびクエリ API は、代替として routing もサポートしています。サポート範囲の詳細については、「ルーティング互換パラメーター」をご参照ください。

• ベクトルクラスターリコールモードでは、書き込みは _slice または routing_field を介してベクトルクラスターを指定します。KNN クエリは、クエリベクトルに基づいて複数の候補 Slices を自動的に選択できます。候補 Slices を自動的に選択できないクエリでは、明示的な _slice、または互換 API では routing が必要です。

• Slices はデータを整理し、クエリ範囲を制限するために使用されます。アカウント権限の境界ではありません。テナント権限を分離するには、アプリケーションレベルの認証と製品がサポートするセキュリティメカニズムを組み合わせてください。

• .sc-* バッキングインデックス (Backing Index) を保存または直接アクセスしないでください。これらの名前およびライフサイクルはシステムによって管理されています。一部の API 応答（書き込み応答の _index や Slice 登録応答の backing_index など）は、これらの名前を観測およびトラブルシューティング目的でのみ返します。これらを後続のアプリケーションリクエストのターゲットとして使用しないでください。ロール権限を構成する際は、.sc-<collection>-* ワイルドカードパターンを使用してください。詳細については、「Collection 権限」をご参照ください。

ルーティング互換パラメーター

このガイドに記載されている Collection または Collection Alias のドキュメント読み取り/書き込みおよびクエリ API を使用する場合、標準の Elasticsearch routing パラメーターを _slice の代わりに使用できます。これは既存クライアントとの互換性のためです。新規アプリケーションでは、より意味的に明確な _slice を使用してください。同じ URL または同じ Bulk または MGet アイテムで、両方のパラメーターを同時に指定することはできません。

この互換性は、Collection および Slice 管理、キャッシュウォーミング、Copy Slice、CAT、明示的な Refresh、または Reindex には適用されません。Reindex では source._slice および dest._slice を使用する必要があります。routing_field は、ドキュメントフィールドから Slice を導出するための構成であり、routing のエイリアスではありません。

一般的な API 規則

• JSON リクエストは Content-Type: application/json を使用します。Bulk および Multi Search は Content-Type: application/x-ndjson を使用し、リクエストボディの末尾に改行が必要です。

• Bulk、Multi Search、およびバッチ管理 API は、アイテムレベルの失敗が発生する可能性があります。アプリケーションは HTTP ステータスコードだけでなく、単一およびバッチ Slice 登録 API もアイテムレベルのエラーを使用することに注意してください。全体のリクエストは HTTP 200 を返しますが、トップレベルの errors フィールドが true になる場合があります。各 items[].result を個別に確認してください。

• HTTP 429 は、サーバーが現在リクエストを拒否していることを示します。クライアントは上限付きの指数バックオフを使用し、リトライに適した操作のみをリトライする必要があります。

• 接続タイムアウトまたは HTTP 5xx は、書き込みが確実に発生しなかったことを意味しません。リトライする前に、安定したドキュメント ID または他のべき等メカニズムで確認してください。

• URL を介して多数の _slice 値を渡す場合、HTTP リクエスト行の最大長が 4096 バイトであることに注意してください。Slice 名が長い場合、Slice 数の制限に達する前に too_long_http_line_exception がトリガーされる可能性があります。

  Collection 管理 API では、以下のクエリパラメーターが一般的に使用されます。具体的なサポート範囲は、各 API の説明に基づいています。

acknowledged=false を返す管理リクエストまたはタイムアウトするリクエストは、サーバー側の操作がロールバックされたことを意味しません。リトライする前に、現在のリソースステータスを確認してください。

モード比較

Collection には、名前空間モードとベクトルクラスターリコールモードがあります。どちらか一方のモードを選択する必要があります。モードは slice_strategy 作成パラメーターによって決定され、作成後に変更できません。これにより、Slices のビジネス上の意味、登録方法、および書き込み・クエリルーティングに影響します。

ベクトルクラスターリコールモードは、ベクトルクラスター重心に基づいて複数の候補 Slices を自動的に選択し、これらの Slices に並列でクエリを送信します。これは、ベクトルを格納するためにこのモードを使用する必要があることを意味しません。名前空間モードも dense_vector、KNN、および DiskBBQ をサポートしています。ビジネスで関連するベクトルクラスターを自動的にリコールする必要があり、かつクラスター重心のメンテナンスおよび取得率評価が完了している場合にのみ、ベクトルクラスターリコールモードを選択してください。

決定ガイド

以下のガイドを使用して、2 つのモードのいずれかを選択してください。

• デフォルトの推奨 — アプリケーションがクエリ前にビジネス識別子（テナント ID、ナレッジベース ID、コードリポジトリ ID）からクエリ範囲を決定できる場合は、名前空間モード (exact) を選択してください。

• 以下のすべてが該当する場合にのみ、ベクトルクラスターリコールモードを選択してください：

  • ビジネスでオフラインでクラスター重心を生成および継続的に維持できます。

  • データ量および Slices 数が十分に大きく、クエリ範囲を絞ることで実質的なメリットがあります。

  • ビジネスで KNN クエリを実行する前に候補クラスターを選択でき、取得率テストを通じて適切な候補 Slices 数を決定しています。

• 以下の場合はベクトルクラスターリコールモードを使用しないでください：

  • データに安定したクラスタリング構造がなく、信頼できる重心ベクトルを提供できません。

  • データ量または Slices 数が小さく、直接クエリのコストがすでに許容範囲内です。

  • クエリで必ずすべてのベクトルデータをカバーする必要があり、候補クラスター選択による取得範囲の変更が許容できません。この場合は、名前空間モードを使用し、_slice クエリ範囲を明示的に指定してください。

  名前空間モードを選択した後は、「名前空間モード：Slice による DiskBBQ ベクトル検索」をご参照ください。ベクトルクラスターリコールモードを選択した後は、「ベクトルクラスターリコールモード：自動候補 Slice 選択」をご参照ください。このガイドの他の Collection 管理、データ API、キャッシュウォーミング、Alias、Copy Slice、および監視機能は、特に明記されていない限り、両方のモードに適用されます。

クエリレプリカおよび高可用性

両方のモードのクエリは、検索ノード上のレプリカシャードによって処理されます。index.number_of_replicas は少なくとも 1 に設定する必要があります。そうでない場合、クエリを処理できません。1 に設定しても、基本的なクエリ要件を満たすだけで、クエリの高可用性は提供されません。本番環境では、少なくとも 2 に設定し、少なくとも 2 つの検索ノードを構成して、単一の検索ノードが障害発生時でもクエリを処理できるようにしてください。

名前空間モード：Slice による DiskBBQ ベクトル検索

エンタープライズナレッジベースプラットフォームは、複数のテナント向けに検索拡張生成 (RAG) サービスを提供します。アプリケーションがテナント認証を完了すると、現在のテナント ID を決定できます。ユーザーが質問を送信すると、アプリケーションはそのテナントのナレッジベースからセマンティクス的に関連するコンテンツセグメントのみをリコールする必要があります。

このシナリオでは、リクエスト送信前にクエリ範囲を決定できるため、名前空間モードに適しています。この例では、knowledge-chunks という名前の Collection を作成し、各テナントを Slice として使用します。アプリケーションは _slice を介してテナントナレッジベースを指定し、その後選択した Slice 内で DiskBBQ を使用して KNN を実行します。Slices はデータを整理し、クエリ範囲を制限するために使用されます。テナント認証は引き続きアプリケーションまたはサポートされている Elasticsearch セキュリティメカニズムによって処理されます。

PUT /_slice_collection/knowledge-chunks
{
  "settings": {
    "index.number_of_shards": 2,
    "index.number_of_replicas": 2
  },
  "mappings": {
    "properties": {
      "tenant_id": { "type": "keyword" },
      "document_id": { "type": "keyword" },
      "title": { "type": "text" },
      "content": { "type": "text" },
      "category": { "type": "keyword" },
      "updated_at": { "type": "date" },
      "embedding": {
        "type": "dense_vector",
        "dims": 4,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "bbq_disk"
        }
      }
    }
  }
}

{
  "acknowledged": true
}

PUT /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a
{
  "tenant_id": "tenant-a",
  "document_id": "doc-refund-policy",
  "title": "返金および返品ポリシー",
  "content": "注文完了後 7 日以内に、重複購入の返金をリクエストできます。",
  "category": "アフターサービス",
  "updated_at": "2026-07-30T10:00:00Z",
  "embedding": [0.82, 0.10, 0.05, 0.03]
}

PUT /knowledge-chunks/_doc/chunk-1002?_slice=tenant-b
{
  "tenant_id": "tenant-b",
  "document_id": "doc-shipping-status",
  "title": "配送ステータスの確認",
  "content": "注文詳細ページの物流情報を開いて、最新の配信ステータスを確認できます。",
  "category": "配送",
  "updated_at": "2026-07-30T10:01:00Z",
  "embedding": [0.12, 0.78, 0.06, 0.04]
}

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

POST /knowledge-chunks/_search?_slice=tenant-a
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.80, 0.12, 0.05, 0.03],
    "k": 10,
    "num_candidates": 100
  },
  "_source": ["document_id", "title", "content"]
}

POST /_bulk
{ "index": { "_index": "knowledge-chunks", "_id": "chunk-1003", "_slice": "tenant-a" } }
{ "tenant_id": "tenant-a", "document_id": "doc-change-address", "title": "配送先住所の変更", "content": "注文が発送される前に、注文詳細ページで配送先住所を変更できます。", "category": "注文", "updated_at": "2026-07-30T10:02:00Z", "embedding": [0.75, 0.16, 0.06, 0.03] }
{ "index": { "_index": "knowledge-chunks", "_id": "chunk-1004", "_slice": "tenant-b" } }
{ "tenant_id": "tenant-b", "document_id": "doc-invoice", "title": "電子請求書のリクエスト", "content": "注文完了後、請求書管理ページで電子請求書をリクエストできます。", "category": "課金", "updated_at": "2026-07-30T10:03:00Z", "embedding": [0.18, 0.70, 0.08, 0.04] }

GET /_cat/slice_collection/knowledge-chunks?v

GET /_cat/slice_collection/knowledge-chunks/slices?v

GET /_slice_collection/knowledge-chunks/slices?page_size=100

{
  "slices": [
    { "id": "tenant-a" },
    { "id": "tenant-b" }
  ]
}

GET /_slice_collection/knowledge-chunks/slices?page_size=100&cursor={next_cursor}

ベクトルクラスターリコールモード：自動候補 Slice 選択

EC 検索プラットフォームは大規模な製品ベクトルデータベースを維持しており、オフラインクラスタリングを通じて製品を数千のベクトルクラスターに分割しています。ユーザーが類似製品クエリを開始すると、アプリケーションにはクエリベクトルしかなく、ターゲットクラスターを事前に決定できません。データ量が増加するにつれて、毎回すべての製品データをクエリすると、クエリ範囲およびリソースオーバーヘッドが増大します。

このシナリオはベクトルクラスターリコールモードに適しています。各 Slice はベクトルクラスターに対応し、そのクラスターの重心ベクトルが登録されます。KNN クエリを実行すると、システムはまずクエリベクトルと各クラスター重心との類似性を計算し、最も関連性の高い候補 Slices を自動的に選択し、その後これらの Slices 内で DiskBBQ 検索を並列実行することで、クエリ範囲を絞ります。

Collections はクラスター重心をトレーニングせず、ドキュメントベクトルに基づいてターゲット Slice を自動的に決定しません。アプリケーションは重心ベクトルを事前に計算および登録する必要があります。

このモードを使用するタイミングおよび回避するタイミングについては、「決定ガイド」をご参照ください。

PUT /_slice_collection/products
{
  "slice_strategy": "vector_cluster",
  "auto_create_slice": false,
  "settings": {
    "index.number_of_shards": 2,
    "index.number_of_replicas": 2
  },
  "mappings": {
    "properties": {
      "cluster_id": { "type": "keyword" },
      "name": { "type": "keyword" },
      "embedding": {
        "type": "dense_vector",
        "dims": 2,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "bbq_disk"
        }
      }
    }
  },
  "config": {
    "routing_field": "cluster_id",
    "vector_dims": 2,
    "default_query_vector_path": "knn.query_vector",
    "default_query_slice_count": 128,
    "max_query_slice_count": 512
  }
}

PUT /_slice_collection/products/slices/cluster-a
{
  "vector": [0.9, 0.1]
}

PUT /_slice_collection/products/slices
{
  "slices": [
    {
      "slice_id": "cluster-b",
      "vector": [0.1, 0.9]
    },
    {
      "slice_id": "cluster-c",
      "vector": [0.6, 0.4]
    }
  ]
}

PUT /products/_doc/product-1
{
  "cluster_id": "cluster-a",
  "name": "example-product",
  "embedding": [0.92, 0.08]
}

POST /products/_search?query_slice_count=64
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.91, 0.09],
    "k": 10,
    "num_candidates": 100
  }
}

作成パラメーター

Collection を作成する API は次のとおりです。

PUT /_slice_collection/{collection}

クエリパラメーター：

リクエストボディパラメーターは次のとおりです。

バッキングインデックスに N 個のプライマリシャードがある場合、カウント制限のみに基づいて受け入れ可能な Slices の最大数は N × max_slices_per_shard です。max_slices_per_shard および max_storage_per_shard は、後続の新しい Slices がこのバッキングに割り当てられ続けるかどうかのみを決定します。

• いずれかのしきい値に達した後、システムは新しい Slices をホストするために別のバッキングを選択または作成します。

• 既存の Slices は引き続き書き込みを受け入れることができます。

• しきい値を変更しても、既存の Slices の移行や既存データの再バランスは行われません。

  ほとんどのシナリオでは、デフォルトの last で十分です。複数のバッキングが同時に新しい Slices を受け入れることができ、新しく登録された Slices をランダムに分散させたい場合にのみ、random を使用してください。

Collection の表示

単一の Collection を表示します。

GET /_slice_collection/knowledge-chunks

すべての Collections を表示します。

GET /_slice_collection

この API は master_timeout クエリパラメーターをサポートします。

{collection} はカンマ区切りの名前およびワイルドカードをサポートします。存在しない正確な名前は HTTP 404 を返します。マッチするものがないワイルドカードは空のオブジェクトを返します。

応答例：

{
  "slice_collections": {
    "knowledge-chunks": {
      "collection_uuid": "opaque-system-id",
      "lifecycle_state": "active",
      "max_slices_per_shard": 200,
      "max_storage_per_shard": "50gb",
      "backing_allocation_strategy": "last",
      "future_only_settings": {},
      "auto_create_slice": true,
      "slice_strategy": "exact",
      "max_managed_backing_generation": 0,
      "aliases": {}
    }
  }
}

応答には、システム管理の識別子および generation フィールドが含まれる場合があります。アプリケーションはこれらを不透明な情報として扱い、バッキング名の構築やビジネスロジックの実装に使用しないでください。

Collection の更新

この API は、後続に登録される Slices の割り当て戦略を調整するために使用され、既存の Slices を移動しません。

変更可能な構成を更新します。

POST /_slice_collection/knowledge-chunks/_update
{
  "max_slices_per_shard": 300,
  "max_storage_per_shard": "80gb",
  "backing_allocation_strategy": "last",
  "auto_create_slice": false,
  "settings": {
    "apack.slice_collection.future.index.number_of_shards": 4
  }
}

クエリパラメーター：

更新可能なフィールドには以下が含まれます。

• max_slices_per_shard

• max_storage_per_shard

• backing_allocation_strategy

• auto_create_slice

• settings 内の許可された将来のみの設定

  将来のみの設定は、その後に作成されたバッキングにのみ影響し、既存のバッキングを変更しません。デフォルトで許可されている設定は次のとおりです。

• index.number_of_shards

• index.routing_partition_size

• index.number_of_routing_shards

  _update リクエストでは、将来のみの設定は apack.slice_collection.future. プレフィックスを使用する必要があります。たとえば、index.number_of_shards は apack.slice_collection.future.index.number_of_shards に対応します。書き込み時はフラットプレフィックスを使用します。GET /_slice_collection/{collection} を介して読み取る際は、設定はネストされた構造で表示されます。たとえば、"future_only_settings": {"index": {"number_of_shards": "4"}} です。

成功応答は {"acknowledged":true} です。acknowledged=false は更新がロールバックされたことを意味するのではなく、確認がタイムアウトしたことを示します。

マッピングおよび動的設定の更新

Collection 名を使用してマッピングを更新します。

PUT /knowledge-chunks/_mapping
{
  "properties": {
    "channel": { "type": "keyword" }
  }
}

Collection 名を使用して動的インデックス設定を更新します。

PUT /knowledge-chunks/_settings
{
  "index.refresh_interval": "5s"
}

マッピングおよび動的インデックス設定は、すべての現在のバッキングに適用され、後続のバッキングの統一構成となります。個々のバッキングインデックスを変更しないでください。

Slice の登録

Slice 登録方法を選択する際は、次の表を参照してください。

auto_create_slice=false の場合、または書き込み前にリソース準備を完了したい場合は、Slice を明示的に登録できます。

PUT /_slice_collection/knowledge-chunks/slices/tenant-c

この API は master_timeout クエリパラメーターをサポートします。

応答例：

{
  "acknowledged": true,
  "errors": false,
  "items": [
    {
      "slice_id": "tenant-c",
      "result": "created",
      "backing_index": ".sc-knowledge-chunks-...-00000"
    }
  ]
}

backing_index は観測およびトラブルシューティング目的のみで使用され、後続のアプリケーションリクエストのターゲットとして使用しないでください。

一度に最大 20480 個のユニークな名前の Slices を登録します。

PUT /_slice_collection/knowledge-chunks/slices
{
  "slices": [
    "tenant-d",
    { "slice": "tenant-e" },
    { "slice_id": "tenant-f" }
  ]
}

この API は master_timeout クエリパラメーターをサポートします。3 つの形式は同じリクエスト内で混在できます。

バッチ登録は部分的に成功する可能性があります。各アイテムの result は created、updated、noop、または failed になる場合があります。いずれかのアイテムが失敗すると、トップレベルの errors は true になります。Slice 名が無効（たとえば、: を含む、英数字以外の文字で始まる、予約値 _all を使用する、または長さ制限を超える）の場合、登録 API は HTTP 200 を返し、対応するアイテムで failed およびエラー理由を提供します。

ページネーションによる Slice の一覧表示

GET /_slice_collection/knowledge-chunks/slices?prefix=tenant-&page_size=100

結果は Slice 名の昇順で返されます。ページネーション中に Slices が同時に追加または削除された場合、結果は弱整合性になります。ページネーションを続ける際は、同じ prefix を維持してください。

Slice の削除

DELETE /_slice_collection/knowledge-chunks/slices/tenant-c

クエリパラメーター：

成功応答：

{
  "acknowledged": true
}

Slice 削除後、同じ名前の Slice を再登録できます。新しいデータは、バックグラウンドでクリーンアップが完了するまでの間、古いデータから分離されます。注意点：

• Slice 削除後、Slice 名を指定するクエリは空の結果ではなく、HTTP 404 (resource_not_found_exception) を返します。

• _slice=_all を使用した全範囲クエリは、物理クリーンアップが完了する前に一時的に古いデータを返す場合があります。

• 削除応答はストレージスペースが解放されたことを示しません。

データの書き込みおよび読み取り

Collections は Elasticsearch 標準ドキュメント API を再利用し、_slice を介して名前空間またはベクトルクラスターを指定します。一般的な API は次のとおりです。

ルール：

• 単一ドキュメントリクエストは 1 つの Slice のみを指定できます。カンマ区切りの値および _all は許可されていません。

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

• 一部のドキュメントおよびクエリ API は、論理 Slice を表すために routing を使用できます。サポート範囲および競合ルールについては、「ルーティング互換パラメーター」をご参照ください。

• 各 Bulk リクエストは、最大 512 個の異なる不足している Slices を自動登録できます。既存の Slices はこの制限にカウントされません。

• wait_for_active_shards は、AI Engine Edition 書き込みパイプラインでレプリカを待機する条件として使用されません。ドキュメントが検索可能になるのを待つには、refresh=wait_for を使用してください。

• dense_vector フィールドは、デフォルトで返される _source に含まれません。GET /{collection}/_doc/{id} および GET /{collection}/_source/{id} のいずれもベクトル値を返しません。これらを返すには、明示的に _source_includes を指定してください。

Refresh およびクエリ可視性

書き込みリクエストが成功したことは、データが永続化されたことを示しますが、検索ノードでクエリ可能になったことを意味しません。AI Engine Edition はステートレスアーキテクチャを使用しています。Refresh には、インデックスノードが新しい Commit を生成および公開し、その後検索ノードが新しい検索可能バージョンをロードする必要があります。これは、従来のステートフル Elasticsearch のローカル Refresh よりもオーバーヘッドが高い分散クロスノード操作です。

index.refresh_interval は Collection 設定を通じてクエリおよび調整できます。現在の値は GET /{collection}/_settings を使用して確認できます。Refresh 間隔を短くするとリソースオーバーヘッドが増加します。本番環境では、5s 以上に設定してください。低遅延可視性要件がある場合は、ビジネスワークロードに基づいて値を調整してください。実際の有効値は現在の Collection 設定に基づいています。自動 Refresh は値を -1 に設定することで無効にできます。この間隔を短縮する前に、Commit 公開頻度、書き込みスループット、およびオブジェクトストレージ I/O を評価してください。

クエリ可視性のビジネス要件に基づいて、以下のいずれかの方法を選択してください。

index.refresh_interval=-1 は自動 Refresh を無効にします。この場合、refresh=wait_for を使用した書き込みは、別のリクエストが明示的な Refresh をトリガーするまで無期限に待機します。明示的な Refresh プロセスなしにこれらの設定を組み合わせないでください。本番環境で読み取り後書き込みが必要な場合、ビジネス遅延要件に基づいて自動 Refresh を待つか明示的な Refresh を選択し、分散 Refresh オーバーヘッドを評価してください。Refresh はクエリ可視性のみに対処します。すべてのクエリレプリカが利用可能であることを意味せず、クエリプローブおよび高可用性チェックに代わるものではありません。

Bulk

Bulk アイテムの各アクションメタデータは、クイックスタートの例のように独自の _slice を提供できます。バッチ内のすべてのアイテムが同じ Slice に書き込まれる場合、URL でデフォルト値を提供できます。

POST /knowledge-chunks/_bulk?_slice=tenant-a
{ "index": { "_id": "chunk-2001" } }
{ "tenant_id": "tenant-a", "document_id": "doc-account-security", "title": "アカウントセキュリティ設定", "content": "管理者はセキュリティ設定ページで多要素認証 (MFA) を有効化できます。" }

アイテムの _slice は URL のデフォルト値を上書きできます。名前空間モードはドキュメントフィールドから Slice を導出しません。ドキュメント本文に tenant_id フィールドが含まれていても、実際の書き込み場所は _slice によって決定されます。エラー処理については、「一般的な API 規則」をご参照ください。

Multi Get

MGet は、既知の ID を持つ複数のドキュメントを一度に読み取るのに適しています。各アイテムは異なる Slice にアクセスできます。

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

URL の _slice はデフォルト値として機能できます。各アイテムはデフォルト値を上書きできます。各アイテムは最終的に単一の Slice に解決する必要があります。

Reindex

Reindex は、通常のインデックスと Collections 間、または異なる Collections 間でのデータ移行に適しています。同じ Collection 内で Slice をコピーするには、Copy Slice を使用してください。

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

POST /_reindex
{
  "source": {
    "index": "source-knowledge-chunks",
    "_slice": "tenant-a,tenant-b"
  },
  "dest": {
    "index": "target-knowledge-chunks",
    "_slice": "=tenant-archive"
  }
}

宛先 Slice は存在しない場合、自動的に登録されます。トップレベルの slices パラメーターは Elasticsearch Reindex の並列性を表し、ビジネス Slices の数とは無関係です。いずれかの側が Collection の場合、Reindex はスクリプトをサポートしません。Collection が宛先の場合、明示的なインジェストパイプラインはサポートされていません。

データのクエリ

Collection クエリは引き続き Elasticsearch Query DSL を使用します。このセクションでは、AI Engine Edition が追加した Slice クエリ範囲のみを取り上げます。このガイドに記載されていない Query DSL およびクエリ機能については、9.99.0 インスタンスの実際のサポート範囲が優先されます。

クエリで明示的に _slice を指定することは、両方のモードに適用されます。名前空間モードでは通常、明示的なクエリ範囲が必要です。ベクトルクラスターリコールモードの KNN クエリは、複数の候補 Slices を自動的に選択できます。詳細については、「ベクトルクラスターリコールモード：自動候補 Slice 選択」をご参照ください。

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

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

GET /knowledge-chunks/_search

PUT /_slice_collection/knowledge-chunks
{
  "settings": {
    "index.sliced_postings.enabled": true
  }
}

Warm Slice キャッシュ

_warm_slice API は、オブジェクトストレージから検索ノード上の共有キャッシュに、指定された Slice への後続のクエリがアクセスする可能性のあるデータをプリフェッチし、コールドデータの初回クエリ遅延を削減します。ウォーミング範囲には、DiskBBQ ベクトル、Slice 関連の転置インデックスデータ、doc values、および格納フィールドが含まれ、Slice が存在するシャードのすべての検索可能レプリカをカバーします。

ウォーミングはキャッシュ最適化のためのみです。後続のアクセス速度にのみ影響し、クエリ結果を変更せず、データがキャッシュにどれだけ留まるかを保証しません。

ウォーミングの使用例：

• ユーザーが長期間アクセスしていないナレッジベース、コードリポジトリ、またはエージェントメモリスペースを開こうとしている場合。最初のクエリの前に対応する Slice をウォーミングできます。

• バッチインポートまたはデータ移行が完了した後、クエリトラフィックを切り替える前に、アクティブ化される予定の Slices をウォーミングできます。

• 特定の名前空間が特定の時間帯にアクセスピークを経験することがわかっている場合。これらの Slices を事前にウォーミングできます。

  データアクセスが予測不可能な場合、多数の Slices を一度にウォーミングする必要がある場合、またはターゲット Slices がすでにホットデータである場合は、アクティブなウォーミングは推奨されません。大規模なウォーミングはオブジェクトストレージおよび検索ノードのネットワーク、キャッシュ、および計算リソースを消費します。また、既存のホットデータをキャッシュから追い出す可能性もあります。

POST /knowledge-chunks/_warm_slice?_slice=tenant-a

{
  "status": "ACCEPTED",
  "message": "cache warm hint accepted",
  "task": "{nodeId}:{taskId}"
}

GET /_tasks/{nodeId}:{taskId}

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&store_result=true

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&wait_for_completion=true&timeout=60s

DiskBBQ ベクトルインデックス

DiskBBQ は、dense_vector の bbq_disk インデックスタイプに対応します。これはシャード内で使用されるベクトルインデックス機能であり、第 3 の Collection モードではありません。名前空間モードおよびベクトルクラスターリコールモードの両方で DiskBBQ を使用できます。このセクションでは、構成およびクエリ方法について説明します。AI Engine Edition のパフォーマンスリファレンスについては、機能概要をご参照ください。

DiskBBQ の使用例：

• ベクトルスケールが大きく、ディスクネイティブベクトルインデックスを通じて常駐メモリ圧力を軽減したい場合。

• ビジネス評価データセットを使用して、取得率、クエリ遅延、およびデータ読み取りオーバーヘッドのバランスを調整できる場合。

  データセットが小さい場合、正確な最近傍結果が必要な場合、または取得率評価が完了していない場合は、DiskBBQ をデフォルトアプローチとして推奨しません。

PUT /{collection}/_mapping
{
  "properties": {
    "embedding": {
      "type": "dense_vector",
      "dims": 4,
      "index": true,
      "similarity": "cosine",
      "index_options": {
        "type": "bbq_disk"
      }
    }
  }
}

{
  "index_options": {
    "type": "bbq_disk",
    "cluster_size": 384,
    "flat_index_threshold": -1,
    "default_visit_percentage": 0.0,
    "rescore_vector": { "oversample": 3.0 },
    "bits": 1
  }
}

POST /knowledge-chunks/_search?_slice=tenant-a
{
  "knn": {
    "field": "embedding",
    "query_vector": [0.80, 0.12, 0.05, 0.03],
    "k": 10,
    "visit_percentage": 10.0
  },
  "_source": ["document_id", "title", "content"]
}

Collection Alias

Collection Alias は、アプリケーションに安定したアクセス名を提供します。複数の Collections を統一的にクエリしたり、書き込みターゲットを切り替えたりするために使用できます。aliases フィールドを使用して Collection 作成時に Alias を追加するか、標準の Elasticsearch _aliases API を使用して Alias を管理できます。

Collection Alias の使用例：

• バージョン移行：アプリケーションは常に固定の Alias にアクセスします。データ準備が完了したら、書き込みターゲットを古い Collection から新しい Collection に切り替えます。

• マルチ Collection クエリ：slice_strategy が同じ複数の Collections を単一の Alias を介してクエリします。

• アプリケーションデカップリング：ビジネス構成は Alias のみを保存し、バージョンまたは日付を含む Collection 名に直接依存しません。

  ビジネスが Alias filter または routing に依存している場合、または通常のインデックスと Collections の両方を同じ Alias に含めたい場合は、Collection Alias は適用されません。

次の例では、knowledge-chunks-v1 および knowledge-chunks-v2 の両方が名前空間モード (exact) を使用する Collections であると仮定します。これらを同じ Alias に追加し、knowledge-chunks-v2 を書き込みターゲットに設定します。

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "knowledge-chunks-v1",
        "alias": "knowledge-chunks-current"
      }
    },
    {
      "add": {
        "index": "knowledge-chunks-v2",
        "alias": "knowledge-chunks-current",
        "is_write_index": true
      }
    }
  ]
}

Alias を表示します。

GET /_alias/knowledge-chunks-current

Alias からメンバーを削除します。

POST /_aliases
{
  "actions": [
    {
      "remove": {
        "index": "knowledge-chunks-v1",
        "alias": "knowledge-chunks-current"
      }
    }
  ]
}

Alias を使用する際の注意点：

• 同じ Alias のメンバーは、同じ slice_strategy を使用する必要があります。ベクトルクラスターリコールモード (vector_cluster) を使用するメンバーは、同じベクトル次元も使用する必要があります。

• マルチメンバー Alias を書き込みに使用する場合、正確に 1 つのメンバーが is_write_index=true を持つ必要があります。

• Search、Count、Bulk などの API は、Alias セマンティクスに基づいてマルチメンバー Alias にアクセスできます。

• 単一ドキュメント GET および MGet の各アイテムは、1 つの Collection に一意に解決する必要があります。したがって、単一メンバー Alias のみを使用できます。

• filter、routing、index_routing、search_routing、is_hidden、および remove_index は、現在 Alias でサポートされていません。

  マルチメンバー Alias をクエリする場合、ターゲット Slice はすべてのメンバー Collections に存在する必要があります。そうでない場合、HTTP 404 が返されます。バージョン移行中は、古い Collection と新しい Collection の Slice セットが通常異なります。この場合、明示的に ignore_missing_slice=true を含めてください（例：GET /knowledge-chunks-current/_search?_slice=tenant-a&ignore_missing_slice=true）。これにより、リクエストは不足しているメンバーをスキップして正常に返されます。

Copy Slice

Copy Slice は、同じ Collection 内で 1 つの Slice から別の Slice に複製可能なドキュメントをオンラインでコピーします。データ移行には適していますが、時点スナップショット、バックアップ、またはアトミックトラフィックスイッチングには適していません。

Copy Slice の使用例：

• テナントのテストまたは検証データをコピーしながら、ソース Slice と同じ Collection マッピングを維持します。

• 同じ Collection 内で新しい名前空間を準備します。コピーが完了して検証された後、アプリケーション層でアクセス名を切り替えます。

• Slice のオンラインデータ移行を実行しながら、ソース Slice および宛先 Slice の両方を読み取りおよび書き込み可能に維持します。

  コピー中に書き込みが発生する可能性があるため、結果はソースの時点スナップショットではありません。バックアップ、ディザスタリカバリ、厳密に一貫性のあるスナップショット、またはアトミックトラフィックスイッチングには、Copy Slice を使用しないでください。

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

{
  "copy_id": "tenant-a-copy:1h",
  "completed": false,
  "timed_out": false,
  "state": "RUNNING",
  "source": "tenant-a",
  "target": "tenant-a-copy",
  "workers": 8,
  "progress": { "total": 0, "created": 0, "version_conflicts": 0 },
  "status_url": "/_slice_collection/knowledge-chunks/_copy/tenant-a-copy%3A1h",
  "cancel_url": "/_slice_collection/knowledge-chunks/_copy/tenant-a-copy%3A1h/_cancel"
}

GET /_slice_collection/knowledge-chunks/_copy/{copy_id}

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

POST /_slice_collection/knowledge-chunks/_copy/{copy_id}/_cancel

クラスターモニタリング

コンソールのインスタンス詳細ページの左側ナビゲーションウィンドウで、モニタリングとログ > クラスターモニタリング を選択して、インスタンスの実行メトリクスを表示します。アラートのしきい値を構成する際は、ビジネス SLO およびストレステストのベースラインに基づいて設定してください。具体的なメトリック名およびアラートエントリポイントは、コンソールに基づいています。

次の表に、一般的な観測ターゲットとコンソールメトリクスのマッピングを示します。

クラスターモニタリングページはメトリクスをカテゴリ別にグループ化しており、インデックスノードおよび検索ノードのロール別グループ化は提供していません。2 種類のノードを別々に観測するには、リソースタイプ を 指定ノード に切り替え、その後ノード名でフィルターをかけます。インデックスノード名には -index- が含まれ、検索ノード名には -search- が含まれます。AI Engine Edition にはウォームノードがありません。インデックスノード、検索ノード、および AI Engine Edition が実際に提供する監視メトリクスのみを監視する必要があります。

CAT API

CAT API は手動観測およびトラブルシューティングに適しています。日常的な概要については、Collection から始めます。容量またはシャード異常が発生した場合は、バッキングを確認します。特定の名前空間のデータ分布およびドキュメント数を特定するには、Slice を確認します。アプリケーションは、ビジネスリクエストのために CAT 出力に依存しないでください。

デフォルトカラム：

一般的なクエリパラメーター：

Slice CAT は、特定の完全なバッキング名に範囲を絞るために backing={backing} もサポートします。docs.count で全バッキングをソートするのは高コストなクエリであり、明示的に allow_expensive_search=true を設定する必要があります。

プログラムによる処理には、format=json を使用し、カラムを明示的に指定します。

GET /_cat/slice_collection/knowledge-chunks?format=json&h=collection,state,backings,slices,docs.count,pri.store.size

CAT API は手動トラブルシューティングおよび有界操作クエリ用に設計されています。

• Slice CAT は最大 10000 行を返します。制限を超えると、HTTP Warning ヘッダーで結果が不完全であることが示されます。

• 完全かつ安定したページネーションされた Slice リストが必要な場合は、GET /_slice_collection/{collection}/slices を使用してください。

• docs.count はニアリアルタイムデータです。書き込まれたがまだ Refresh されていないドキュメントはカウントされない場合があります。

• pri.store.size および store.size はインデックスデータサイズを表しますが、ステートレスノードのローカルディスク使用量と同等ではありません。また、クリーンアップ待ちのオブジェクトストレージ内の既存データも含まれていません。

Collection の削除

この API は、ビジネスデータをオフラインにする場合や、このガイドの例をクリーンアップする場合に適用されます。削除により、Collection 構成およびシステム管理データが削除されます。この操作は不可逆です。特定の Slice のみをクリーンアップするには、Slice 削除 API を使用してください。

DELETE /_slice_collection/knowledge-chunks

クエリパラメーター：

成功応答：

{
  "acknowledged": true
}

{collection} はカンマ区切りの名前をサポートします。デフォルトでは、ワイルドカード * および _all は許可されていません。リクエストは HTTP 400 を返します。これらを使用するには、action.destructive_requires_name クラスター設定を調整してください。

Copy Slice 操作が実行中またはキャンセル中の場合、削除は HTTP 409 を返します。キャンセルは非同期です。state が CANCELLED に変更されるまで、削除は拒否され続けます。state=CANCELLED を確認してから削除を実行してください。

acknowledged=true は、論理リソースおよびメタデータの削除が確認されたことを示します。オブジェクトストレージ内の既存インデックスおよび Translog ファイルは、バックグラウンドプロセスによって非同期的に回収されます。応答が返された時点で物理スペースが即座に解放されるとは限りません。

Collection 権限

ロールを構成する際は、インデックス名に Collection 名および対応するバッキングワイルドカードの両方を含める必要があります。

<collection>
.sc-<collection>-*

たとえば、Collection 名が knowledge-chunks の場合、ロールに knowledge-chunks および .sc-knowledge-chunks-* の両方を構成します。Collection 名のみを構成すると、単一ドキュメントの読み取り/書き込み、MGet、明示的な Refresh、および _update_by_query などの操作が HTTP 403 を返します。

.sc-* は権限構成専用です。アプリケーションは引き続き Collection 名を介してデータにアクセスし、特定のバッキングインデックス名を直接アクセスまたは保存しないでください。

Slices はテナント権限隔離の境界ではありません。権限を分離するには、アプリケーション層または他のサポートされている Elasticsearch セキュリティモデルで実装してください。

従来のステートフル Elasticsearch との一般的な違い

次の表で該当なしとマークされた設定は、変更時に HTTP 200 を返し、新しい値が読み取り時に表示される場合があります。これは、機能が有効になったことを示しません。

さらに、ステートレスアーキテクチャのレプリカは主にクエリおよびキャッシュに使用されます。従来のステートフル Elasticsearch の永続レプリカ（プライマリシャードに昇格可能）とは同等ではありません。クエリレプリカ数および検索ノード数が together でクエリ容量および可用性を決定します。永続データはオブジェクトストレージに格納されます。レプリカ数を増やしてもバックアップ戦略に代わるものではありません。

Collections および Slices 使用時の制限事項

以下の制限事項は、AI Engine Edition の Collection および Slice 使用にのみ適用されます。同じ名前の機能が通常のインデックスでも利用できないことを意味するものではありません。

API クイックリファレンス

以下は、このガイドのユースケースに必要な 9.99.0 パブリック API の概要です。これは完全な Elasticsearch API リストではなく、内部で維持されている API も含まれていません。