OpenSearch/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.

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

`GET /_cat/segments/<index>`

`GET /_cat/segments`


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

include::{docdir}/rest-api/common-parms.asciidoc[tag=index]


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

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

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

include::{docdir}/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, such as `twitter`.

`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::{docdir}/rest-api/common-parms.asciidoc[tag=segment]

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

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

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

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

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

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

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

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

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


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

[source,console]
--------------------------------------------------
GET /_cat/segments?v
--------------------------------------------------
// TEST[s/^/PUT \/test\/test\/1?refresh\n{"test":"test"}\nPUT \/test1\/test\/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]