--- type: api title: Get index segments description: Get low-level information about the Lucene segments in index shards. url: https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-indices-segments resource: https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-indices-segments products: - Elasticsearch --- # Get index segments Authentication: required ## Paths - `GET` `/{index}/_segments` - `GET` `/_segments` #### Path parameters - `index` (union string | string[]) — optional, leave it out to use `/_segments` 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`. ## Description Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the stream's backing indices. ## Required privileges - Index privileges: `monitor` ## Query string parameters - `allow_no_indices` (boolean · default: true) — optional A setting that does two separate checks on the index expression. If `false`, the request returns an error (1) if any wildcard expression (including `_all` and `*`) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If `true`, index expressions that resolve to no indices are allowed and the request returns an empty result. - `expand_wildcards` (union oneOf · default: open) — optional Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`. Supported values include: - `all`: Match any data stream or index, including hidden ones. - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream. - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed. - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`. - `none`: Wildcard expressions are not accepted. Values: `all`, `open`, `closed`, `hidden`, `none` - `ignore_unavailable` (boolean · default: false) — optional If `false`, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If `true`, unavailable concrete targets are silently ignored. - `include_auto_calibration` (boolean · default: false) — optional If `true`, the response includes the auto-calibration information of each segment, for the `dense_vector` fields that support auto-calibration. - `vector_formats` (boolean · default: false) — optional If `true`, the response includes the vector formats used by the fields of each segment, in `attributes`. ## Response `application/json` - `indices` (map string to object) Map values (object) - `shards` (map string to oneOf) Map values (union oneOf) One of: - **[]ShardsSegment** - `num_committed_segments` (number) - `routing` (object) - `node` (string) The node ID of the node that holds the shard. - `relocating_node` (string) The node ID of the node the shard is relocating to. Only returned while the shard is relocating. - `primary` (boolean) If `true`, the shard is a primary shard. - `state` (string) The state of the shard, such as `STARTED` or `RELOCATING`. - `num_search_segments` (number) - `segments` (map string to object) Map values (object) - `attributes` (map string to string) Contains information about whether high compression was enabled and per-field vector formats. - `committed` (boolean) If `true`, the segment is synced to disk. Segments that are synced can survive a hard reboot. If `false`, the data from uncommitted segments is also stored in the transaction log so that Elasticsearch is able to replay changes on the next start. - `compound` (boolean) If `true`, Lucene merged all files from the segment into a single file to save file descriptors. - `deleted_docs` (number) The number of deleted documents as reported by Lucene, which may be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, Elasticsearch creates extra deleted documents to internally track the recent history of operations on a shard. - `generation` (number) Generation number, such as `0`. Elasticsearch increments this generation number for each segment written then uses this number to derive the segment name. - `search` (boolean) If `true`, the segment is searchable. If `false`, the segment has most likely been written to disk but needs a refresh to be searchable. - `merge_id` (string) The ID of the merge the segment is part of. Only returned while the segment is being merged. - `sort` (object[]) The index sort of the segment. Only returned when the index is sorted. - `field` (string) The name of the sort field. - `mode` (string) The selector used to pick a value from multi-valued fields, such as `min` or `max`. Only returned for numeric and keyword fields. - `missing` (string) The value used for documents that are missing the field. - `reverse` (boolean) If `true`, the sort order is descending. - `size` (number | string) Disk space used by the segment. - `size_in_bytes` (number) Disk space used by the segment, in bytes. - `num_docs` (number) The number of documents as reported by Lucene. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment. - `version` (string) Version of Lucene used to write the segment. - `auto_calibration` (map string to oneOf) The auto-calibration information of the segment, per `dense_vector` field that supports auto-calibration. Only returned when `include_auto_calibration` is `true`. Map values (union oneOf) One of: - **type: osq** (`type: osq`) - `type` (enum) Values: `osq` - `calibrated` (boolean) If `true`, the segment has been calibrated, and `parameters` is present. - `number_of_vectors` (number) The number of vectors of the field in the segment. - `size` (number | string) - `size_in_bytes` (number) The size of the vectors of the field in the segment, in bytes. - `parameters` (object) The calibration parameters. - `bits` (number) The number of bits used to quantize the vectors. - `query_bits` (number) The number of bits used to quantize the query vectors. - `precondition` (boolean) If `true`, the vectors are preconditioned before quantization. - `oversample` (number) The oversampling factor applied when rescoring. - **ShardsSegment** - `num_committed_segments` (number) - `routing` (object) - `node` (string) The node ID of the node that holds the shard. - `relocating_node` (string) The node ID of the node the shard is relocating to. Only returned while the shard is relocating. - `primary` (boolean) If `true`, the shard is a primary shard. - `state` (string) The state of the shard, such as `STARTED` or `RELOCATING`. - `num_search_segments` (number) - `segments` (map string to object) Map values (object) - `attributes` (map string to string) Contains information about whether high compression was enabled and per-field vector formats. - `committed` (boolean) If `true`, the segment is synced to disk. Segments that are synced can survive a hard reboot. If `false`, the data from uncommitted segments is also stored in the transaction log so that Elasticsearch is able to replay changes on the next start. - `compound` (boolean) If `true`, Lucene merged all files from the segment into a single file to save file descriptors. - `deleted_docs` (number) The number of deleted documents as reported by Lucene, which may be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, Elasticsearch creates extra deleted documents to internally track the recent history of operations on a shard. - `generation` (number) Generation number, such as `0`. Elasticsearch increments this generation number for each segment written then uses this number to derive the segment name. - `search` (boolean) If `true`, the segment is searchable. If `false`, the segment has most likely been written to disk but needs a refresh to be searchable. - `merge_id` (string) The ID of the merge the segment is part of. Only returned while the segment is being merged. - `sort` (object[]) The index sort of the segment. Only returned when the index is sorted. - `field` (string) The name of the sort field. - `mode` (string) The selector used to pick a value from multi-valued fields, such as `min` or `max`. Only returned for numeric and keyword fields. - `missing` (string) The value used for documents that are missing the field. - `reverse` (boolean) If `true`, the sort order is descending. - `size` (number | string) Disk space used by the segment. - `size_in_bytes` (number) Disk space used by the segment, in bytes. - `num_docs` (number) The number of documents as reported by Lucene. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment. - `version` (string) Version of Lucene used to write the segment. - `auto_calibration` (map string to oneOf) The auto-calibration information of the segment, per `dense_vector` field that supports auto-calibration. Only returned when `include_auto_calibration` is `true`. Map values (union oneOf) One of: - **type: osq** (`type: osq`) - `type` (enum) Values: `osq` - `calibrated` (boolean) If `true`, the segment has been calibrated, and `parameters` is present. - `number_of_vectors` (number) The number of vectors of the field in the segment. - `size` (number | string) - `size_in_bytes` (number) The size of the vectors of the field in the segment, in bytes. - `parameters` (object) The calibration parameters. - `bits` (number) The number of bits used to quantize the vectors. - `query_bits` (number) The number of bits used to quantize the query vectors. - `precondition` (boolean) If `true`, the vectors are preconditioned before quantization. - `oversample` (number) The oversampling factor applied when rescoring. - `_shards` (object) - `failed` (number) The number of shards the operation or search attempted to run on but failed. - `successful` (number) The number of shards the operation or search succeeded on. - `total` (number) The number of shards the operation or search will run on overall. - `failures` (object[]) - `index` (string) - `node` (string) - `reason` (object) - `type` (string) The type of error - `reason` (union string) — nullable A human-readable explanation of the error, in English. One of: `string` - `stack_trace` (string) The server stack trace. Present only if the `error_trace=true` parameter was sent with the request. - `caused_by` (object) — recursive Same fields as `reason` in `failures` - `root_cause` (object[]) — recursive Same fields as `reason` in `failures` - `suppressed` (object[]) — recursive Same fields as `reason` in `failures` - `shard` (number) - `status` (string) - `primary` (boolean) - `skipped` (number) ## Code examples #### Console ```console GET /my-index-000001/_segments ``` #### JavaScript ```javascript const response = await client.indices.segments({ index: "my-index-000001", }); ``` #### Python ```python resp = client.indices.segments( index="my-index-000001", ) ``` #### curl ```curl curl -X GET "$ELASTICSEARCH_URL/my-index-000001/_segments" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" ``` #### Java ```java client.indices().segments(s -> s .index("my-index-000001") ); ``` #### C# ```c# var response = await client.Indices .SegmentsAsync(d1 => d1 .Indices(new[] { "my-index-000001" }) ); ``` #### PHP ```php $resp = $client->indices()->segments([ "index" => "my-index-000001", ]); ``` #### Ruby ```ruby response = client.indices.segments( index: "my-index-000001" ) ``` ## Response examples #### Indices segments response example1 `application/json` A response describing information about index segments. ```json { "_shards": { "total": 2, "successful": 2, "failed": 0 }, "indices": { "kibana_sample_data_ecommerce": { "shards": { "0": [ { "routing": { "state": "STARTED", "primary": false, "node": "zZg9NuPhQPKO3LMRkMo2iw" }, "num_committed_segments": 4, "num_search_segments": 4, "segments": { "_0": { "generation": 0, "num_docs": 500, "deleted_docs": 0, "size_in_bytes": 524718, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_1": { "generation": 1, "num_docs": 500, "deleted_docs": 0, "size_in_bytes": 526100, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_2": { "generation": 2, "num_docs": 2000, "deleted_docs": 0, "size_in_bytes": 1846181, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_3": { "generation": 3, "num_docs": 1675, "deleted_docs": 0, "size_in_bytes": 1572960, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } } } }, { "routing": { "state": "STARTED", "primary": true, "node": "sp27SQiNTQWKpBKoRcnfQQ" }, "num_committed_segments": 5, "num_search_segments": 5, "segments": { "_0": { "generation": 0, "num_docs": 187, "deleted_docs": 0, "size_in_bytes": 227245, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_1": { "generation": 1, "num_docs": 253, "deleted_docs": 0, "size_in_bytes": 297549, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_2": { "generation": 2, "num_docs": 560, "deleted_docs": 0, "size_in_bytes": 580918, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_3": { "generation": 3, "num_docs": 1603, "deleted_docs": 0, "size_in_bytes": 1506385, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } }, "_4": { "generation": 4, "num_docs": 2072, "deleted_docs": 0, "size_in_bytes": 1913051, "committed": true, "search": true, "version": "10.3.1", "compound": true, "attributes": { "Lucene90StoredFieldsFormat.mode": "BEST_SPEED" } } } } ] } } } } ```