Elasticsearch:Warm Up the Slice Cache

Warming is an optional performance optimization. If you do not warm data, queries load the data on demand. Warming does not change query results and does not guarantee how long data stays resident in the cache. After a batch of data is warmed, query it directly instead of warming it again before every query.

Before you begin

• The target Collection and Slice exist. _warm_slice does not create a Slice that does not exist.

• The data that you want to warm is already searchable. Warming does not trigger a refresh. Wait for the automatic background refresh to make the data searchable before you warm it, and do not call _refresh manually for warming.

Usage notes

The following limits and behaviors apply to all warming requests:

• Request scope — Each request can explicitly specify only one Collection and one Slice. _all cannot be used in a warming request, although query requests support _slice=_all.

• Duplicate requests — Concurrent warming requests for the same query shard replica and Slice are merged. You do not need to submit duplicate requests.

• Data scope — Warming processes only the data that is already searchable when the request is initiated. New data that becomes searchable later is not included in this warming result.

• Resource impact — Warming consumes object storage read bandwidth and query node resources. In a production environment, use the default asynchronous method, warm the Slices before your application queries them, and limit the number of Slices that are warmed at the same time.

• Queue full — When the warming queue is full, the server may reject new requests. Your client must use a bounded backoff retry strategy instead of immediately retrying all Slices concurrently.

Choose a warming mode

_warm_slice submits a warming task asynchronously by default. You can also wait synchronously for the warming result.

Request parameters

_warm_slice accepts the following query parameters:

Initiate asynchronous warming

By default, a warming task is submitted asynchronously:

POST /knowledge-chunks/_warm_slice?_slice=tenant-a

The request returns HTTP 200. The response body contains status set to ACCEPTED and the ID of this warming task:

{
  "status": "ACCEPTED",
  "message": "cache warm hint accepted",
  "task": "<nodeId>:<taskId>"
}

Use the following operation to query a running task:

GET /_tasks/<nodeId>:<taskId>

By default, the task result is not retained after the task is complete.

ACCEPTED indicates only that the task has been submitted. It does not indicate that the target Slice exists or that warming succeeded. To confirm the result, set store_result=true when you submit the task, and then use the Tasks API to check the following items in sequence:

1. completed=true: The task has ended. If the value is false, wait for a while and then query the task again.

2. The top level does not contain error: The task did not end with an error. Conditions such as a nonexistent Slice or an Active Branch that does not currently support warming may be reported as errors only after the task is submitted. A synchronous request returns HTTP 404 for a nonexistent Slice instead.

3. response._shards.failed=0: No shard failed. If response._shards.total=0, perform further checks as described in Evaluate synchronous results below.

Warm only the Slices that your application actually queries. Do not enumerate all Slices just for warming.

Wait for warming to complete

To get the warming statistics directly, you can wait synchronously:

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&wait_for_completion=true&timeout=60s

In synchronous mode, HTTP 404 is returned for a nonexistent Slice. After the request succeeds, check that the top-level _shards.failed=0. If _shards.total=0, you cannot use this result to determine that the query nodes are ready. If you expect searchable data to exist, first confirm that the query shards are available, verify data visibility with an actual query, and then retry warming as needed. Do not conclude from this result alone that warming failed for a Slice that has no data.

The synchronous response contains the following statistics fields:

ranges_skipped greater than 0 does not necessarily indicate that warming failed. When files are merged or deleted during warming, the corresponding ranges are skipped.

Query and warming affinity

The local cache of each query node is independent. If different searchable replicas of the same shard reside on different nodes, they cannot directly share cached data. Therefore, query and warming affinity is enabled by default. When shard routing remains stable, warming and subsequent queries preferentially access the same searchable replica. This reuses the local cache of the query node where that replica resides, which reduces repeated data reads from object storage and prevents multiple replicas from caching the same data.

For example, warm a knowledge base that is queried infrequently before your users query it, and then run the query after warming is complete. In a production environment, warm the data asynchronously in advance so that user queries do not have to wait for warming. The following synchronous example shows the call sequence:

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&wait_for_completion=true&timeout=60s

After you check the warming result, run the query:

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

Affinity affects only which replica is preferentially accessed and does not change query results. Affinity applies to:

• GET, MGet, and Explain

• Collection subrequests in Search, Count, Search Template, Search Shards, Async Search, and Multi Search

• Queries for a single Slice, multiple Slices, and _slice=_all

• Update By Query and Delete By Query

• _warm_slice

Affinity does not apply to source-side reads for Reindex or to Validate Query. Copy Slice uses Reindex to read source data, so Copy Slice also cannot guarantee that the cache of the replica that was just warmed is reused.

When affinity is enabled (the default), you do not need to set preference. Any preference value passed in a request is overridden by the affinity rules. If your business needs to use preference to control node selection, the cluster administrator must disable affinity. For example, _local preferentially accesses local nodes, and _only_nodes accesses only specified nodes.

This setting takes effect for all Collections and cannot be changed for a single Collection. After affinity is disabled, warming requests that do not carry preference cover all searchable replicas of the target shard, which may increase object storage reads and local cache usage. Confirm this impact before you change the setting. To disable affinity, submit the following request:

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.query_warm_affinity.enabled": false
  }
}

This setting takes effect dynamically, and you do not need to rebuild the Collection. After affinity is disabled, the preference value in requests takes effect again. If a query does not pass this parameter, the original replica selection method is used.

Whether or not affinity is enabled, the replica that is actually accessed may change when a replica is migrated or becomes unavailable, or when a request is retried. Affinity does not guarantee that a request remains permanently bound to a node.