Elasticsearch:コレクションとスライスの管理

コレクションの作成

コレクション名は、Elasticsearch のインデックスとエイリアスの命名規則に準拠する必要があります。名前は小文字で、長さが 128 バイトを超えてはならず、システム予約のプレフィックス .sc- を使用することはできません。

PUT /_slice_collection/{collection}

クエリパラメーター：master_timeout (マスターノードがリクエストを処理するのを待つ時間) と timeout (作成の確認応答を待つ時間)。

次の表に、リクエストボディのパラメーターを示します。

例：

PUT /_slice_collection/knowledge-chunks
{
  "max_slices_per_shard": 200,
  "max_storage_per_shard": "50gb",
  "settings": {
    "index.number_of_shards": 2,
    "index.number_of_replicas": 2
  },
  "mappings": {
    "properties": {
      "tenant_id": { "type": "keyword" },
      "category": { "type": "keyword" }
    }
  }
}

成功レスポンスのサンプル：

{
  "acknowledged": true
}

acknowledged=true は、コレクション設定が作成されたことを示します。リクエストがタイムアウトした場合や接続に失敗した場合は、GET /_slice_collection/knowledge-chunks を呼び出して実際の状態を確認してください。リトライのレスポンスに基づいてコレクションが作成されたかどうかを判断しないでください。

PUT /_slice_collection/text-search-demo
{
  "settings": {
    "index.sliced_postings.enabled": false
  }
}

コレクションの表示

GET /_slice_collection/knowledge-chunks

すべてのコレクションを一覧表示します：

GET /_slice_collection

{collection} は、カンマ区切りの名前とワイルドカードをサポートしています。正確な名前が存在しない場合は、HTTP 404 が返されます。ワイルドカードに一致する項目がない場合は、{"slice_collections": {}} が返されます。

クエリパラメーター：

この API は、ターゲットコレクションに対する monitor インデックス権限のみを必要とします。クラスターレベルの monitor 権限は必要ありません。

レスポンスのサンプル：

{
  "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,
      "latest_backing": {
        "settings": {
          "index": {
            "number_of_shards": "2",
            "number_of_replicas": "2"
          }
        },
        "mappings": {
          "properties": {
            "tenant_id": { "type": "keyword" },
            "category": { "type": "keyword" }
          }
        }
      },
      "aliases": {}
    }
  }
}

フィールドの説明：

• latest_backing は、まだ存在する最新のバッキングインデックスから取得されます。settings には、バッキングの現在の継承可能で公開されている設定が含まれます。これには、システムによって自動的に追加されたり、後で更新されたりしたフィールドが含まれる場合があります。mappings は、バッキングの現在のマッピングであり、したがって動的に追加されたフィールドも含まれます。

• future_only_settings は、後で作成されるバッキングにのみ影響し、現在の最新のバッキングがすでにこれらの値を使用していることを示すものではありません。

• collection_uuid と max_managed_backing_generation は、システム管理用のフィールドです。アプリケーションはこれらを不透明な情報として扱い、バッキング名の構築やビジネスロジックの実装に使用してはなりません。

コレクションの更新

この API は、後続で登録されるスライスのアロケーションポリシーを調整します。既存のスライスを移動するものではありません。すべての現在のバッキングのマッピングまたは動的インデックス設定を変更するには、代わりに次のセクションで説明するマッピングと動的設定の更新 API を使用してください。

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 は、確認応答の待機がタイムアウトしたことを示します。更新がロールバックされたことを示すものではありません。

マッピングと動的設定の更新

コレクション名を使用してマッピングを更新します：

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

コレクション名を使用して動的インデックス設定を更新します。 次の例では、更新間隔をデフォルト値 5s にリセットします。 Collection の作成時に、このデフォルト値を明示的に設定する必要はありません。 この変更は Collection 全体に影響します。 使用条件については、「リフレッシュとクエリの可視性」をご参照ください：

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

マッピングと動的インデックス設定は、すべての現在のバッキングに適用され、後続のバッキングの統一された設定になります。同じコレクション内のすべてのスライスは、これらの設定を共有します。特定のスライスのフィールドタイプやインデックス設定を個別に変更することはできません。バッキングインデックスを個別に変更しないでください。

変更が有効になったことを確認するには、GET /_slice_collection/{collection} を呼び出して latest_backing の値を読み戻します。mappings フィールドは現在のマッピングを反映し、settings フィールドは現在のインデックス設定を反映します。

バッキングの事前作成

デフォルトでは、システムはオンデマンドでバッキングインデックスを作成します。新しいスライスを登録するときに、既存のすべてのバッキングが容量のしきい値に達した場合、システムは次のバッキングの自動作成を実行します。多数のテナントを有効にしたり、データをバッチでインポートしたりする前に、これらの基盤となるインデックスを事前に準備して、最初のバッチのスライスが登録される際のインデックス作成の待機レイテンシを短縮できます。

バッキングの事前作成とスライスの登録は、個別の操作です。前者はデータストレージ用のインデックスを準備し、後者はアプリケーションがアクセスするビジネスパーティションを作成します。事前作成では、テナントスライスが自動的に登録されたり、既存のデータが移動されたりすることはありません。コレクションの manage 権限を持つアカウントは、この API を呼び出すことができます。完全な権限構成については、「コレクションの権限」をご参照ください。

PUT /_slice_collection/knowledge-chunks/backings?count=5

PUT /_slice_collection/knowledge-chunks/backings
{
  "count": 5
}

{
  "acknowledged": true,
  "backings": [
    ".sc-knowledge-chunks-...-00000",
    ".sc-knowledge-chunks-...-00001",
    ".sc-knowledge-chunks-...-00002",
    ".sc-knowledge-chunks-...-00003",
    ".sc-knowledge-chunks-...-00004"
  ],
  "created_backings": [
    ".sc-knowledge-chunks-...-00001",
    ".sc-knowledge-chunks-...-00002",
    ".sc-knowledge-chunks-...-00003",
    ".sc-knowledge-chunks-...-00004"
  ],
  "existing_backings": [
    ".sc-knowledge-chunks-...-00000"
  ]
}

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

GET /_slice_collection/knowledge-chunks

POST /_slice_collection/knowledge-chunks/_update
{
  "backing_allocation_strategy": "last"
}

スライスの登録

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

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

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

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

スライスのクエリ

GET /_slice_collection/{collection}/slices/{slice}

クエリパラメーター：

レスポンスのサンプル：

{
  "slice": "tenant-a",
  "backing_index": ".sc-knowledge-chunks-...-00000",
  "created_at": "2026-08-12T00:00:00.000Z"
}

created_at は、スライスが作成された時刻を UTC ISO 8601 形式で示します。

スライスが存在するかどうかを確認したり、その情報を読み取ったりするだけの場合は、前述のデフォルトリクエストを使用してください。include_doc_count=true は、ドキュメントをカウントするために追加のデータクエリを実行します。多数のスライスの頻繁なポーリングやバッチチェックには使用しないでください。検索可能なドキュメント数を確認する必要がある場合にのみ呼び出してください：

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

レスポンスにはさらに以下が含まれます：

{
  "docs": {
    "count": 12500
  }
}

使用上の注意：

• docs.count は、現在の検索可能なドキュメント数を示します。最近書き込まれたがまだリフレッシュされていないドキュメントは含まれない場合があります。

• この API は、現在有効なスライスのみをクエリします。コレクションまたはスライスが存在しない場合、またはスライスが削除されている場合は、HTTP 404 が返されます。

• クエリはスライスを作成しません。最初にスライスを明示的に登録するか、自動登録が有効になっている場合は最初にスライスに書き込みます。

• この API は、単一の Slice のストレージサイズを提供しません。ストレージ統計を取得するには、Backing CAT またはネイティブの Index Stats API を使用します。詳細については、「Backing CAT および Slice CAT コマンド」をご参照ください。

• シャードとレプリカはバッキングレベルで設定されます。スライスが実際にアクセスするプライマリシャードを表示するにはスライス CAT を使用し、レプリカ設定を表示するにはバッキング CAT を使用してください。

ページごとのスライス一覧表示

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

レスポンスのサンプル：

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

次のページが存在しない場合、next_cursor は省略されます。結果はスライス名の昇順で返されます。ページネーション中にスライスが同時に追加または削除された場合、ページ分割された結果は弱い整合性を提供します。ページネーションを続けるときは、同じ prefix を維持してください。

スライスの削除

スライスが削除されると、そのスライスとすべてのドキュメントは元の名前でアクセスできなくなります。同じ名前でスライスを再登録しても、古いデータは回復できません。次のリクエストを実行する前に、ターゲットのビジネススペースを確認してください：

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

クエリパラメーター：

成功レスポンスのサンプル：

{
  "acknowledged": true
}

このレスポンスは、元のスライス名がもはやアクセスできないことを示します。古い物理データが完全に削除されたことや、ストレージスペースが解放されたことを示すものではありません。後で同じ名前のスライスを登録できます。新しいデータは、バックグラウンドでクリーンアップ待ちの古いデータから隔離されたままです。アプリケーションは、削除、同じ名前での再作成、および自動登録をトリガーする可能性のある書き込みを調整する必要があります。削除結果が不確かな場合は、まずスライスのライフサイクル状態を確認してください。同じ名前のスライスが再作成されている場合は、元の名前を使用して DELETE をむやみに再送信しないでください。そうしないと、新しいスライスが削除される可能性があります。さらに：

• スライスが削除された後、スライス名を指定したクエリは、空の結果ではなく HTTP 404 (resource_not_found_exception) を返します。

• 物理的なクリーンアップが完了する前に、_slice=_all を使用した完全なクエリは、一時的に古いデータを返す可能性があります。特定のスライス名のクエリは、削除された古いデータにアクセスしません。

  1 つのスライスのみを削除する必要がある場合は、この API を使用してください。コレクション全体を削除しないでください。コレクションを削除するには、「コレクションの削除」をご参照ください。

コレクションの削除

この API は、すべてのビジネスデータを廃止する場合や、サンプルデータを削除する場合に適しています。削除すると、Collection の構成とシステム管理データが削除されます。この操作は元に戻すことはできません。1 つのスライスのみを削除する必要がある場合は、スライスの削除を使用してください。

DELETE /_slice_collection/knowledge-chunks

クエリパラメーター：master_timeout と timeout。

成功レスポンスのサンプル：

{
  "acknowledged": true
}

• {collection} はカンマ区切りの名前をサポートしています。削除する各コレクションを明示的に指定することを推奨します。デフォルトでは、action.destructive_requires_name の安全策により、ワイルドカード * と _all は拒否され、HTTP 400 が返されます。単にサンプルデータを削除するために、このクラスターレベルの安全策を無効にしないでください。

• コピースライスが RUNNING または CANCELLING 状態の場合、削除リクエストは HTTP 409 を返します。コピーのキャンセルは非同期です。コレクションを削除する前に、completed=true であり、コピーが終端状態に入ったことを確認してください。

• acknowledged=true は、論理リソースとメタデータの削除が確認されたことを示します。オブジェクトストレージ内の履歴インデックスと Translog ファイルは、バックグラウンドプロセスによって非同期で回収されます。レスポンスが返されたときに物理スペースがすぐに解放されることは保証されません。

コレクションエイリアスの管理

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

シナリオ：

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

• 複数コレクションのクエリ：同じ slice_strategy を使用する複数のコレクションを 1 つのエイリアスでクエリします。

• アプリケーションのデカップリング：バージョンや日付を含むコレクション名に直接依存するのではなく、ビジネス設定にエイリアスのみを保存します。

  使用する前に、「コレクションエイリアスのサポート」を確認して、既存のエイリアス設定がサポートされていることを確認してください。

バージョン移行の場合、まずデータ移行を完了し、移行中の増分書き込みを処理し、新しいコレクションのデータが検索可能であることを確認し、アクセスされるスライスをウォームアップします。次に、同じリクエストで、古いコレクションをエイリアスから削除し、新しいコレクションをエイリアスに追加します。エイリアスの更新はアトミックですが、データを自動的にコピーまたは同期するものではありません。次の例では、読み取りおよび書き込みトラフィックを knowledge-chunks-v1 から knowledge-chunks-v2 にアトミックに切り替えます：

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

次の例は、バージョン移行ではなく、複数コレクションのクエリ用です。knowledge-chunks-v1 と knowledge-chunks-v2 が両方とも名前空間モードのコレクションであり、2 つのコレクションのデータが重複していないと仮定します。それらを同じエイリアスに追加し、knowledge-chunks-v2 を書き込みターゲットとして設定します。検索クエリは両方のコレクションをクエリします。is_write_index は書き込み場所のみを決定し、クエリスコープを制限しません。

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
      }
    }
  ]
}

エイリアスの表示：

GET /_alias/knowledge-chunks-current

複数メンバーのエイリアスで欠落している可能性のあるスライスをクエリします：

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

エイリアスを使用する際は、次の点に注意してください：

• 複数メンバーのエイリアスを書き込みに使用する場合、正確に 1 つのメンバーが is_write_index=true である必要があります。

• Search、Count、Bulk などの API は、エイリアスのセマンティクスに従って複数メンバーのエイリアスにアクセスできます。

• 単一ドキュメントの GET リクエストと MGet リクエストの各項目は、正確に 1 つのコレクションに解決される必要があります。したがって、単一メンバーのエイリアスのみを使用できます。is_write_index は、単一ターゲットの読み取りのためにメンバーを選択しません。

• エイリアスの更新はアトミックに適用されます。デフォルトでは、remove は少なくとも 1 つの既存のメンバーに一致する場合に成功します。must_exist=true は、各特定のターゲットを厳密に検証します。レスポンスには acknowledged のみが含まれ、アクションごとの結果は含まれません。

• 複数メンバーのエイリアスをクエリする場合、ターゲットスライスはすべてのメンバーコレクションに存在する必要があります。そうでない場合、HTTP 404 が返されます。欠落している可能性のあるスライスをクエリするには、明示的に ignore_missing_slice=true を含めてください。リクエストはスライスが欠落しているメンバーをスキップし、通常どおり結果を返します。