Compact and aligned text (CAT)

The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, it's recommend to use a corresponding JSON API. All the cat commands accept a query string parameter help to see all the headers and info they provide, and the /_cat command alone lists all the available commands.

Get follower stats Added in 6.5.0

GET /{index}/_ccr/stats

Api key auth Basic auth Bearer auth

Get cross-cluster replication follower stats. The API returns shard-level stats about the "following tasks" associated with each shard for the specified indices.

External documentation

Path parameters

index string | array[string] Required

A comma-delimited list of index patterns.

Query parameters

timeout string

The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

Responses

200 application/json
Hide response attribute Show response attribute object
- indices array[object] Required
  
  An array of follower index statistics.
  
  Hide indices attributes Show indices attributes object
  
  index string Required
  
  shards array[object] Required
  
  An array of shard-level following task statistics.
  
  Hide shards attributes Show shards attributes object
  
  bytes_read number Required
  
  The total of transferred bytes read from the leader. This is only an estimate and does not account for compression if enabled.
  
  failed_read_requests number Required
  
  The number of failed reads.
  
  failed_write_requests number Required
  
  The number of failed bulk write requests on the follower.
  
  fatal_exception object
  
  Hide fatal_exception attributes Show fatal_exception attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  follower_aliases_version number Required
  
  follower_global_checkpoint number Required
  
  The current global checkpoint on the follower. The difference between the leader_global_checkpoint and the follower_global_checkpoint is an indication of how much the follower is lagging the leader.
  
  follower_index string Required
  
  The name of the follower index.
  
  follower_mapping_version number Required
  
  follower_max_seq_no number Required
  
  follower_settings_version number Required
  
  last_requested_seq_no number Required
  
  leader_global_checkpoint number Required
  
  The current global checkpoint on the leader known to the follower task.
  
  leader_index string Required
  
  The name of the index in the leader cluster being followed.
  
  leader_max_seq_no number Required
  
  operations_read number Required
  
  The total number of operations read from the leader.
  
  operations_written number Required
  
  The number of operations written on the follower.
  
  outstanding_read_requests number Required
  
  The number of active read requests from the follower.
  
  outstanding_write_requests number Required
  
  The number of active bulk write requests on the follower.
  
  read_exceptions array[object] Required
  
  An array of objects representing failed reads.
  
  remote_cluster string Required
  
  The remote cluster containing the leader index.
  
  shard_id number Required
  
  The numerical shard ID, with values from 0 to one less than the number of replicas.
  
  successful_read_requests number Required
  
  The number of successful fetches.
  
  successful_write_requests number Required
  
  The number of bulk write requests run on the follower.
  
  time_since_last_read string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  time_since_last_read_millis number
  
  Time unit for milliseconds
  
  total_read_remote_exec_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  total_read_remote_exec_time_millis number
  
  Time unit for milliseconds
  
  total_read_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  total_read_time_millis number
  
  Time unit for milliseconds
  
  total_write_time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  total_write_time_millis number
  
  Time unit for milliseconds
  
  write_buffer_operation_count number Required
  
  The number of write operations queued on the follower.
  
  write_buffer_size_in_bytes number | string Required
  
  One of:
  ByteSize number ByteSize string

GET /{index}/_ccr/stats

curl \
 --request GET 'http://api.example.com/{index}/_ccr/stats' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /follower_index/_ccr/stats`, which retrieves follower stats.

{
  "indices" : [
    {
      "index" : "follower_index",
      "total_global_checkpoint_lag" : 256,
      "shards" : [
        {
          "remote_cluster" : "remote_cluster",
          "leader_index" : "leader_index",
          "follower_index" : "follower_index",
          "shard_id" : 0,
          "leader_global_checkpoint" : 1024,
          "leader_max_seq_no" : 1536,
          "follower_global_checkpoint" : 768,
          "follower_max_seq_no" : 896,
          "last_requested_seq_no" : 897,
          "outstanding_read_requests" : 8,
          "outstanding_write_requests" : 2,
          "write_buffer_operation_count" : 64,
          "follower_mapping_version" : 4,
          "follower_settings_version" : 2,
          "follower_aliases_version" : 8,
          "total_read_time_millis" : 32768,
          "total_read_remote_exec_time_millis" : 16384,
          "successful_read_requests" : 32,
          "failed_read_requests" : 0,
          "operations_read" : 896,
          "bytes_read" : 32768,
          "total_write_time_millis" : 16384,
          "write_buffer_size_in_bytes" : 1536,
          "successful_write_requests" : 16,
          "failed_write_requests" : 0,
          "operations_written" : 832,
          "read_exceptions" : [ ],
          "time_since_last_read_millis" : 8
        }
      ]
    }
  ]
}

Add an index block Added in 7.9.0

PUT /{index}/_block/{block}

Api key auth Basic auth Bearer auth

Add an index block to an index. Index blocks limit the operations allowed on an index by blocking specific operation types.

Path parameters

index string Required

A comma-separated list or wildcard expression of index names used to limit the request. By default, you must explicitly name the indices you are adding blocks to. To allow the adding of blocks to indices with _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. You can update this setting in the elasticsearch.yml file or by using the cluster update settings API.
block string Required

The block type to add to the index.

Values are metadata, read, read_only, or write.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]

The 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. It supports comma-separated values, such as open,hidden.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. It can also be set to -1 to indicate that the request should never timeout.
timeout string

The period to wait for a response from all relevant nodes in the cluster after updating the cluster metadata. If no response is received before the timeout expires, the cluster metadata update still applies but the response will indicate that it was not completely acknowledged. It can also be set to -1 to indicate that the request should never timeout.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- shards_acknowledged boolean Required
- indices array[object] Required
  
  Hide indices attributes Show indices attributes object
  
  name string Required
  
  blocked boolean Required

PUT /{index}/_block/{block}

curl \
 --request PUT 'http://api.example.com/{index}/_block/{block}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `PUT /my-index-000001/_block/write`, which adds an index block to an index.'

{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "indices" : [ {
    "name" : "my-index-000001",
    "blocked" : true
  } ]
}

Delete a query rule Added in 8.15.0

DELETE /_query_rules/{ruleset_id}/_rule/{rule_id}

Api key auth Basic auth Bearer auth

Delete a query rule within a query ruleset. This is a destructive action that is only recoverable by re-adding the same rule with the create or update query rule API.

Path parameters

ruleset_id string Required

The unique identifier of the query ruleset containing the rule to delete
rule_id string Required

The unique identifier of the query rule within the specified ruleset to delete

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_query_rules/{ruleset_id}/_rule/{rule_id}

curl \
 --request DELETE 'http://api.example.com/_query_rules/{ruleset_id}/_rule/{rule_id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "acknowledged": true
}

Search rolled-up data Deprecated Technical preview

GET /{index}/_rollup_search

Api key auth Basic auth Bearer auth

The rollup search endpoint is needed because, internally, rolled-up documents utilize a different document structure than the original data. It rewrites standard Query DSL into a format that matches the rollup documents then takes the response and rewrites it back to what a client would expect given the original query.

The request body supports a subset of features from the regular search API. The following functionality is not available:

size: Because rollups work on pre-aggregated data, no search hits can be returned and so size must be set to zero or omitted entirely. highlighter, suggestors, post_filter, profile, explain: These are similarly disallowed.

Searching both historical rollup and non-rollup data

The rollup search API has the capability to search across both "live" non-rollup data and the aggregated rollup data. This is done by simply adding the live indices to the URI. For example:

GET sensor-1,sensor_rollup/_rollup_search
{
  "size": 0,
  "aggregations": {
     "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}

The rollup search endpoint does two things when the search runs:

The original request is sent to the non-rollup index unaltered.
A rewritten version of the original request is sent to the rollup index.

When the two responses are received, the endpoint rewrites the rollup response and merges the two together. During the merging process, if there is any overlap in buckets between the two responses, the buckets from the non-rollup index are used.

Path parameters

index string | array[string] Required
A comma-separated list of data streams and indices used to limit the request. This parameter has the following rules:
- At least one data stream, index, or wildcard expression must be specified. This target can include a rollup or non-rollup index. For data streams, the stream's backing indices can only serve as non-rollup indices. Omitting the parameter or using _all are not permitted.
- Multiple non-rollup indices may be specified.
- Only one rollup index may be specified. If more than one are supplied, an exception occurs.
- Wildcard expressions (*) may be used. If they match more than one rollup index, an exception occurs. However, you can use an expression to match multiple non-rollup indices or data streams.

Query parameters

rest_total_hits_as_int boolean

Indicates whether hits.total should be rendered as an integer or an object in the rest search response
typed_keys boolean

Specify whether aggregation and suggester names should be prefixed by their respective types in the response

application/json

Body Required

aggregations object

Specifies aggregations.

External documentation
query object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
size number

Must be zero if set, as rollups work on pre-aggregated data.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- timed_out boolean Required
- terminated_early boolean
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object | number
  
  Total hit count information, present only if track_total_hits wasn't false in the search request.
  
  One of:
  TotalHits object number-2 number
  
  Hide attributes Show attributes
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  hits array[object] Required
  
  Hide hits attributes Show hits attributes object
  
  _index string Required
  
  _id string
  
  _score number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  _explanation object
  
  Hide _explanation attributes Show _explanation attributes object
  
  description string Required
  
  details array[object] Required
  
  value number Required
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  * array[string] Additional properties
  
  inner_hits object
  
  Hide inner_hits attribute Show inner_hits attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  hits object Required
  
  matched_queries array[string] | object
  
  One of:
  array-1 array[string] object-2 object
  
  _nested object
  
  Hide _nested attributes Show _nested attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  offset number Required
  
  _nested object
  
  _ignored array[string]
  
  ignored_field_values object
  
  Hide ignored_field_values attribute Show ignored_field_values attribute object
  
  * array[object] Additional properties
  
  _shard string
  
  _node string
  
  _routing string
  
  _source object
  
  _rank number
  
  _seq_no number
  
  _primary_term number
  
  _version number
  
  sort array[number | string | boolean | null]
  
  A field value.
  
  max_score number | string | null
  
  One of:
  number-1 number string-2 string | null
- aggregations object

GET /{index}/_rollup_search

curl \
 --request GET 'http://api.example.com/{index}/_rollup_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"size\": 0,\n  \"aggregations\": {\n    \"max_temperature\": {\n      \"max\": {\n        \"field\": \"temperature\"\n      }\n    }\n  }\n}"'

Request example

Search rolled up data stored in `sensor_rollup` with `GET /sensor_rollup/_rollup_search`

{
  "size": 0,
  "aggregations": {
    "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}

Response examples (200)

An abbreviated response from `GET /sensor_rollup/_rollup_search` with a `max` aggregation on a `temperature` field. The response provides some metadata about the request (`took`, `_shards`), the search hits (which is always empty for rollup searches), and the aggregation response.

{
  "took" : 102,
  "timed_out" : false,
  "terminated_early" : false,
  "_shards" : {} ,
  "hits" : {
    "total" : {
        "value": 0,
        "relation": "eq"
    },
    "max_score" : 0.0,
    "hits" : [ ]
  },
  "aggregations" : {
    "max_temperature" : {
      "value" : 202.0
    }
  }
}

Get follower stats Added in 6.5.0

write_buffer_size_in_bytes number | string Required

Add an index block Added in 7.9.0

Delete a query rule Added in 8.15.0

Search rolled-up data Deprecated Technical preview

Body Required

total object | number

_score number | string | null

matched_queries array[string] | object

max_score number | string | null