文档读写与查询

写入和读取

单文档 API：

使用时请遵循以下规则：

• 单文档请求只能指定一个 Slice，不能使用逗号分隔或 _all。

• index、create 和 update 在 auto_create_slice=true 时可以自动注册不存在的 Slice；读取和删除不会自动注册，指定不存在的 Slice 时返回 HTTP 404。

• 文档以 Collection、业务 Slice 名和 _id 共同定位。不同 Slice 可以使用相同 _id；应用读取、更新和删除时必须带上对应 Slice，不能只按 _id 区分租户。

• 每次 Bulk 最多自动注册 512 个缺失 Slice，已存在的 Slice 不计入该限制。

• wait_for_active_shards 在 Agent 引擎版写入链路中不作为等待副本的条件。查询可见性通常由后台刷新保障；确需在写入返回前等待可搜索时，按下文的适用条件使用 refresh=wait_for。

• 默认不返回向量值。常规读取和检索只返回业务需要的字段；确需核对或导出向量时，见按需读取向量值。

响应中的 _index 和 _routing 可能分别是底层索引名和系统生成的 Slice 内部标识（slice_uid），不等于请求中使用的 Collection 名和业务 Slice 名。后续请求继续使用业务名称，不要直接回填这些内部值，见请求目标与响应标识。

Refresh 与查询可见性

常规写入不应传 refresh，应等待后台自动刷新。 写入成功表示数据已经持久化；按 ID 读取文档和按条件搜索数据的可见性不同，应先根据需要选择读取方式。

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

Refresh 只解决查询可见性，不代表全部查询副本已经可用，也不能替代查询探针和高可用检查。

Bulk

每个 Bulk item 可以在 action metadata 中提供自己的 _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": "管理员可以在安全设置页面启用多因素认证。" }

item 中的 _slice 可以覆盖 URL 默认值。命名空间模式不会从文档字段推导 Slice，即使文档体中包含 tenant_id 等字段，实际写入位置仍由 _slice 决定。错误处理方式见 API 通用约定。

Multi Get

MGet 适合一次读取多个已知 ID，每个 item 可以访问不同的 Slice：

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

上述两项读取不同租户的同 ID 文档；使用快速入门的数据时，标题分别为“退款与退货政策”和“查询物流状态”。逐项检查 found、业务字段和错误。URL 上的 _slice 可以作为默认值，每个 item 可以覆盖该默认值。每个 item 最终只能解析到一个 Slice。

Reindex

调用前请核对Collection Reindex 的 API 支持范围，特别是脚本、目标 pipeline 和远程源端的限制。

Reindex 适合在普通索引与 Collection 之间，或不同 Collection 之间迁移数据。在同一个 Collection 内复制一个 Slice 时，使用 Copy Slice。

当源端是 Collection 时，必须在请求体中显式指定 source._slice，否则返回 HTTP 400。当目标端是 Collection 时，只能指定一个目标 Slice，并且目标值必须采用 ={slice} 格式。

执行前先创建目标 Collection、配置可接收源文档的 Mapping，并按 预创建 Backing 准备容量、注册目标 Slice。确认要迁移的源数据已可搜索；Reindex 不持续同步后续写入，正式切流前还需处理增量数据。

Reindex 默认保留文档 _id，并可能覆盖目标中同 ID 的文档。把多个源 Slice 合并到一个目标 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，通过 GET /_tasks/<task_id> 间隔查询，直到 completed=true，并检查 error 以及结果中的 failures、version_conflicts。任务完成不等于目标数据已全部可搜索；切流前等待后台刷新、验证目标结果，并预热即将访问的 Slice。

规则：

• source._slice 支持一个、多个或 _all；Reindex 请求体不接受 source.routing，传入会返回 HTTP 400；

• 目标端可以使用 "_slice": "=slice-name" 或 "routing": "=slice-name"，不能同时提供，前导 = 必须保留；

• 目标 Slice 不存在时，仅在 auto_create_slice=true 时自动注册；

• 顶层 slices 参数表示 Elasticsearch Reindex 的并行度，与业务 Slice 数量无关；

• 从 Collection 写入普通索引时，如不需要保留 routing，可设置 "dest": { "routing": "discard" }。

指定查询范围

本节集中说明 Agent 引擎版新增的 Slice 查询范围；接口的通用参数沿用 Elasticsearch API 语义，已知限制见使用限制。

单次查询最多指定 1024 个 Slice。除数量上限外，还需要注意 HTTP 请求行长度限制：使用较长的 Slice 名时，可能在达到数量上限之前先返回 too_long_http_line_exception。此时可以缩短 Slice 名或拆分为多次查询。

Collection 查询默认启用查询与预热亲和性。开启时，请求中的 preference 会被亲和性规则覆盖，响应不会额外提示；如果需要用 preference 控制节点选择，管理员必须关闭该设置，而且关闭后对所有 Collection 生效。

线上查询默认不要使用 _slice=_all。 它会搜索整个 Collection，查询节点的分片请求、聚合与对象存储读取开销随 Backing 和分片数量增长。应用应指定已知的一个或少量 Slice；仅在专门的分析、审计或运维任务确实需要全部数据，并已评估整个 Collection 的负载、限制并发和设置超时后，才使用 GET /knowledge-chunks/_search?_slice=_all。

如果使用了 Beta 阶段的 Branch Slice（Beta），多 Slice 查询和 _slice=_all 在范围包含尚未转为普通 Slice 的 Branch 时会返回 HTTP 409。未使用该能力时不受影响。

查询列表中可能包含不存在的 Slice 时，可以使用 ignore_missing_slice：

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

对可能不存在的可选 Slice，可设置 ignore_missing_slice=true，避免因单个缺失 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 用于解释某一文档为什么匹配查询，只能指定一个 Slice，不能使用逗号列表或 _all：

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

对以 Collection 为目标的 Update by query、Delete by query 和 Reindex，必须显式指定目标 Slice，未指定时请求会被拒绝并返回 HTTP 400。

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