CAT Indices API

Introduced 1.0

The CAT indices operation lists information related to indexes, that is, how much disk space they are using, how many shards they have, their health status, and so on.

The document counts in the response are sourced directly from Lucene, so they include hidden nested documents. For example, a document containing two nested objects counts as three documents. To count only top-level documents, use the CAT count or Count API.

Endpoints

GET /_cat/indices
GET /_cat/indices/{index}

Query parameters

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

Example requests

GET /_cat/indices?v

response = client.cat.indices(
  params = { "v": "true" }
)

To limit the information to a specific index, add the index name after your query.

GET /_cat/indices/<index>?v

response = client.cat.indices(
  index = "<index>",
  params = { "v": "true" }
)

If you want to get information for more than one index, separate the indexes with commas:

GET /_cat/indices/index1,index2,index3

response = client.cat.indices(
  index = "index1,index2,index3"
)

Example response

health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
green  | open | movies | UZbpfERBQ1-3GSH2bnM3sg | 1 | 1 | 1 | 0 | 7.7kb | 3.8kb

Response columns

By default, the response contains the health, status, index, uuid, pri, rep, docs.count, docs.deleted, store.size, and pri.store.size columns. To choose the columns to display, provide a comma-separated list of column names or aliases in the h query parameter. The h parameter also accepts wildcards, for example, h=index,search.*. To list all available columns, send GET /_cat/indices?help.

For example, the following request returns the name, health, document count, and store size of the opensearch_dashboards_sample_data_ecommerce index:

GET /_cat/indices/opensearch_dashboards_sample_data_ecommerce?v&h=index,health,docs.count,store.size

The response contains only the requested columns:

index                                       health docs.count store.size
opensearch_dashboards_sample_data_ecommerce green        4675        4mb

The following table lists the general index information columns.

The following table lists the index statistics columns. These columns report values for both primary and replica shards. Each column has a counterpart prefixed with pri. that reports the value for primary shards only, for example, pri.completion.size or pri.search.query_total. The pri. columns have no aliases. The primary-shard counterparts of search.startree_query_current, search.startree_query_time, and search.startree_query_total are named pri.search.startree.query_current, pri.search.startree.query_time, and pri.search.startree.query_total.

System indexes

Introduced 3.9

The system query parameter filters indexes by their system index classification:

• system=true returns only system indexes.
• system=false returns only non-system indexes.

Omitting system returns both system and non-system indexes, subject to the request’s index selection and wildcard expansion.

When system=true and expand_wildcards is omitted, wildcard expansion includes hidden indexes by default. When system=false or system is omitted, hidden indexes are not included in wildcard expansion by default. An explicit expand_wildcards value overrides these defaults. For example, system=true&expand_wildcards=open excludes hidden indexes, while system=true&expand_wildcards=all includes open, closed, and hidden indexes.

An index’s system classification is independent of whether the index is hidden. The system filter does not identify every hidden index or every index protected by the Security plugin. It does not grant access to indexes; your existing permissions still apply. For information about how the Security plugin protects system indexes, see System indexes.

The response includes the system and system.description columns whenever you specify system, including system=false. When system is omitted, the default columns are unchanged. Use h to select the columns explicitly. Selecting either column with h does not change index selection or include hidden indexes in wildcard expansion.

The description is provided independently of the system flag. An index without a matching descriptor has no description. If the descriptor registry and the index metadata are temporarily out of sync, an index with system=false can still have a description.

For example, to list system indexes and their descriptions, including hidden indexes by default, use the following request:

GET /_cat/indices?system=true&h=index,system,system.description&format=json

The following example response is for a cluster containing a task result index:

[
  {
    "index": ".tasks",
    "system": "true",
    "system.description": "Task Result Index"
  }
]

To display both system and non-system indexes, including open, closed, and hidden indexes, use the following request:

GET /_cat/indices?expand_wildcards=all&h=index,system,system.description&format=json

Limiting the response size

To limit the number of indexes returned, configure the cat.indices.response.limit.number_of_indices setting. For more information, see Cluster-level CAT response limit settings.

When system is specified, the limit counts only indexes that match the requested system classification.

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: indices:monitor/stats and cluster:monitor/state.