elasticsearch/docs/reference/cat/segments.asciidoc

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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-cat[Compact and aligned text (CAT) APIs]..
--

[IMPORTANT]
====
cat APIs are only intended for human consumption using the command line or {kib} 
console. They are _not_ intended for use by applications. For application 
consumption, use the <<indices-segments,index segments API>>.
====

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-ref-dir}/rest-api/common-parms.asciidoc[tag=bytes]

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

include::{es-ref-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-ref-dir}/rest-api/common-parms.asciidoc[tag=segment]

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

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

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

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

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

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

`version`::
(Default)
include::{es-ref-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-ref-dir}/rest-api/common-parms.asciidoc[tag=help]

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

include::{es-ref-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           0 false     true       {lucene_version}   true
test1 0     p      127.0.0.1 _0               0          1            0  3kb           0 false     true       {lucene_version}   true
--------------------------------------------------
// TESTRESPONSE[s/3kb/\\d+(\\.\\d+)?[mk]?b/ s/2042/\\d+/ non_json]