cluster clause-OpenSearch(Open Search)-阿里云帮助中心

The cluster clause routes a query to specific partitions in a cluster.

The clause is optional. Omit it to query all partitions.

When to use it

Use the cluster clause when you know which partitions hold the data you're looking for:

Your data is partitioned by a known field value — use hash_field to route by the original partition field value.
You have a hash ID from a previous query result — use part_ids to target the exact partition by its numeric hash ID.

Syntax

Route by partition field value

Pass the original values of the partition field to hash_field. OpenSearch Retrieval Engine Edition hashes each value, resolves the corresponding partition IDs, and queries only those partitions.

{
  "cluster": {
    "hash_field": []
  }
}

Examples

Query the partitions that correspond to the hash values of "123" and "456":

{
  "cluster": {
    "hash_field": ["123", "456"]
  }
}

Query the partition that corresponds to the hash value of "abc":

{
  "cluster": {
    "hash_field": ["abc"]
  }
}

Route by hash ID

Use part_ids when a previous query returns a document's hash ID and you want to query its partition directly. Each hash ID is an integer in the range 0–65535.

The hash ID range is split evenly across partitions. For a cluster with two partitions:

Partition 1: hash IDs 0–32767
Partition 2: hash IDs 32768–65535

If the hash ID you specify falls within a partition's range, that partition is queried.

{
  "cluster": {
    "part_ids": []
  }
}

Example

Query the partitions that contain hash IDs 123 and 8790:

{
  "cluster": {
    "part_ids": [123, 8790]
  }
}

Usage notes

Specify either hash_field or part_ids in a single cluster clause — not both.