New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« cat 段 API cat 快照 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›紧凑和对齐文本 (CAT) API

cat 分片 API

编辑

cat 分片 API

编辑

cat API 仅供人类通过命令行或 Kibana 控制台使用。它们不打算供应用程序使用。

shards 命令是关于哪些节点包含哪些分片的详细视图。它会告诉您它是主分片还是副本分片、文档数量、它在磁盘上占用的字节数以及它所在的节点。

对于数据流，API 返回有关流的后备索引的信息。

请求

编辑

GET /_cat/shards/<target>

GET /_cat/shards

先决条件

编辑
  • 如果启用了 Elasticsearch 安全功能，您必须具有 monitor 或 manage 集群权限才能使用此 API。您还必须具有 monitor 或 manage 索引权限才能查看检索的任何数据流、索引或别名的完整信息。

路径参数

编辑
<target>
（可选，字符串）用于限制请求的数据流、索引和别名的逗号分隔列表。支持通配符 (*)。要定位所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

编辑
bytes
（可选，字节大小单位）用于显示字节值的单位。
format
（可选，字符串）HTTP accept 标头的简短版本。有效值包括 JSON、YAML 等。
h

（可选，字符串）要显示的列名称的逗号分隔列表。

如果您未指定要包含哪些列，则 API 将按以下顺序返回默认列。如果您明确指定一个或多个列，则它仅返回指定的列。

有效列为

index, i, idx
（默认）索引的名称。
shard, s, sh
（默认）分片的名称。
prirep, p, pr, primaryOrReplica
（默认）分片类型。返回的值为 primary 或 replica。
state, st

（默认）分片的状态。返回的值为

  • INITIALIZING：分片正在从对等分片或网关恢复。
  • RELOCATING：分片正在重新定位。
  • STARTED：分片已启动。
  • UNASSIGNED：分片未分配给任何节点。
docs, d, dc
（默认）分片中的文档数，例如 25。
store, sto
（默认）分片使用的磁盘空间，例如 5kb。
dataset.size
（默认）分片数据集使用的磁盘空间，它可能不是磁盘上的大小，但包括分片在对象存储上使用的空间。报告为大小值，例如 5kb。
ip
（默认）节点的 IP 地址，例如 127.0.1.1。
id
（默认）节点的 ID，例如 k0zy。
node, n
（默认）节点名称，例如 I8hydUG。
completion.size, cs, completionSize
完成的大小，例如 0b。
dense_vector.value_count, dvc, denseVectorCount
索引的稠密向量的数量。
fielddata.memory_size, fm, fielddataMemory
使用的 fielddata 缓存内存，例如 0b。
fielddata.evictions, fe, fielddataEvictions
Fielddata 缓存逐出次数，例如 0。
flush.total, ft, flushTotal
刷新次数，例如 1。
flush.total_time, ftt, flushTotalTime
花费在刷新上的时间，例如 1。
get.current, gc, getCurrent
当前 get 操作的数量，例如 0。
get.time, gti, getTime
花费在 get 上的时间，例如 14ms。
get.total, gto, getTotal
get 操作的数量，例如 2。
get.exists_time, geti, getExistsTime
花费在成功 get 上的时间，例如 14ms。
get.exists_total, geto, getExistsTotal
成功 get 操作的数量，例如 2。
get.missing_time, gmti, getMissingTime
花费在失败 get 上的时间，例如 0s。
get.missing_total, gmto, getMissingTotal
失败 get 操作的数量，例如 1。
indexing.delete_current, idc, indexingDeleteCurrent
当前删除操作的数量，例如 0。
indexing.delete_time, idti, indexingDeleteTime
花费在删除上的时间，例如 2ms。
indexing.delete_total, idto, indexingDeleteTotal
删除操作的数量，例如 2。
indexing.index_current, iic, indexingIndexCurrent
当前索引操作的数量，例如 0。
indexing.index_time, iiti, indexingIndexTime
花费在索引上的时间，例如 134ms。
indexing.index_total, iito, indexingIndexTotal
索引操作的数量，例如 1。
indexing.index_failed, iif, indexingIndexFailed
失败的索引操作数量，例如 0。
merges.current, mc, mergesCurrent
当前合并操作的数量，例如 0。
merges.current_docs, mcd, mergesCurrentDocs
当前合并的文档数量，例如 0。
merges.current_size, mcs, mergesCurrentSize
当前合并的大小，例如 0b。
merges.total, mt, mergesTotal
完成的合并操作的数量，例如 0。
merges.total_docs, mtd, mergesTotalDocs
合并的文档数量，例如 0。
merges.total_size, mts, mergesTotalSize
当前合并的大小，例如 0b。
merges.total_time, mtt, mergesTotalTime
花费在合并文档上的时间，例如 0s。
query_cache.memory_size, qcm, queryCacheMemory
使用的查询缓存内存，例如 0b。
query_cache.evictions, qce, queryCacheEvictions
查询缓存逐出次数，例如 0。
recoverysource.type, rs
恢复源的类型。
refresh.total, rto, refreshTotal
刷新次数，例如 16。
refresh.time, rti, refreshTime
花费在刷新上的时间，例如 91ms。
search.fetch_current, sfc, searchFetchCurrent
当前获取阶段操作，例如 0。
search.fetch_time, sfti, searchFetchTime
花费在获取阶段的时间，例如 37ms。
search.fetch_total, sfto, searchFetchTotal
获取操作的数量，例如 7。
search.open_contexts, so, searchOpenContexts
打开的搜索上下文，例如 0。
search.query_current, sqc, searchQueryCurrent
当前查询阶段操作，例如 0。
search.query_time, sqti, searchQueryTime
花费在查询阶段的时间，例如 43ms。
search.query_total, sqto, searchQueryTotal
查询操作的数量，例如 9。
search.scroll_current, scc, searchScrollCurrent
打开的滚动上下文，例如 2。
search.scroll_time, scti, searchScrollTime
滚动上下文保持打开的时间，例如 2m。
search.scroll_total, scto, searchScrollTotal
完成的滚动上下文，例如 1。
segments.count, sc, segmentsCount
段的数量，例如 4。
segments.memory, sm, segmentsMemory
段使用的内存，例如 1.4kb。
segments.index_writer_memory, siwm, segmentsIndexWriterMemory
索引写入器使用的内存，例如 18mb。
segments.version_map_memory, svmm, segmentsVersionMapMemory
版本映射使用的内存，例如 1.0kb。
segments.fixed_bitset_memory, sfbm, fixedBitsetMemory
嵌套对象字段类型和join字段中引用的类型过滤器所使用的固定位集内存，例如 1.0kb。
seq_no.global_checkpoint, sqg, globalCheckpoint
全局检查点。
seq_no.local_checkpoint, sql, localCheckpoint
本地检查点。
seq_no.max, sqm, maxSeqNo
最大序列号。
sparse_vector.value_count, svc, sparseVectorCount
已索引的稀疏向量的数量。
suggest.current, suc, suggestCurrent
当前建议操作的数量，例如 0。
suggest.time, suti, suggestTime
在建议上花费的时间，例如 0。
suggest.total, suto, suggestTotal
建议操作的数量，例如 0。
sync_id
分片的同步 ID。
unassigned.at, ua
分片在协调世界时 (UTC)中变为未分配状态的时间。
unassigned.details, ud
有关分片为何变为未分配状态的详细信息。这并不解释为什么该分片当前未分配。要了解为什么未分配分片，请使用集群分配解释 API。
unassigned.for, uf
在协调世界时 (UTC)中请求未分配分片的时间。
unassigned.reason, ur

指示此未分配分片的状态发生上次更改的原因。这并不解释为什么该分片当前未分配。要了解为什么未分配分片，请使用集群分配解释 API。返回的值包括

  • ALLOCATION_FAILED：由于分片分配失败而未分配。
  • CLUSTER_RECOVERED：由于完整的集群恢复而未分配。
  • DANGLING_INDEX_IMPORTED：由于导入悬空索引而未分配。
  • EXISTING_INDEX_RESTORED：由于恢复到关闭的索引而未分配。
  • FORCED_EMPTY_PRIMARY：上次通过使用集群重新路由 API 强制创建空主分片而修改了该分片的分配。
  • INDEX_CLOSED：由于索引已关闭而未分配。
  • INDEX_CREATED：由于通过 API 创建索引而未分配。
  • INDEX_REOPENED：由于打开关闭的索引而未分配。
  • MANUAL_ALLOCATION：上次通过集群重新路由 API 修改了该分片的分配。
  • NEW_INDEX_RESTORED：由于恢复到新索引而未分配。
  • NODE_LEFT：由于托管该分片的节点离开集群而未分配。
  • NODE_RESTARTING：与NODE_LEFT类似，只是该节点已使用节点关闭 API 注册为正在重新启动。
  • PRIMARY_FAILED：该分片正在作为副本进行初始化，但主分片在初始化完成之前失败。
  • REALLOCATED_REPLICA：确定了更好的副本位置，并导致取消现有副本分配。
  • REINITIALIZED：当分片从已启动状态移回初始化状态时。
  • REPLICA_ADDED：由于显式添加副本而未分配。
  • REROUTE_CANCELLED：由于显式取消重新路由命令而未分配。
help
(可选，布尔值) 如果为 true，则响应包括帮助信息。默认为 false。
master_timeout
(可选，时间单位) 等待主节点的时间段。如果主节点在超时到期之前不可用，则请求失败并返回错误。默认为 30s。也可以设置为 -1，以指示请求永远不应超时。
s
(可选，字符串) 用于对响应进行排序的列名或列别名的逗号分隔列表。
time
(可选，时间单位) 用于显示时间值的单位。
v
(可选，布尔值) 如果为 true，则响应包括列标题。默认为 false。

示例

编辑

单个数据流或索引的示例

编辑
resp = client.cat.shards()
print(resp)
response = client.cat.shards
puts response
const response = await client.cat.shards();
console.log(response);
GET _cat/shards
Copy as curlTry in Elastic 

API 返回以下响应

my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA

使用通配符模式的示例

编辑

如果您的集群有许多分片，则可以在 <target> 路径参数中使用通配符模式来限制 API 请求。

以下请求返回以 my-index- 开头的任何数据流或索引的信息。

resp = client.cat.shards(
    index="my-index-*",
)
print(resp)
response = client.cat.shards(
  index: 'my-index-*'
)
puts response
const response = await client.cat.shards({
  index: "my-index-*",
});
console.log(response);
GET _cat/shards/my-index-*
Copy as curlTry in Elastic 

API 返回以下响应

my-index-000001 0 p STARTED 3014 31.1mb 192.168.56.10 H5dfFeA

使用正在重新定位的分片的示例

编辑
resp = client.cat.shards()
print(resp)
response = client.cat.shards
puts response
const response = await client.cat.shards();
console.log(response);
GET _cat/shards
Copy as curlTry in Elastic 

API 返回以下响应

my-index-000001 0 p RELOCATING 3014 31.1mb 192.168.56.10 H5dfFeA -> -> 192.168.56.30 bGG90GE

state 列中的 RELOCATING 值表示索引分片正在重新定位。

使用分片状态的示例

编辑

在分片可用之前，它会经历一个 INITIALIZING 状态。您可以使用 cat 分片 API 来查看哪些分片正在初始化。

resp = client.cat.shards()
print(resp)
response = client.cat.shards
puts response
const response = await client.cat.shards();
console.log(response);
GET _cat/shards
Copy as curlTry in Elastic 

API 返回以下响应

my-index-000001 0 p STARTED      3014 31.1mb 192.168.56.10 H5dfFeA
my-index-000001 0 r INITIALIZING    0 14.3mb 192.168.56.30 bGG90GE

使用未分配分片原因的示例

编辑

以下请求返回 unassigned.reason 列，该列指示分片未分配的原因。

resp = client.cat.shards(
    h="index,shard,prirep,state,unassigned.reason",
)
print(resp)
response = client.cat.shards(
  h: 'index,shard,prirep,state,unassigned.reason'
)
puts response
const response = await client.cat.shards({
  h: "index,shard,prirep,state,unassigned.reason",
});
console.log(response);
GET _cat/shards?h=index,shard,prirep,state,unassigned.reason
Copy as curlTry in Elastic 

API 返回以下响应

my-index-000001 0 p STARTED    3014 31.1mb 192.168.56.10 H5dfFeA
my-index-000001 0 r STARTED    3014 31.1mb 192.168.56.30 bGG90GE
my-index-000001 0 r STARTED    3014 31.1mb 192.168.56.20 I8hydUG
my-index-000001 0 r UNASSIGNED ALLOCATION_FAILED
« cat 段 API cat 快照 API »