Link Search Menu Expand Document Documentation Menu
文档

搜索分片 API

_search_shards API 提供有关 OpenSearch 在执行搜索请求时会将请求路由到哪些分片的信息。这有助于您了解 OpenSearch 如何在不实际运行搜索的情况下计划跨分片分发查询。此 API 不执行搜索，但允许您检查路由决策、分片分布以及将处理请求的节点。

端点

GET /_search_shards
GET /<index>/_search_shards
POST /_search_shards
POST /<index>/_search_shards

路径参数

下表列出了可用的路径参数。所有路径参数均为可选。

参数 参数 描述
<index> 字符串 逗号分隔的目标索引名称列表。

查询参数

下表列出了可用的查询参数。所有查询参数都是可选的。

参数 数据类型 描述
allow_no_indices 布尔型 如果为 true，则当通配符表达式或索引别名解析为无具体索引时，请求不会失败。默认值为 true。
expand_wildcards 字符串 控制通配符表达式的展开方式。选项包括：open（默认）、closed、hidden、none 或 all。
ignore_unavailable 布尔型 如果为 true，则忽略缺失或已关闭的索引。默认值为 false。
local 布尔型 如果为 true，则操作仅在本地节点上执行，而不从集群管理器节点检索状态。默认值为 false。
preference 字符串 指定选择目标分片或节点的偏好设置。有关更多信息，请参阅`preference` 查询参数。
路由 字符串 用于分片选择的逗号分隔的特定路由值列表。

请求正文字段

请求体可以包含一个完整的搜索查询，以模拟请求将如何路由

{
  "query": {
    "term": {
      "user": "alice"
    }
  }
}

示例

创建索引

PUT /logs-demo
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 0
  },
  "mappings": {
    "properties": {
      "user": { "type": "keyword" },
      "message": { "type": "text" },
      "@timestamp": { "type": "date" }
    }
  }
}

使用 routing=user1 索引第一个文档

POST /logs-demo/_doc?routing=user1
{
  "@timestamp": "2025-05-23T10:00:00Z",
  "user": "user1",
  "message": "User login successful"
}

使用 routing=user2 索引第二个文档

POST /logs-demo/_doc?routing=user2
{
  "@timestamp": "2025-05-23T10:01:00Z",
  "user": "user2",
  "message": "User login failed"
}

请求示例

使用 _search_shards 模拟路由

POST /logs-demo/_search_shards?routing=user1
{
  "query": {
    "term": {
      "user": "user1"
    }
  }
}

示例响应

响应显示如果执行搜索将搜索的节点和分片

{
  "nodes": {
    "12ljrWLsQyiWHLzhFZgL9Q": {
      "name": "opensearch-node3",
      "ephemeral_id": "-JPvYKPMSGubd0VmSEzlbw",
      "transport_address": "172.18.0.4:9300",
      "attributes": {
        "shard_indexing_pressure_enabled": "true"
      }
    }
  },
  "indices": {
    "logs-demo": {}
  },
  "shards": [
    [
      {
        "state": "STARTED",
        "primary": true,
        "node": "12ljrWLsQyiWHLzhFZgL9Q",
        "relocating_node": null,
        "shard": 1,
        "index": "logs-demo",
        "allocation_id": {
          "id": "HwEjTdYQQJuULdQn10FRBw"
        }
      }
    ]
  ]
}

响应正文字段

下表列出了所有响应正文字段。

字段 参数 描述
节点 对象 包含节点 ID 到节点元数据的映射，例如名称和传输地址。
索引 对象 包含请求中包含的索引名称的映射。
分片 数组的数组 表示请求的分片副本（主/副本）的嵌套数组。
shards.index 字符串 索引名称。
shards.shard 整数 分片编号。
shards.node 字符串 包含此分片的节点的节点 ID。
shards.primary 布尔型 这是否为主分片。
shards.state 字符串 当前分片状态。
shards.allocation_id.id 字符串 此分片分配的唯一 ID。
剩余 350 字符

有问题？。

想要贡献？或。