Segment

Introduced 1.0

The Segment API provides details about the Lucene segments within index shards as well as information about the backing indexes of data streams.

Path and HTTP methods

  1. GET /<index>/_segments
  2. GET /_segments

Path parameters

The following table lists the available path parameters. All path parameters are optional.

ParameterData typeDescription
<index>StringA comma-separated list of indexes, data streams, or index aliases to which the operation is applied. Supports wildcard expressions (). Use _all or to specify all indexes and data streams in a cluster.

Query parameters

All query parameters are optional.

ParameterData typeDescription
allow_no_indicesBooleanWhether to ignore wildcards that don’t match any indexes. Default is true.
expand_wildcardsStringSpecifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indexes), closed (match closed, non-hidden indexes), hidden (match hidden indexes), and none (deny wildcard expressions). Default is open.
ignore_unavailableBooleanWhen true, OpenSearch ignores missing or closed indexes. If false, OpenSearch returns an error if the force merge operation encounters missing or closed indexes. Default is false.
verboseBooleanWhen true, provides information about Lucene’s memory usage. Default is false.

Example requests

The following example requests show you how to use the Segment API.

Specific data stream or index

  1. GET /index1/_segments

copy

Several data streams and indexes

  1. GET /index1,index2/_segments

copy

All data streams and indexes in a cluster

  1. GET /_segments

copy

Example response

  1. {
  2.   "_shards": ...
  3.   "indices": {
  4.     "test": {
  5.       "shards": {
  6.         "0": [
  7.           {
  8.             "routing": {
  9.               "state": "STARTED",
  10.               "primary": true,
  11.               "node": "zDC_RorJQCao9xf9pg3Fvw"
  12.             },
  13.             "num_committed_segments": 0,
  14.             "num_search_segments": 1,
  15.             "segments": {
  16.               "_0": {
  17.                 "generation": 0,
  18.                 "num_docs": 1,
  19.                 "deleted_docs": 0,
  20.                 "size_in_bytes": 3800,
  21.                 "memory_in_bytes": 1410,
  22.                 "committed": false,
  23.                 "search": true,
  24.                 "version": "7.0.0",
  25.                 "compound": true,
  26.                 "attributes": {
  27.                 }
  28.               }
  29.             }
  30.           }
  31.         ]
  32.       }
  33.     }
  34.   }
  35. }

Response body fields

ParameterData typeDescription
<segment>StringThe name of the segment used to create internal file names in the shard directory.
generationIntegerThe generation number, such as 0, incremented for each written segment and used to name the segment.
num_docsIntegerThe number of documents, obtained from Lucene. Nested documents are counted separately from their parents. Deleted documents, as well as recently indexed documents that are not yet assigned to a segment, are excluded.
deleted_docsIntegerThe number of deleted documents, obtained from Lucene, which may not match the actual number of delete operations performed. Recently deleted documents that are not yet assigned to a segment are excluded. Deleted documents are automatically merged when appropriate. OpenSearch will occasionally delete extra documents in order to track recent shard operations.
size_in_bytesIntegerThe amount of disk space used by the segment, for example, 50kb.
memory_in_bytesIntegerThe amount of segment data, measured in bytes, that is kept in memory to facilitate efficient search operations, such as 1264. A value of -1 indicates that OpenSearch was unable to compute this number.
committedBooleanWhen true, the segments are synced to disk. Segments synced to disk can survive a hard reboot. If false, then uncommitted segment data is stored in the transaction log as well so that changes can be replayed at the next startup.
searchBooleanWhen true, segment search is enabled. When false, the segment may have already been written to disk and require a refresh in order to be searchable.
versionStringThe Lucene version used to write the segment.
compoundBooleanWhen true, indicates that Lucene merged all segment files into one file in order to save any file descriptions.
attributesObjectShows if high compression was enabled.