Branch Slice（Beta）-检索分析服务 Elasticsearch版(ES)-阿里云帮助中心

本接口在同一个 Collection 内，从源 Slice（source）的已提交数据创建可独立读写的目标 Slice（target）。该能力目前为 Beta，接口和资源边界可能调整。

调用前提

source 和 target 属于同一个 Collection，共用 Mapping 和索引设置；独立写入只影响文档内容。
target 与 source 位于同一个 Backing 的同一分片。source 所在 Backing 的 index.routing_partition_size 必须为 1（默认值）；大于 1 时不支持创建 Branch，可考虑使用 Copy Slice。
target 必须使用新名称，不能接管已有 Slice。重复请求与名称冲突的处理见下文。
账号需要 Collection 上的 manage 权限，配置方式见Collection 权限。

创建 Branch

PUT /_slice_collection/{collection}/slices/{source}/_branch/{target}

查询参数：

参数	默认值	说明
`timeout`	`30s`	等待本次创建或幂等确认的最长时间，必须为有限值。

请求体可以省略或使用 {}。当前唯一可选字段：

字段	默认值	说明
`wait_for_commit`	`false`	是否等到目标的起点数据和恢复信息持久化后再返回。需要在故障恢复后保持相同起点时设为 `true`；源 Slice 仍是活动 Branch 时只支持 `false`。

PUT /_slice_collection/knowledge-chunks/slices/tenant-a/_branch/tenant-a-preview
{}

首次创建成功返回 HTTP 201：

{
  "target_slice": "tenant-a-preview",
  "target_uid": "opaque-target-uid",
  "wait_for_commit": false
}

target_uid 是目标的内部身份标识，用于确认是否为同一次创建结果；不要解析其内容或将其用作 _slice。访问目标时仍传业务名称 tenant-a-preview（响应中的 target_slice）。

对同一个活动分支关系重复发起相同请求是幂等操作，返回 HTTP 200 和同一个 target_uid。如果 target 名称已经属于其他 Slice、其他分支关系或正在删除，返回 HTTP 409，接口不会接管已有 target。

请求超时不会回滚已经落地的创建进度。超时后应使用相同参数幂等重试，或先查询 target 是否可用，不能据此判定创建已回滚。

`wait_for_commit` 的取值

默认 wait_for_commit=false 在 target 可读后即返回。如果恢复信息还未持久化就发生主分片故障恢复，target 名称和身份不变，但系统可能用恢复时 source 的最新已提交数据重新确定 target 的起点。因此，起点数据可能受到创建后 source 变化的影响；恢复信息持久化后，起点不再变化。

wait_for_commit=true 会先固定 source 的一个数据版本，等该版本和分支恢复信息都持久化后再返回，使 target 的起点在后续故障恢复时也保持不变，代价是创建延迟更高。例如：

PUT /_slice_collection/knowledge-chunks/slices/tenant-a/_branch/tenant-a-durable-preview
{
  "wait_for_commit": true
}

wait_for_commit 的两种取值都不会等待请求发起时仍在途的业务写入，也不能把客户端发起请求的时刻作为精确的数据时间点。

使用 wait_for_commit=false 时，分支从最近的已提交版本创建。仅收到写入成功响应，还不能保证这批数据会进入分支。 需要包含指定数据时，先确认源端写入成功并等待这批数据可搜索，再创建分支、核对目标结果。

使用 wait_for_commit=true 时，创建流程会提交并固定数据版本，再持久化分支恢复信息；这样可以固定分支的起点，但会增加提交和持久化等待开销。

读写语义

创建响应返回后，target 可以立即用于 GET、MGet 和单个 Slice 的 Search。文档请求仍通过 _slice=tenant-a-preview 选择 target，参数和权限与普通 Slice 相同。

GET /knowledge-chunks/_search?_slice=tenant-a-preview

读写规则：

正常使用期间，target 读取的是创建时固定的 source 数据版本。之后写入 source 的文档不会自动出现在 target 中；默认 wait_for_commit=false 的早期故障恢复例外见创建 Branch；
对 target 的 Index、Update 和 Delete 只影响 target 自己，不会修改 source；
分支不会把继承文档中的业务字段改为目标名称。配置了 routing_field 时，后续写入 target 必须选择目标 Slice，并使写入文档中的路由字段与目标一致；否则可能按源字段值写回 source，或因显式范围与字段不一致而被拒绝；
在 target 中写入与继承文档相同 _id 的文档时，新文档覆盖继承视图中的旧文档；
在 target 中删除继承文档时，该文档只在 target 中不可见，source 中的文档不受影响；
删除 target 使用标准的删除 Slice 接口。分支关系释放后，同名 target 可以作为普通 Slice 重新注册，新的 Slice 不会看到旧分支继承的数据。

target 也可以继续作为新 Branch 的 source，此时只支持 wait_for_commit=false，传入 true 会返回 HTTP 400。基于 target 再次创建 Branch 时，系统捕获 target 最近一次完整提交视图，不等待在途写入。写入是否进入新分支，取决于该写入是否已经包含在实际捕获的提交版本中，不能把客户端请求发起时刻作为业务写入截止点。继承层数最多 8 层。

Active 期间的行为差异

target 在转为普通 Slice 之前称为 Active Branch。这一阶段存在以下差异，接入前必须确认业务能够接受：

操作	Active Branch 的行为
单个 Slice 的 Search、GET、MGet	正常支持。
以 target 为源执行 Copy Slice 或单 Slice Reindex	支持，按 target 当前可见的数据读取，包含继承文档以及 target 自己的修改。
多 Slice 查询或 `_slice=_all`	范围中包含 Active Branch 时整个请求返回 HTTP 409。即使设置 `allow_partial_search_results=true` 也不会返回缺少该 Slice 的部分结果。
`_warm_slice`	同步预热返回 HTTP 409；异步请求可能先返回 HTTP 200 和 `status=ACCEPTED`，随后任务失败，该响应不代表预热成功。
Explain	当前不支持。
CAT 文档数统计	精确查询单个 Slice 时包含继承文档；多行列表和 `s=docs.count` 排序只统计目标自身写入的数据，不能代表完整文档数或全局排名。

如果业务存在覆盖全部 Slice 的统计或检索请求，应在创建 Branch 前评估这些请求会不会因为包含 Active Branch 而失败。需要立即执行多 Slice 查询时，应单独查询该 target，或等待其转为普通 Slice 后重试。

自动转为普通 Slice

Branch target 会在后台自动转换为普通 Slice。转换会扫描一次完整可见历史，把继承数据写成 target 自己的数据，整个过程不冻结业务读写。转换完成后，上述 Active 期间的行为差异全部消失。

转换由后台调度，触发条件包括创建后经过一定时间、被覆盖或删除的继承文档达到一定数量、分支元数据达到一定体积。这些都是调度条件，不是完成时限，也不是更新次数或拒写上限：达到条件不代表转换立即完成，未达到条件也不影响 target 的正常读写。

后台任务积压或单次内存预算不足不会导致已有 target 的 GET、Search、Index、Update 或 Delete 失败，系统会取消并重试后台任务，已成功的转换结果和后续业务写入都继续有效。

需要确认 target 是否已经转为普通 Slice 时，可以结合实际业务请求观察上述限制行为是否消失。不要通过高频 _slice=_all 查询或反复提交预热任务来探测转换进度；单 Slice 读写无需等待转换。

查询与文档数核对（可选）

如果需要在一次请求中分别查询 source 和 target，可以使用 Multi Search，每个子请求只选择一个 Slice：

POST /knowledge-chunks/_msearch
{ "_slice": "tenant-a" }
{ "query": { "match_all": {} } }
{ "_slice": "tenant-a-preview" }
{ "query": { "match_all": {} } }

请求体使用 NDJSON，末尾保留换行。每个子请求分别返回结果或错误，应用应逐项检查；该方式不会自动生成跨 Slice 的统一排序或聚合结果。

需要核对 target 的完整可搜索文档数时，可以使用查询单个 Slice 接口。include_doc_count=true 会额外查询数据，适合低频核对；仅检查 Slice 是否存在时应省略该参数：

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

分支状态正在切换，或读取所需的已提交数据暂不可用时，当前节点可能暂时无法提供完整的分支数据，读取或派生操作会返回可重试的 HTTP 503。客户端应采用有上限的退避重试；持续失败时再联系技术支持排查。

常见错误

HTTP	场景	处理建议
`400`	请求体非法、source 与 target 同名，或 source 本身是 Branch target 却使用了 `wait_for_commit=true`	修正参数后重试。
`404`	Collection 或 source Slice 不存在	先确认 source 状态。
`409`	target 名称被其他 Slice 或生命周期占用、幂等重试时参数与首次创建不一致、达到继承层数或分支元数据体积上限，或 source 正在完成转换	先按错误原因处理：名称被其他 Slice 占用才换新名称；确认既有创建结果时保持原参数；达到上限或正在转换时等待后重试。不要因为结果暂不确定就连续创建不同名称的分支。
`429`	同一分片上正在准备的分支过多、已达到活动分支数量上限，或本次同步等待超时	等待收敛后重试。已有数据读写不受影响；超时不代表创建已回滚，应使用相同参数幂等重试。
`503`	分支状态正在切换，或所需的已提交数据暂不可用	采用有上限的退避重试；持续失败时联系技术支持。

具体的数量和体积上限见 Branch Slice（Beta）使用限制。达到上限时只拒绝新的 Branch 创建，已有 Branch 及其数据的读写继续服务。