管理 Collection 与 Slice

创建 Collection

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 表示 Collection 的配置已创建。请求超时或连接失败时，先调用 GET /_slice_collection/knowledge-chunks 确认实际状态，不要靠重试的返回结果判断是否创建成功。

Collection 名需遵循 Elasticsearch 索引和 Alias 命名规则，必须使用小写，长度不超过 128 字节，且不能使用系统保留的 .sc- 前缀。

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

查看 Collection

GET /_slice_collection/knowledge-chunks

列出全部 Collection：

GET /_slice_collection

{collection} 支持逗号分隔的名称和通配符。精确名称不存在时返回 HTTP 404；通配符没有匹配项时返回 {"slice_collections": {}}。

查询参数：

该接口只需要目标 Collection 上的索引权限 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 来自最新仍存在的 Backing Index。其中 settings 是该 Backing 当前可继承、可公开的设置，可能包含系统自动补齐或后续更新的字段；mappings 是该 Backing 的当前 Mapping，因此也包含动态新增的字段。

• future_only_settings 只影响后续创建的 Backing，不代表当前最新 Backing 已经使用这些值。

• collection_uuid 和 max_managed_backing_generation 是系统管理字段。应用应将其视为不透明信息，不要据此拼接 Backing 名或实现业务逻辑。

更新 Collection

该接口用于调整后续注册 Slice 的分配策略，不会移动已有 Slice。

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 中允许的后续生效设置。

后续生效设置只影响以后创建的 Backing，不修改现有 Backing。默认允许配置：

• 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 表示等待确认超时，不表示更新已经回滚。

更新 Mapping 和动态 Settings

使用 Collection 名更新 Mapping：

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

使用 Collection 名更新动态索引设置。以下演示将刷新间隔恢复为默认的 5s；创建时无需重复配置该默认值。修改会影响整个 Collection，使用条件见 Refresh 与查询可见性：

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

Mapping 和动态索引设置会应用到当前所有 Backing，并成为后续 Backing 的统一配置。同一 Collection 中的所有 Slice 共用这些配置，不能为某个 Slice 单独修改字段类型或索引设置。不要逐个修改 Backing Index。

注册 Slice

选择注册方式时可参考下表。

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

查询单个 Slice

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 是 Slice 创建时间，使用 UTC ISO-8601 格式。

仅判断 Slice 是否存在或读取其信息时，使用上述默认请求即可。include_doc_count=true 会额外执行数据查询来统计文档数，不应用于高频轮询或批量检查大量 Slice。确需核对可搜索文档数时再调用：

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

响应额外包含：

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

使用说明：

• docs.count 表示当前可搜索的文档数，刚写入但尚未 Refresh 的文档可能暂未计入；

• 该接口只查询当前有效的 Slice。Collection 或 Slice 不存在、Slice 已删除时返回 HTTP 404；

• 查询不会创建 Slice；应先显式注册，或在启用自动注册时先写入该 Slice；

• 该接口不提供单 Slice 存储大小。需要存储统计时，使用 Backing CAT 或原生 Index Stats，见 CAT 观测；

• 分片和副本是 Backing 级配置。使用 Slice CAT 查看 Slice 实际访问的主分片，使用 Backing CAT 查看副本配置。

分页列出 Slice

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

响应示例：

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

没有下一页时省略 next_cursor。结果按 Slice 名升序返回。翻页期间如果并发新增或删除 Slice，分页结果为弱一致；继续翻页时应保持相同的 prefix。

删除 Slice

删除会使该 Slice 及其中全部文档无法再通过原名称访问，不能通过重新注册同名 Slice 找回旧数据。确认目标业务空间后再执行：

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

查询参数：

成功响应：

{
  "acknowledged": true
}

该响应表示原 Slice 名已经不可访问，不表示旧物理数据已经清理完成，也不表示存储空间已经释放。同名 Slice 可以随后重新注册，新数据与后台待清理的旧数据保持隔离。删除、同名重建以及可能自动注册的写入需要由应用协调；删除结果不确定时，先核对 Slice 生命周期状态。同名 Slice 已经重建后，不要盲目按原名称重发 DELETE，否则可能删除新 Slice。此外：

• Slice 删除后，指定该 Slice 名的查询返回 HTTP 404（resource_not_found_exception），而不是返回空结果；

• 物理清理完成前，使用 _slice=_all 的全量查询可能短暂看到旧数据；查询具体 Slice 名不会访问已经删除的旧数据。

如果只需要清理某个 Slice，请使用本接口，不要删除整个 Collection。删除 Collection 见 删除 Collection。

删除 Collection

该接口适用于业务数据整体下线或清理示例数据。删除会移除 Collection 的配置和系统管理的数据，操作不可撤销；如果只需要清理某个 Slice，请使用 删除 Slice。

DELETE /_slice_collection/knowledge-chunks

查询参数：master_timeout、timeout。

成功响应：

{
  "acknowledged": true
}

• {collection} 支持逗号分隔的名称，建议逐一明确要删除的 Collection。默认 action.destructive_requires_name 保护会拒绝通配符 * 和 _all，返回 HTTP 400；不应为方便清理示例而关闭这一集群级保护。

• 存在 RUNNING 或 CANCELLING 状态的 Copy Slice 时，删除返回 HTTP 409。取消 Copy 是异步操作，应确认 completed=true、Copy 已进入结束状态后再执行删除。

• acknowledged=true 表示逻辑资源和元数据删除已确认；对象存储中的历史索引和 Translog 文件由后台流程异步回收，物理空间不保证在响应返回时立即释放。

预创建 Backing

默认情况下系统按需创建 Backing Index：注册新 Slice 时，如果现有 Backing 都已达到容量阈值，系统会自动创建下一个 Backing。批量开通大量租户或批量导入数据前，可以提前准备这些底层索引，减少首批 Slice 注册时等待创建索引的延迟。

预创建 Backing 和注册 Slice 是两个操作：前者准备存储数据的索引，后者创建应用要访问的业务分区。预创建不会自动注册租户 Slice，也不会搬移已有数据。 该接口可由具备 Collection manage 权限的账号调用，完整权限配置见Collection 权限。

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

Collection Alias

Collection Alias 为应用提供稳定的访问名称，可用于统一查询多个 Collection 或切换写入目标。创建 Collection 时可以通过 aliases 字段添加 Alias，也可以使用标准 Elasticsearch _aliases API 管理。

适用场景：

• 版本迁移：应用始终访问固定 Alias，完成数据准备后把写入目标从旧 Collection 切换到新 Collection；

• 多 Collection 查询：通过一个 Alias 查询多个使用相同 slice_strategy 的 Collection；

• 应用解耦：业务配置只保存 Alias，不直接依赖带版本或日期的 Collection 名。

使用前请核对 Collection Alias 支持范围，确认现有 Alias 配置可用。

如果目的是版本迁移，应先完成数据迁移、处理迁移期间的增量写入，确认新 Collection 的数据已可搜索并预热即将访问的 Slice，再在同一个请求中移除旧 Collection、添加新 Collection。Alias 更新是原子的，但不会自动复制或同步数据。以下示例将读写流量从 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
      }
    }
  ]
}

以下示例用于多 Collection 查询，不用于版本迁移。假设 knowledge-chunks-v1 和 knowledge-chunks-v2 均为命名空间模式 Collection，且两个 Collection 的数据互不重叠。将它们加入同一个 Alias，并把 knowledge-chunks-v2 设置为写入目标。Search 会同时查询两个 Collection；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
      }
    }
  ]
}

查看 Alias：

GET /_alias/knowledge-chunks-current

在多成员 Alias 中查询可能缺失的 Slice：

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

使用 Alias 时请注意：

• 多成员 Alias 用于写入时，必须有且只有一个成员设置 is_write_index=true。

• Search、Count 和 Bulk 等接口可以按 Alias 语义访问多成员 Alias。

• 单文档 GET 和 MGet 中的每个 item 都必须唯一解析到一个 Collection，因此只能使用单成员 Alias；is_write_index 不会替单目标读取选择成员。

• Alias 更新原子应用。remove 默认至少匹配一个已有成员即可成功；must_exist=true 对每个具体目标严格校验。响应只返回 acknowledged，不包含逐 action 的结果。

• 查询多成员 Alias 时，目标 Slice 必须在全部成员 Collection 中都存在，否则返回 HTTP 404。需要查询可能缺失的 Slice 时，显式携带 ignore_missing_slice=true，请求会跳过缺失成员并正常返回。