Elasticsearch:Manage Collections and Slices

Create a Collection

Collection names must comply with the Elasticsearch naming rules for indexes and aliases. A name must be lowercase, cannot exceed 128 bytes in length, and cannot use the system-reserved .sc- prefix.

PUT /_slice_collection/{collection}

Query parameters: master_timeout (the time to wait for the master node to process the request) and timeout (the time to wait for creation acknowledgment).

The following table describes the request body parameters.

Example:

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

Sample success response:

{
  "acknowledged": true
}

acknowledged=true indicates that the Collection configuration is created. If the request times out or the connection fails, call GET /_slice_collection/knowledge-chunks to check the actual status. Do not determine whether the Collection was created based on the response to a retry.

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

View Collections

GET /_slice_collection/knowledge-chunks

List all Collections:

GET /_slice_collection

{collection} supports comma-separated names and wildcards. If an exact name does not exist, HTTP 404 is returned. If a wildcard has no matching item, {"slice_collections": {}} is returned.

Query parameters:

This API requires only the monitor index privilege on the target Collection. The cluster-level monitor privilege is not required.

Sample response:

{
  "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": {}
    }
  }
}

Field descriptions:

• latest_backing comes from the latest Backing Index that still exists. settings contains the current inheritable and public settings of the Backing. It may include fields that were automatically added by the system or subsequently updated. mappings is the current Mapping of the Backing and therefore also includes dynamically added fields.

• future_only_settings affects only subsequently created Backings and does not indicate that the latest current Backing already uses these values.

• collection_uuid and max_managed_backing_generation are fields for system administration. Applications must treat them as opaque information and must not use them to construct Backing names or implement business logic.

Update a Collection

This API adjusts the allocation policy for subsequently registered Slices. It does not move existing Slices. To change the Mapping or dynamic index settings for all current Backings, use the Mapping and dynamic Settings update API described in the next section instead.

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

Query parameters:

The following fields can be updated: max_slices_per_shard, max_storage_per_shard, backing_allocation_strategy, auto_create_slice, and allowed future-effective settings in settings.

Future-effective settings affect only Backings created later and do not modify existing Backings. The following settings are allowed by default:

• index.number_of_shards

• index.routing_partition_size

• index.number_of_routing_shards

  In an _update request, these settings must use the apack.slice_collection.future. prefix. For example, index.number_of_shards corresponds to apack.slice_collection.future.index.number_of_shards. Use the flattened prefix when writing the setting. When you read it back by using GET /_slice_collection/{collection}, it is displayed as a nested structure, such as "future_only_settings": {"index": {"number_of_shards": "4"}}.

A successful response is {"acknowledged": true}. acknowledged=false indicates that the wait for acknowledgment timed out. It does not indicate that the update was rolled back.

Update the Mapping and dynamic settings

Update the Mapping by using the Collection name:

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

Update dynamic index settings by using the Collection name. The following example resets the refresh interval to the default value 5s. You do not need to explicitly configure this default value when you create the Collection. The change affects the entire Collection. For usage conditions, see Refresh and query visibility:

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

The Mapping and dynamic index settings are applied to all current Backings and become the unified configuration for subsequent Backings. All Slices in the same Collection share these configurations. You cannot separately modify the field type or index settings for a specific Slice. Do not modify Backing Indexes individually.

To verify that a change took effect, call GET /_slice_collection/{collection} and read back the latest_backing value. The mappings field reflects the current Mapping, and the settings field reflects the current index settings.

Pre-create Backings

By default, the system creates Backing Indexes on demand. When you register a new Slice, if all existing Backings have reached their capacity thresholds, the system performs automatic creation of the next Backing. Before you enable a large number of tenants or import data in batches, you can prepare these underlying indexes in advance to reduce the latency of waiting for index creation when the first batch of Slices is registered.

Pre-creating Backings and registering Slices are separate operations. The former prepares indexes for data storage, whereas the latter creates business partitions that applications access. Pre-creation does not automatically register tenant Slices or move existing data. An account that has the Collection manage privilege can call this API. For the complete privilege configuration, see Collection privileges.

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

Register Slices

Refer to the following table when you select a registration method.

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

Query a Slice

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

Query parameters:

Sample response:

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

created_at is the time when the Slice was created, in UTC ISO 8601 format.

To only check whether a Slice exists or read its information, use the preceding default request. include_doc_count=true runs an additional data query to count documents. Do not use it for frequent polling or batch checks of a large number of Slices. Call it only when you need to check the number of searchable documents:

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

The response additionally contains:

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

Usage notes:

• docs.count indicates the current number of searchable documents. Documents that were recently written but not yet refreshed may not be included.

• This API queries only currently valid Slices. If the Collection or Slice does not exist or the Slice has been deleted, HTTP 404 is returned.

• A query does not create a Slice. Explicitly register the Slice first, or write to the Slice first if automatic registration is enabled.

• This API does not provide the storage size of a single Slice. To obtain storage statistics, use Backing CAT or the native Index Stats API. For more information, see the Backing CAT and Slice CAT commands.

• Shards and replicas are configured at the Backing level. Use Slice CAT to view the primary shards that a Slice actually accesses and Backing CAT to view the replica configuration.

List Slices by page

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

Sample response:

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

If no next page exists, next_cursor is omitted. Results are returned in ascending order by Slice name. If Slices are concurrently added or deleted during pagination, the paginated results provide weak consistency. Keep the same prefix when you continue pagination.

Delete a Slice

After a Slice is deleted, the Slice and all its documents can no longer be accessed by using the original name. Re-registering a Slice with the same name cannot recover the old data. Confirm the target business space before you run the following request:

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

Query parameters:

Sample success response:

{
  "acknowledged": true
}

This response indicates that the original Slice name is no longer accessible. It does not indicate that the old physical data has been completely removed or that storage space has been released. You can subsequently register a Slice with the same name. New data remains isolated from old data that is pending cleanup in the background. The application must coordinate deletion, recreation with the same name, and writes that may trigger automatic registration. If the deletion result is uncertain, first check the Slice lifecycle state. If a Slice with the same name has been recreated, do not blindly resend DELETE by using the original name. Otherwise, the new Slice may be deleted. In addition:

• After a Slice is deleted, a query that specifies the Slice name returns HTTP 404 (resource_not_found_exception) instead of an empty result.

• Before physical cleanup is complete, a full query that uses _slice=_all may briefly return old data. A query for a specific Slice name does not access deleted old data.

  If you need to delete only one Slice, use this API. Do not delete the entire Collection. To delete a Collection, see Delete a Collection.

Delete a Collection

This API is suitable for decommissioning all business data or removing sample data. Deletion removes the Collection configuration and system-managed data. This operation cannot be undone. If you need to delete only one Slice, use Delete a Slice.

DELETE /_slice_collection/knowledge-chunks

Query parameters: master_timeout and timeout.

Sample success response:

{
  "acknowledged": true
}

• {collection} supports comma-separated names. We recommend that you explicitly specify each Collection to delete. By default, the action.destructive_requires_name safeguard rejects the wildcards * and _all and returns HTTP 400. Do not disable this cluster-level safeguard merely to conveniently remove sample data.

• If a Copy Slice is in the RUNNING or CANCELLING state, the delete request returns HTTP 409. Canceling a Copy is asynchronous. Confirm that completed=true and that the Copy has entered a terminal state before you delete the Collection.

• acknowledged=true indicates that deletion of the logical resources and metadata is acknowledged. Historical indexes and Translog files in object storage are asynchronously reclaimed by a background process. Physical space is not guaranteed to be released immediately when the response is returned.

Manage Collection Aliases

A Collection Alias provides applications with a stable access name and can be used to query multiple Collections in a unified manner or switch the write target. When you create a Collection, you can add an Alias by using the aliases field. You can also use the standard Elasticsearch _aliases API for management.

Scenarios:

• Version migration: The application always accesses a fixed Alias. After data preparation is complete, switch the write target from the old Collection to the new Collection.

• Multi-Collection queries: Use one Alias to query multiple Collections that use the same slice_strategy.

• Application decoupling: Store only the Alias in business configurations instead of directly depending on Collection names that contain versions or dates.

  Before use, check Collection Alias support to confirm that the existing Alias configuration is supported.

For version migration, first complete data migration, handle incremental writes during migration, confirm that data in the new Collection is searchable, and warm up the Slices that will be accessed. Then, in the same request, remove the old Collection from the Alias and add the new Collection to the Alias. Alias updates are atomic, but they do not automatically copy or synchronize data. The following example atomically switches read and write traffic from knowledge-chunks-v1 to 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
      }
    }
  ]
}

The following example is for multi-Collection queries, not version migration. Assume that knowledge-chunks-v1 and knowledge-chunks-v2 are both Collections in namespace mode and that the data in the two Collections does not overlap. Add them to the same Alias and set knowledge-chunks-v2 as the write target. Search queries both Collections.is_write_index determines only the write location and does not limit the query scope.

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

View the Alias:

GET /_alias/knowledge-chunks-current

Query a potentially missing Slice in a multi-member Alias:

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

Take note of the following when you use an Alias:

• When a multi-member Alias is used for writes, exactly one member must have is_write_index=true.

• APIs such as Search, Count, and Bulk can access a multi-member Alias according to Alias semantics.

• A single-document GET request and each item in an MGet request must resolve to exactly one Collection. Therefore, only a single-member Alias can be used. is_write_index does not select a member for a single-target read.

• Alias updates are applied atomically. By default, remove succeeds if it matches at least one existing member. must_exist=true strictly validates each specific target. The response contains only acknowledged and does not contain per-action results.

• When you query a multi-member Alias, the target Slice must exist in all member Collections. Otherwise, HTTP 404 is returned. To query a Slice that may be missing, explicitly include ignore_missing_slice=true. The request skips members in which the Slice is missing and returns results as normal.