Branch Slice (Beta) - Elasticsearch - Alibaba Cloud Documentation Center

Branch Slice creates a target Slice (target) that supports independent reads and writes from the committed data of a source Slice (source) within the same Collection. This feature is currently in Beta. The API and resource limits may change.

Prerequisites

The source and the target belong to the same Collection and share the Mapping and index settings. Independent writes affect only document content.
The target and the source reside on the same shard of the same Backing. The index.routing_partition_size of the Backing that contains the source must be 1, which is the default value. If the value is greater than 1, Branch creation is not supported. Consider using Copy Slice.
The target must use a new name and cannot take over an existing Slice. For information about duplicate requests and name conflicts, see Create a Branch and Common errors.
The account requires the manage permission on the Collection. For information about how to configure this permission, see Collection permissions.

Before you integrate Branch Slice, confirm that your business can accept the following limits:

Requests that fail as a whole — While the target is an Active Branch (a Branch target that has not yet been converted to a regular Slice), a multi-Slice request or a _slice=_all request that includes the target returns HTTP 409 instead of partial results. A synchronous _warm_slice request also returns HTTP 409, and Explain is not supported.
Incomplete results — A CAT request that returns multiple rows, or that sorts by s=docs.count, counts only the data written to the target itself.
Source state — If the source Slice is still an Active Branch, only wait_for_commit=false is supported. Specifying wait_for_commit=true returns HTTP 400.
Inheritance depth — A maximum of 8 inheritance levels is supported.
Quotas — Limits apply to the number of Branches being prepared on the same shard, the number of Active Branches, and the Branch metadata size. When a limit is reached, only new Branch creations are rejected. Reads and writes to existing Branches and their data continue to be served.
Retryable unavailability — While the Branch state is transitioning, or the committed data required for a read is temporarily unavailable, read and derived operations return retryable HTTP 503.

For details, see Behavioral differences during the Active phase and Common errors. To compare Branch Slice with Copy Slice, see Related information.

Create a new Branch

Send the following request to create a Branch:

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

The following query parameter is supported:

Parameter	Default value	Description
`timeout`	`30s`	The maximum time to wait for this creation or idempotency confirmation. The value must be finite.

The request body can be omitted or set to {}. Currently, the following is the only optional field:

Field	Default value	Description
`wait_for_commit`	`false`	Specifies whether to wait until the starting data and recovery information of the target are persisted before a response is returned. Set this field to `true` if the same starting point must be retained after fault recovery. If the source Slice is still an Active Branch, only `false` is supported. For scenario-based guidance, see `wait_for_commit` values in this section.

The following example creates the Branch tenant-a-preview from the source Slice tenant-a:

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

The first successful creation returns HTTP 201:

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

target_uid is the internal identity of the target and is used to confirm whether the result belongs to the same creation. Do not parse its content or use it as _slice. To access the target, continue to specify the business name tenant-a-preview, which is the target_slice in the response.

Sending the same request again for the same Active Branch relationship is idempotent and returns HTTP 200 and the same target_uid. The API does not take over an existing target. If the target name is occupied or another conflict prevents the creation, HTTP 409 is returned. For the complete list of HTTP 409 scenarios, see Common errors.

A request timeout does not roll back creation progress that has already been persisted. Do not conclude from a timeout that the creation has been rolled back. Query the target Slice to confirm whether it is available, and then handle the retry as described in Common errors.

After the creation response is returned, verify that the target is readable and that it returns the expected data. For the verification methods, see Query and document count verification.

`wait_for_commit` values

By default, wait_for_commit=false creates the Branch from the most recent committed version of the source and returns a response as soon as the target becomes readable. If primary shard fault recovery occurs before the recovery information is persisted, the target name and identity remain unchanged, but the system may redetermine the starting point of the target based on the latest committed data of the source at the time of recovery. Changes made to the source after creation may therefore affect the starting data. After the recovery information is persisted, the starting point no longer changes.

wait_for_commit=true first fixes a data version of the source and returns a response only after both that version and the Branch recovery information are persisted. This keeps the starting point of the target unchanged during subsequent fault recovery, at the cost of higher creation latency. Example:

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

Regardless of its value, wait_for_commit does not wait for business writes that are still in progress when the request is sent. The time when the client sends the request cannot be used as an exact data timestamp.

Set wait_for_commit=false when you need the target to become readable as soon as possible and your business can accept that the starting point may be redetermined during early fault recovery. Receiving a successful write response alone does not guarantee that this data is included in the Branch. To include specific data, first confirm that the writes to the source are successful and wait until the data is searchable. Then, create the Branch and verify the target results.

Set wait_for_commit=true when the same starting point must be retained after fault recovery. The creation process commits and fixes a data version before it persists the Branch recovery information, which increases the wait overhead for committing and persistence.

Read and write semantics

After the creation response is returned, the target can immediately be used for GET, MGet, and Search on a single Slice. Document requests still select the target by specifying _slice=tenant-a-preview. The parameters and permissions are the same as those of a regular Slice. The following request searches the target Slice:

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

The following read and write rules apply to a Branch target:

During normal use, the target reads the source data version that was fixed at creation time. Documents written to the source afterwards do not automatically appear in the target. For the early fault recovery exception that applies to the default wait_for_commit=false, see the Create a Branch section, which describes wait_for_commit values.
Index, Update, and Delete operations on the target affect only the target and do not modify the source.
A Branch does not change the business fields in inherited documents to the target name. If routing_field is configured, subsequent writes to the target must select the target Slice, and the routing field in the written document must match the target. Otherwise, the document may be written back to the source based on the source field value, or the write may be rejected because the explicitly specified scope does not match the field.
When you write a document with the same _id as an inherited document to the target, the new document overwrites the old document in the inherited view.
When you delete an inherited document from the target, the document becomes invisible only in the target. The document in the source is unaffected.
To delete the target, use the standard Delete Slice API. After the Branch relationship is released, a target with the same name can be registered again as a regular Slice. The new Slice cannot see the data inherited by the old Branch.

A Branch target can also serve as the source of a new Branch. In this case, only wait_for_commit=false is supported, and specifying true returns HTTP 400. A maximum of 8 inheritance levels is supported.

When you create a Branch from a Branch target, the following rules apply:

The system captures the most recent complete committed view of the target without waiting for writes in progress.
Whether a write is included in the new Branch depends on whether that write is already included in the committed version that is actually captured.
The time when the client sends the request cannot be used as the cutoff for business writes.

Behavioral differences during the Active phase

Before the target is converted to a regular Slice, it is called an Active Branch. The following differences apply during this phase. Some of them cause the entire request to fail instead of returning partial results. Before you integrate this feature, make sure that your business can accept them:

Operation	Active Branch behavior
Search, GET, and MGet on a single Slice	Fully supported.
Copy Slice or single-Slice Reindex with the target as the source	Supported. Data is read as currently visible in the target, including inherited documents and the modifications of the target itself.
Multi-Slice queries or `_slice=_all`	If the scope includes an Active Branch, the entire request returns HTTP 409. Even if `allow_partial_search_results=true` is specified, partial results that exclude this Slice are not returned.
`_warm_slice`	Synchronous warming returns HTTP 409. An asynchronous request may first return HTTP 200 and `status=ACCEPTED` before the task fails. This response does not indicate that warming succeeded.
Explain	Not currently supported.
CAT document count	An exact query for a single Slice includes inherited documents. A CAT request that returns multiple rows, or that sorts by `s=docs.count`, counts only the data written to the target itself. Such a request cannot represent the complete document count or the global ranking.

If your business has statistics or retrieval requests that cover all Slices, evaluate before you create a Branch whether these requests may fail because they include an Active Branch. If you must run a multi-Slice query immediately, query this target separately or retry after it is converted to a regular Slice.

Automatic conversion to a regular Slice

A Branch target is automatically converted to a regular Slice in the background. The conversion scans the complete visible history once and writes the inherited data as the data of the target itself. The entire process does not freeze business reads or writes. After the conversion is complete, all the behavioral differences described for the Active phase disappear.

The conversion is scheduled in the background. Trigger conditions include a certain amount of time passing after creation, the number of overwritten or deleted inherited documents reaching a certain threshold, and the Branch metadata reaching a certain size. These are scheduling conditions, not completion deadlines, update count limits, or write rejection limits. The specific thresholds are internal values that may change in Beta. Meeting a condition does not mean that the conversion completes immediately, and not meeting a condition does not affect normal reads or writes on the target.

A backlog of background tasks or an insufficient memory budget for a single run does not cause GET, Search, Index, Update, or Delete operations on an existing target to fail. The system cancels and retries the background task. Conversion results that already succeeded and subsequent business writes remain valid.

To check whether the target has been converted to a regular Slice, observe whether the Active Branch limitations disappear in actual business requests. Do not probe the conversion progress with frequent _slice=_all queries or by repeatedly submitting warming tasks. Single-Slice reads and writes do not need to wait for the conversion.

Query and document count verification

After you create a Branch, verify that the target is readable and that it returns the expected data. To query the source and the target separately in one request, use Multi Search and select only one Slice in each subrequest:

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

The request body uses NDJSON and must end with a newline. Each subrequest returns a result or an error separately, and the application must check each item. This method does not automatically generate unified sorting or aggregation results across Slices.

To verify the complete number of searchable documents in the target, query the target Slice directly. include_doc_count=true performs an additional data query and is suitable for infrequent verification. Omit this parameter if you only need to check whether the Slice exists:

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

When the Branch state is transitioning, or the committed data required for the read is temporarily unavailable, the current node may be temporarily unable to provide complete Branch data. Read or derived operations return retryable HTTP 503. For the retry contract, see Common errors.

Common errors

HTTP	Scenario	Recommendation
`400`	The request body is invalid, the source and the target have the same name, or the source is itself a Branch target with `wait_for_commit=true`	Correct the parameters and retry.
`404`	The Collection or the source Slice does not exist	Check the source status first.
`409`	The target name is occupied by another Slice or lifecycle, the target is being deleted, the parameters of an idempotent retry differ from those of the initial creation, the inheritance level or Branch metadata size limit is reached, or the source is completing conversion	Handle the error based on its cause: use a new name only if the name is occupied by another Slice; keep the original parameters when you confirm an existing creation result; if a limit is reached or conversion is in progress, wait and retry. Do not continuously create Branches with different names just because the result is temporarily uncertain.
`429`	Too many Branches are being prepared on the same shard, the Active Branch count limit is reached, or this synchronous wait timed out	Wait for the operations to converge and retry. Existing data reads and writes are unaffected. A timeout does not mean that the creation has been rolled back. Retry idempotently with the same parameters.
`503`	The Branch state is transitioning, or the required committed data is temporarily unavailable	The client must use backoff retry with a capped number of attempts. If failures persist, contact technical support.

For the specific count and size limits, see Limits of Branch Slice (Beta).