You're viewing version 2.16 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
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
GET /<index-name>/_segments
GET /_segments
Path parameters
The following table lists the available path parameters. All path parameters are optional.
| Parameter | Data type | Description |
|---|---|---|
<index> | String | A 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
The Segment API supports the following optional query parameters.
| Parameter | Data type | Description |
|---|---|---|
allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indexes. Default is true. |
expand_wildcards | String | Specifies 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_unavailable | Boolean | When 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. |
verbose | Boolean | When true, provides information about Lucene’s memory usage. Default is false. |
Response body fields
| Parameter | Data type | Description |
|---|---|---|
<segment> | String | The name of the segment used to create internal file names in the shard directory. |
generation | Integer | The generation number, such as 0, incremented for each written segment and used to name the segment. |
num_docs | Integer | The 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_docs | Integer | The 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_bytes | Integer | The amount of disk space used by the segment, for example, 50kb. |
memory_in_bytes | Integer | The 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. |
committed | Boolean | When 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. |
search | Boolean | When 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. |
version | String | The Lucene version used to write the segment. |
compound | Boolean | When true, indicates that Lucene merged all segment files into one file in order to save any file descriptions. |
attributes | Object | Shows if high compression was enabled. |
Example requests
The following example requests show you how to use the Segment API.
Specific data stream or index
GET /index1/_segments
Several data streams and indexes
GET /index1,index2/_segments
All data streams and indexes in a cluster
GET /_segments
Example response
{
"_shards": ...
"indices": {
"test": {
"shards": {
"0": [
{
"routing": {
"state": "STARTED",
"primary": true,
"node": "zDC_RorJQCao9xf9pg3Fvw"
},
"num_committed_segments": 0,
"num_search_segments": 1,
"segments": {
"_0": {
"generation": 0,
"num_docs": 1,
"deleted_docs": 0,
"size_in_bytes": 3800,
"memory_in_bytes": 1410,
"committed": false,
"search": true,
"version": "7.0.0",
"compound": true,
"attributes": {
}
}
}
}
]
}
}
}
}