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>`


[[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) 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`::
(Default) Generation number, such as `0`. {es} increments this generation number
for each segment written. {es} then uses this number to derive the segment name.

`docs.count`::
(Default) Number of non-deleted documents in the segment, such as `25`. This
number is based on Lucene documents and may include documents from
<<nested,nested>> fields.
                
`docs.deleted`::
(Default) Number of deleted documents in the segment, such as `0`. This number
is based on Lucene documents. {es} reclaims the disk space of deleted Lucene
documents when a segment is merged.

`size`::
(Default) Disk space used by the segment, such as `50kb`.

`size.memory`::
(Default) Bytes of segment data stored in memory for efficient search, such as
`1264`.

`committed`::
(Default) If `true`, the segment is committed to disk. Segments committed to
disk would survive a hard reboot. 
+
If `false`, the data from uncommitted segments is also stored in the transaction
log. {es} replays those changes on the next start.

`searchable`::
(Default) If `true`, the segment is searchable.
+
If `false`, likely means the segment is written to disk but has not been
<<docs-refresh,refreshed>>.

`version`::
(Default) Version of Lucene used to write the segment.

`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,js]
--------------------------------------------------
GET /_cat/segments?v
--------------------------------------------------
// CONSOLE
// 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]