Get segment information

GET /_cat/segments/{index}
GET /_cat/segments

Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the backing indices. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the index segments API.

Required authorization

Index privileges: monitor
Cluster privileges: monitor

Path Parameters

index union IndexName | [] IndexName optional

A comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Leave it out to use /_cat/segments.

Query Parameters

h CatSegmentsColumns · default: ip,hp,rp,r,m,n,cpu,l

A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:

index (or i, idx): The name of the index.
shard (or s, sh): The name of the shard.
prirep (or p, pr, primaryOrReplica): The shard type. Returned values are 'primary' or 'replica'.
ip: IP address of the segment’s shard, such as '127.0.1.1'.
segment: The name of the segment, such as '_0'. The segment name is derived from the segment generation and used internally to create file names in the directory of the shard.
generation: Generation number, such as '0'. Elasticsearch increments this generation number for each segment written. Elasticsearch then uses this number to derive the segment name.
docs.count: The number of documents as reported by Lucene. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment.
docs.deleted: The number of deleted documents as reported by Lucene, which may be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, Elasticsearch creates extra deleted documents to internally track the recent history of operations on a shard.
size: The disk space used by the segment, such as '50kb'.
size.memory: The bytes of segment data stored in memory for efficient search, such as '1264'. A value of '-1' indicates Elasticsearch was unable to compute this number.
committed: If 'true', the segments is synced to disk. Segments that are synced can survive a hard reboot. If 'false', the data from uncommitted segments is also stored in the transaction log so that Elasticsearch is able to replay changes on the next start.
searchable: If 'true', the segment is searchable. If 'false', the segment has most likely been written to disk but needs a refresh to be searchable.
version: The version of Lucene used to write the segment.
compound: If 'true', the segment is stored in a compound file. This means Lucene merged all files from the segment in a single file to save file descriptors.
id: The ID of the node, such as 'k0zy'.

Values: index i idx shard s sh prirep p pr primaryOrReplica ip segment generation docs.count docs.deleted size size.memory committed searchable version compound id

s union Names

A comma-separated list of column names or aliases that determines the sort order. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

One of: Name or Name[]

local boolean · default: false

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.

master_timeout string Duration · default: 30s

Period to wait for a connection to the master node.

expand_wildcards string ExpandWildcards · default: open

Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden.

Supported values include:

all: Match any data stream or index, including hidden ones.
open: Match open, non-hidden indices. Also matches any non-hidden data stream.
closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
none: Wildcard expressions are not accepted.

Values: all open closed hidden none

allow_no_indices boolean · default: true

A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

ignore_throttled boolean · default: false

If true, concrete, expanded or aliased indices are ignored when frozen.

ignore_unavailable boolean · default: false

If false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

allow_closed boolean · default: false

If true, allow closed indices to be returned in the response otherwise if false, keep the legacy behaviour of throwing an exception if index pattern matches closed indices

Response

application/json

Response Type: [] SegmentsRecord

index string IndexName: The index name.
shard string: The shard name.
prirep string: The shard type: primary or replica.
ip string: The IP address of the node where it lives.
id string: The unique identifier of the node where it lives.
segment string: The segment name, which is derived from the segment generation and used internally to create file names in the directory of the shard.
generation string: The segment generation number. Elasticsearch increments this generation number for each segment written then uses this number to derive the segment name.
docs.count string: The number of documents in the segment. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment.
docs.deleted string: The number of deleted documents in the segment, which might be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, Elasticsearch creates extra deleted documents to internally track the recent history of operations on a shard.
size number | string ByteSize: The segment size in bytes.
size.memory number | string ByteSize: The segment memory in bytes. A value of -1 indicates Elasticsearch was unable to compute this number.
committed string: If true, the segment is synced to disk. Segments that are synced can survive a hard reboot. If false, the data from uncommitted segments is also stored in the transaction log so that Elasticsearch is able to replay changes on the next start.
searchable string: If true, the segment is searchable. If false, the segment has most likely been written to disk but needs a refresh to be searchable.
version string: The version of Lucene used to write the segment.
compound string: If true, the segment is stored in a compound file. This means Lucene merged all files from the segment in a single file to save file descriptors.

Examples

A successful response from GET /_cat/segments?v=true&format=json.

Request Console 1 / 7 languages

Console Kibana Dev Tools

GET /_cat/segments?v=true&format=json

JavaScript Elasticsearch JavaScript Client

const response = await client.cat.segments({
  v: "true",
  format: "json",
});

Python Elasticsearch Python Client

resp = client.cat.segments(
    v=True,
    format="json",
)

curl Shell

curl -X GET "$ELASTICSEARCH_URL/_cat/segments?v=true&format=json" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"

Java Elasticsearch Java Client

client.cat().segments(s -> s);

PHP Elasticsearch PHP Client

$resp = $client->cat()->segments([
    "v" => "true",
    "format" => "json",
]);

Ruby Elasticsearch Ruby Client

response = client.cat.segments(
  v: "true",
  format: "json"
)

Response

[
  {
    "index": "test",
    "shard": "0",
    "prirep": "p",
    "ip": "127.0.0.1",
    "segment": "_0",
    "generation": "0",
    "docs.count": "1",
    "docs.deleted": "0",
    "size": "3kb",
    "size.memory": "0",
    "committed": "false",
    "searchable": "true",
    "version": "9.12.0",
    "compound": "true"
  },
  {
    "index": "test1",
    "shard": "0",
    "prirep": "p",
    "ip": "127.0.0.1",
    "segment": "_0",
    "generation": "0",
    "docs.count": "1",
    "docs.deleted": "0",
    "size": "3kb",
    "size.memory": "0",
    "committed": "false",
    "searchable": "true",
    "version": "9.12.0",
    "compound": "true"
  }
]

Required authorization

Path Parameters

Query Parameters { h , s , local , master_timeout , expand_wildcards , allow_no_indices , ignore_throttled , ignore_unavailable , allow_closed , }

Response

Query Parameters