elasticsearch/docs/reference/cat/segments.asciidoc

[[cat-segments]]
=== cat segments API
++++
<titleabbrev>cat segments</titleabbrev>
++++

Returns low-level information about the https://lucene.apache.org/core/[Lucene]
segments in index shards, similar to the <<indices-segments, indices segments>>
API.

For data streams, the API returns information about the stream's backing
indices.

[[cat-segments-api-request]]
==== {api-request-title}

`GET /_cat/segments/<target>`

`GET /_cat/segments`

[[cat-segments-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API. You must
also have the `monitor` or `manage` <<privileges-list-indices,index privilege>>
for any data stream, index, or alias you retrieve.

[[cat-segments-path-params]]
==== {api-path-parms-title}

`<target>`::
(Optional, string) 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`.

[[cat-segments-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=bytes]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
--
If you do not specify which columns to include, the API returns the default
columns in the order listed below. If you explicitly specify one or more
columns, it only returns the specified columns.

Valid columns are:

`index`, `i`, `idx`::
(Default) Name of the index.

`shard`, `s`, `sh`::
(Default) Name of the shard.

`prirep`, `p`, `pr`, `primaryOrReplica`::
(Default) Shard type. Returned values are `primary` or `replica`.

`ip`::
(Default) IP address of the segment's shard, such as `127.0.1.1`.

`segment`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=segment]

`generation`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=generation]

`docs.count`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=docs-count]
                
`docs.deleted`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=docs-deleted]

`size`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=segment-size]

`size.memory`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=memory]

`committed`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=committed]

`searchable`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=segment-search]

`version`::
(Default)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=segment-version]

`compound`::
(Default) 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`::
ID of the node, such as `k0zy`.
--

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]


[[cat-segments-api-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
GET /_cat/segments?v=true
--------------------------------------------------
// TEST[s/^/PUT \/test\/_doc\/1?refresh\n{"test":"test"}\nPUT \/test1\/_doc\/1?refresh\n{"test":"test"}\n/]

The API returns the following response:

["source","txt",subs="attributes,callouts"]
--------------------------------------------------
index shard prirep ip        segment generation docs.count docs.deleted size size.memory committed searchable version compound
test  0     p      127.0.0.1 _0               0          1            0  3kb        2042 false     true       {lucene_version}   true
test1 0     p      127.0.0.1 _0               0          1            0  3kb        2042 false     true       {lucene_version}   true
--------------------------------------------------
// TESTRESPONSE[s/3kb/\\d+(\\.\\d+)?[mk]?b/ s/2042/\\d+/ non_json]