Create or update an autoscaling policy Generally available; Added in 7.11.0

PUT /_autoscaling/policy/{name}

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

External documentation

Path parameters

name string Required

the name of the autoscaling policy

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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

Values are -1 or 0.

application/json

Body Required

roles array[string] Required
deciders object Required

Decider settings.

External documentation
Hide deciders attribute Show deciders attribute object
- * object Additional properties

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.

PUT /_autoscaling/policy/{name}

PUT /_autoscaling/policy/<name>
{
  "roles": [],
  "deciders": {
    "fixed": {
    }
  }
}

resp = client.autoscaling.put_autoscaling_policy(
    name="<name>",
    policy={
        "roles": [],
        "deciders": {
            "fixed": {}
        }
    },
)

const response = await client.autoscaling.putAutoscalingPolicy({
  name: "<name>",
  policy: {
    roles: [],
    deciders: {
      fixed: {},
    },
  },
});

response = client.autoscaling.put_autoscaling_policy(
  name: "<name>",
  body: {
    "roles": [],
    "deciders": {
      "fixed": {}
    }
  }
)

$resp = $client->autoscaling()->putAutoscalingPolicy([
    "name" => "<name>",
    "body" => [
        "roles" => array(
        ),
        "deciders" => [
            "fixed" => new ArrayObject([]),
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"roles":[],"deciders":{"fixed":{}}}' "$ELASTICSEARCH_URL/_autoscaling/policy/<name>"

client.autoscaling().putAutoscalingPolicy(p -> p
    .name("<name>")
    .policy(po -> po
        .deciders("fixed", JsonData.fromJson("{}"))
    )
);

Request examples

{
  "roles": [],
  "deciders": {
    "fixed": {
    }
  }
}

The API method and path for this request: `PUT /_autoscaling/policy/my_autoscaling_policy`. It creates `my_autoscaling_policy` using the fixed autoscaling decider, applying to the set of nodes having (only) the `data_hot` role.

{
  "roles" : [ "data_hot" ],
  "deciders": {
    "fixed": {
    }
  }
}

Response examples (200)

{
  "acknowledged": true
}

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 aliases Generally available

GET /_cat/aliases/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/aliases

GET /_cat/aliases/{name}

Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.

Required authorization

Index privileges: view_index_metadata

Path parameters

name string | array[string]

A comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
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.

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 are all, open, closed, hidden, or none.
master_timeout string

The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicated that the request should never timeout, you can set it to -1.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- alias string
  
  alias name
- index string
- filter string
  
  filter
- routing.index string
  
  index routing
- routing.search string
  
  search routing
- is_write_index string
  
  write index

GET /_cat/aliases/{name}

GET _cat/aliases?format=json&v=true

resp = client.cat.aliases(
    format="json",
    v=True,
)

const response = await client.cat.aliases({
  format: "json",
  v: "true",
});

response = client.cat.aliases(
  format: "json",
  v: "true"
)

$resp = $client->cat()->aliases([
    "format" => "json",
    "v" => "true",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/aliases?format=json&v=true"

client.cat().aliases();

Response examples (200)

A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations.

[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]

Get component templates Generally available; Added in 5.1.0

GET /_cat/component_templates/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/component_templates

GET /_cat/component_templates/{name}

Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get component template API.

Required authorization

Cluster privileges: monitor

Path parameters

name string Required

The name of the component template. It accepts wildcard expressions. If it is omitted, all component templates are returned.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local boolean

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

The period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string Required
- version string | null Required
  
  One of:
  string-1 string string-2 string | null
- alias_count string Required
- mapping_count string Required
- settings_count string Required
- metadata_count string Required
- included_in string Required

GET /_cat/component_templates/{name}

GET _cat/component_templates/my-template-*?v=true&s=name&format=json

resp = client.cat.component_templates(
    name="my-template-*",
    v=True,
    s="name",
    format="json",
)

const response = await client.cat.componentTemplates({
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json",
});

response = client.cat.component_templates(
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json"
)

$resp = $client->cat()->componentTemplates([
    "name" => "my-template-*",
    "v" => "true",
    "s" => "name",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/component_templates/my-template-*?v=true&s=name&format=json"

client.cat().componentTemplates();

Response examples (200)

A successful response from `GET _cat/component_templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "name": "my-template-1",
    "version": "null",
    "alias_count": "0",
    "mapping_count": "0",
    "settings_count": "1",
    "metadata_count": "0",
    "included_in": "[my-index-template]"
  },
    {
    "name": "my-template-2",
    "version": null,
    "alias_count": "0",
    "mapping_count": "3",
    "settings_count": "0",
    "metadata_count": "0",
    "included_in": "[my-index-template]"
  }
]

Get a document count Generally available

GET /_cat/count/{index}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/count

GET /_cat/count/{index}

Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the count API.

Required authorization

Index privileges: read

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases used to limit the request. It supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

Responses

200 application/json
Hide response attributes Show response attributes object
- epoch number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  UnitSeconds number string-2 string
  
  Time unit for seconds
- timestamp string
  
  Time of day, expressed as HH:MM:SS
- count string
  
  the document count

GET /_cat/count/{index}

GET /_cat/count/my-index-000001?v=true&format=json

resp = client.cat.count(
    index="my-index-000001",
    v=True,
    format="json",
)

const response = await client.cat.count({
  index: "my-index-000001",
  v: "true",
  format: "json",
});

response = client.cat.count(
  index: "my-index-000001",
  v: "true",
  format: "json"
)

$resp = $client->cat()->count([
    "index" => "my-index-000001",
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/count/my-index-000001?v=true&format=json"

client.cat().count();

Response examples (200)

A successful response from `GET /_cat/count/my-index-000001?v=true&format=json`. It retrieves the document count for the `my-index-000001` data stream or index.

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "120"
  }
]

A successful response from `GET /_cat/count?v=true&format=json`. It retrieves the document count for all data streams and indices in the cluster.

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "121"
  }
]

Get index template information Generally available; Added in 5.2.0

GET /_cat/templates/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cat/templates

GET /_cat/templates/{name}

Get information about the index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the get index template API.

Required authorization

Cluster privileges: monitor

Path parameters

name string Required

The name of the template to return. Accepts wildcard expressions. If omitted, all templates are returned.

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local boolean

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string
- index_patterns string
  
  The template index patterns.
- order string
  
  The template application order or priority number.
- version string | null
  
  The template version.
  
  One of:
  VersionString string string-2 string | null
- composed_of string
  
  The component templates that comprise the index template.

GET /_cat/templates/{name}

GET _cat/templates/my-template-*?v=true&s=name&format=json

resp = client.cat.templates(
    name="my-template-*",
    v=True,
    s="name",
    format="json",
)

const response = await client.cat.templates({
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json",
});

response = client.cat.templates(
  name: "my-template-*",
  v: "true",
  s: "name",
  format: "json"
)

$resp = $client->cat()->templates([
    "name" => "my-template-*",
    "v" => "true",
    "s" => "name",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/templates/my-template-*?v=true&s=name&format=json"

client.cat().templates();

Response examples (200)

A successful response from `GET _cat/templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "name": "my-template-0",
    "index_patterns": "[te*]",
    "order": "500",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-1",
    "index_patterns": "[tea*]",
    "order": "501",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-2",
    "index_patterns": "[teak*]",
    "order": "502",
    "version": "7",
    "composed_of": "[]"
  }
]

Update the cluster settings Generally available

PUT /_cluster/settings

Api key auth Basic auth Bearer auth

Configure and update dynamic settings on a running cluster. You can also configure dynamic settings locally on an unstarted or shut down node in elasticsearch.yml.

Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a null value.

If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) elasticsearch.yml setting; 4) Default setting value. For example, you can apply a transient setting to override a persistent setting or elasticsearch.yml setting. However, a change to an elasticsearch.yml setting will not override a defined transient or persistent setting.

TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster. If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings. Only use elasticsearch.yml for static cluster settings and node settings. The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.

WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.

External documentation

Query parameters

flat_settings boolean

Return settings in flat format (default: false)
master_timeout string

Explicit operation timeout for connection to master node

Values are -1 or 0.
timeout string

Explicit operation timeout

Values are -1 or 0.

application/json

Body Required

persistent object

The settings that persist after the cluster restarts.
Hide persistent attribute Show persistent attribute object
- * object Additional properties
transient object

The settings that do not persist after the cluster restarts.
Hide transient attribute Show transient attribute object
- * object Additional properties

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- persistent object Required
  
  Hide persistent attribute Show persistent attribute object
  
  * object Additional properties
- transient object Required
  
  Hide transient attribute Show transient attribute object
  
  * object Additional properties

PUT /_cluster/settings

PUT /_cluster/settings
{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}

resp = client.cluster.put_settings(
    persistent={
        "indices.recovery.max_bytes_per_sec": "50mb"
    },
)

const response = await client.cluster.putSettings({
  persistent: {
    "indices.recovery.max_bytes_per_sec": "50mb",
  },
});

response = client.cluster.put_settings(
  body: {
    "persistent": {
      "indices.recovery.max_bytes_per_sec": "50mb"
    }
  }
)

$resp = $client->cluster()->putSettings([
    "body" => [
        "persistent" => [
            "indices.recovery.max_bytes_per_sec" => "50mb",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"persistent":{"indices.recovery.max_bytes_per_sec":"50mb"}}' "$ELASTICSEARCH_URL/_cluster/settings"

client.cluster().putSettings(p -> p
    .persistent("indices.recovery.max_bytes_per_sec", JsonData.fromJson("\"50mb\""))
);

Request examples

An example of a persistent update.

{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}

PUT `/_cluster/settings` to update the `action.auto_create_index` setting. The setting accepts a comma-separated list of patterns that you want to allow or you can prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. In this example, the auto-creation of indices called `my-index-000001` or `index10` is allowed, the creation of indices that match the pattern `index1*` is blocked, and the creation of any other indices that match the `ind*` pattern is allowed. Patterns are matched in the order specified.

{
  "persistent": {
    "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*" 
  }
}

Get the cluster health Generally available; Added in 8.7.0

GET /_health_report/{feature}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_health_report

GET /_health_report/{feature}

Get a report with the health status of an Elasticsearch cluster. The report contains a list of indicators that compose Elasticsearch functionality.

Each indicator has a health status of: green, unknown, yellow or red. The indicator will provide an explanation and metadata describing the reason for its current health status.

The cluster’s status is controlled by the worst indicator status.

In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.

Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. The root cause and remediation steps are encapsulated in a diagnosis. A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.

NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.

Path parameters

feature string | array[string] Required

A feature of the cluster, as returned by the top-level health report API.

Query parameters

timeout string

Explicit operation timeout.

Values are -1 or 0.
verbose boolean

Opt-in for more information about the health of the system.
size number

Limit the number of affected resources the health report API returns.

Responses

200 application/json
Hide response attributes Show response attributes object
- cluster_name string Required
- indicators object Required
  
  Hide indicators attributes Show indicators attributes object
  
  master_is_stable object
  
  MASTER_IS_STABLE
  
  Hide master_is_stable attributes Show master_is_stable attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  current_master object Required
  
  Hide current_master attributes Show current_master attributes object
  
  name
  
  node_id
  
  recent_masters array[object] Required
  
  exception_fetching_history object
  
  Hide exception_fetching_history attributes Show exception_fetching_history attributes object
  
  message string Required
  
  stack_trace string Required
  
  cluster_formation array[object]
  
  shards_availability object
  
  SHARDS_AVAILABILITY
  
  Hide shards_availability attributes Show shards_availability attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  creating_primaries number Required
  
  creating_replicas number Required
  
  initializing_primaries number Required
  
  initializing_replicas number Required
  
  restarting_primaries number Required
  
  restarting_replicas number Required
  
  started_primaries number Required
  
  started_replicas number Required
  
  unassigned_primaries number Required
  
  unassigned_replicas number Required
  
  disk object
  
  DISK
  
  Hide disk attributes Show disk attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  indices_with_readonly_block number Required
  
  nodes_with_enough_disk_space number Required
  
  nodes_over_high_watermark number Required
  
  nodes_over_flood_stage_watermark number Required
  
  nodes_with_unknown_disk_status number Required
  
  repository_integrity object
  
  REPOSITORY_INTEGRITY
  
  Hide repository_integrity attributes Show repository_integrity attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  total_repositories number
  
  corrupted_repositories number
  
  corrupted array[string]
  
  data_stream_lifecycle object
  
  DATA_STREAM_LIFECYCLE
  
  Hide data_stream_lifecycle attributes Show data_stream_lifecycle attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  stagnating_backing_indices_count number Required
  
  total_backing_indices_in_error number Required
  
  stagnating_backing_indices array[object]
  
  ilm object
  
  ILM
  
  Hide ilm attributes Show ilm attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  ilm_status string Required
  
  Values are RUNNING, STOPPING, or STOPPED.
  
  policies number Required
  
  stagnating_indices number Required
  
  slm object
  
  SLM
  
  Hide slm attributes Show slm attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  slm_status string Required
  
  Values are RUNNING, STOPPING, or STOPPED.
  
  policies number Required
  
  unhealthy_policies object
  
  Hide unhealthy_policies attributes Show unhealthy_policies attributes object
  
  count number Required
  
  invocations_since_last_success object
  
  shards_capacity object
  
  SHARDS_CAPACITY
  
  Hide shards_capacity attributes Show shards_capacity attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  data object Required
  
  Hide data attributes Show data attributes object
  
  max_shards_in_cluster number Required
  
  current_used_shards number
  
  frozen object Required
  
  Hide frozen attributes Show frozen attributes object
  
  max_shards_in_cluster number Required
  
  current_used_shards number
  
  file_settings object
  
  FILE_SETTINGS
  
  Hide file_settings attributes Show file_settings attributes object
  
  status string Required
  
  Values are green, yellow, red, unknown, or unavailable.
  
  symptom string Required
  
  impacts array[object]
  
  Hide impacts attributes Show impacts attributes object
  
  description string Required
  
  id string Required
  
  impact_areas array[string] Required
  
  Values are search, ingest, backup, or deployment_management.
  
  severity number Required
  
  diagnosis array[object]
  
  Hide diagnosis attributes Show diagnosis attributes object
  
  id string Required
  
  action string Required
  
  affected_resources object Required
  
  cause string Required
  
  help_url string Required
  
  details object
  
  Hide details attributes Show details attributes object
  
  failure_streak number Required
  
  most_recent_failure string Required
- status string
  
  Values are green, yellow, red, unknown, or unavailable.

GET /_health_report/{feature}

GET _health_report

resp = client.health_report()

const response = await client.healthReport();

response = client.health_report

$resp = $client->healthReport();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_health_report"

client.healthReport(h -> h);

Claim a connector sync job Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_claim

Api key auth Basic auth Bearer auth

This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. Additionally, it can set the sync_cursor property for the sync job.

This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.

To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job.

application/json

Body Required

sync_cursor object

The cursor object from the last incremental sync job. This should reference the sync_cursor field in the connector state for which the job runs.
worker_hostname string Required

The host name of the current system that will run the job.

Responses

200 application/json

PUT /_connector/_sync_job/{connector_sync_job_id}/_claim

PUT _connector/_sync_job/my-connector-sync-job-id/_claim
{
  "worker_hostname": "some-machine"
}

resp = client.connector.sync_job_claim(
    connector_sync_job_id="my-connector-sync-job-id",
    worker_hostname="some-machine",
)

const response = await client.connector.syncJobClaim({
  connector_sync_job_id: "my-connector-sync-job-id",
  worker_hostname: "some-machine",
});

response = client.connector.sync_job_claim(
  connector_sync_job_id: "my-connector-sync-job-id",
  body: {
    "worker_hostname": "some-machine"
  }
)

$resp = $client->connector()->syncJobClaim([
    "connector_sync_job_id" => "my-connector-sync-job-id",
    "body" => [
        "worker_hostname" => "some-machine",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"worker_hostname":"some-machine"}' "$ELASTICSEARCH_URL/_connector/_sync_job/my-connector-sync-job-id/_claim"

client.connector().syncJobClaim(s -> s
    .connectorSyncJobId("my-connector-sync-job-id")
    .workerHostname("some-machine")
);

Request example

An example body for a `PUT _connector/_sync_job/my-connector-sync-job-id/_claim` request.

{
  "worker_hostname": "some-machine"
}

Update the connector API key ID Beta; Added in 8.12.0

PUT /_connector/{connector_id}/_api_key_id

Api key auth Basic auth Bearer auth

Update the api_key_id and api_key_secret_id fields of a connector. You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored. The connector secret ID is required only for Elastic managed (native) connectors. Self-managed connectors (connector clients) do not use this field.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

api_key_id string
api_key_secret_id string

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_api_key_id

PUT _connector/my-connector/_api_key_id
{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

resp = client.connector.update_api_key_id(
    connector_id="my-connector",
    api_key_id="my-api-key-id",
    api_key_secret_id="my-connector-secret-id",
)

const response = await client.connector.updateApiKeyId({
  connector_id: "my-connector",
  api_key_id: "my-api-key-id",
  api_key_secret_id: "my-connector-secret-id",
});

response = client.connector.update_api_key_id(
  connector_id: "my-connector",
  body: {
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
  }
)

$resp = $client->connector()->updateApiKeyId([
    "connector_id" => "my-connector",
    "body" => [
        "api_key_id" => "my-api-key-id",
        "api_key_secret_id" => "my-connector-secret-id",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"api_key_id":"my-api-key-id","api_key_secret_id":"my-connector-secret-id"}' "$ELASTICSEARCH_URL/_connector/my-connector/_api_key_id"

client.connector().updateApiKeyId(u -> u
    .apiKeyId("my-api-key-id")
    .apiKeySecretId("my-connector-secret-id")
    .connectorId("my-connector")
);

Request example

{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

Response examples (200)

{
  "result": "updated"
}

Update data stream settings Generally available; Added in 9.1.0

PUT /_data_stream/{name}/_settings

Api key auth Basic auth Bearer auth

This API can be used to override settings on specific data streams. These overrides will take precedence over what is specified in the template that the data stream matches. To prevent your data stream from getting into an invalid state, only certain settings are allowed. If possible, the setting change is applied to all backing indices. Otherwise, it will be applied when the data stream is next rolled over.

Required authorization

Index privileges: manage

Path parameters

name string | array[string] Required

A comma-separated list of data streams or data stream patterns.

Query parameters

dry_run boolean

If true, the request does not actually change the settings on any data streams or indices. Instead, it simulates changing the settings and reports back to the user what would have happened had these settings actually been applied.
master_timeout string

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

Values are -1 or 0.
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.

Values are -1 or 0.

application/json

Body Required

object

Index settings

Responses

200 application/json
Hide response attribute Show response attribute object
- data_streams array[object] Required
  
  Hide data_streams attributes Show data_streams attributes object
  
  name string Required
  
  applied_to_data_stream boolean Required
  
  If the settings were successfully applied to the data stream (or would have been, if running in dry_run mode), it is true. If an error occurred, it is false.
  
  error string
  
  A message explaining why the settings could not be applied to the data stream.
  
  settings object Required
  Index settings
  
  effective_settings object Required
  Index settings
  
  index_settings_results object Required
  
  Hide index_settings_results attributes Show index_settings_results attributes object
  
  applied_to_data_stream_only array[string] Required
  
  The list of settings that were applied to the data stream but not to backing indices. These will be applied to the write index the next time the data stream is rolled over.
  
  applied_to_data_stream_and_backing_indices array[string] Required
  
  The list of settings that were applied to the data stream and to all of its backing indices. These settings will also be applied to the write index the next time the data stream is rolled over.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  index string Required
  
  error string Required
  
  A message explaining why the settings could not be applied to specific indices.

PUT /_data_stream/{name}/_settings

PUT /_data_stream/my-data-stream/_settings
{
  "index.lifecycle.name" : "new-test-policy",
  "index.number_of_shards": 11
}

resp = client.indices.put_data_stream_settings(
    name="my-data-stream",
    settings={
        "index.lifecycle.name": "new-test-policy",
        "index.number_of_shards": 11
    },
)

const response = await client.indices.putDataStreamSettings({
  name: "my-data-stream",
  settings: {
    "index.lifecycle.name": "new-test-policy",
    "index.number_of_shards": 11,
  },
});

response = client.indices.put_data_stream_settings(
  name: "my-data-stream",
  body: {
    "index.lifecycle.name": "new-test-policy",
    "index.number_of_shards": 11
  }
)

$resp = $client->indices()->putDataStreamSettings([
    "name" => "my-data-stream",
    "body" => [
        "index.lifecycle.name" => "new-test-policy",
        "index.number_of_shards" => 11,
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index.lifecycle.name":"new-test-policy","index.number_of_shards":11}' "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_settings"

Request example

This is a request to change two settings on a data stream.

{
  "index.lifecycle.name" : "new-test-policy",
  "index.number_of_shards": 11
}

Response examples (200)

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when two settings are successfully updated on the data stream. In this case, `index.number_of_shards` is only applied to the data stream -- it will be applied to the write index on rollover. The setting `index.lifecycle.name` is applied to the data stream and all backing indices.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      },
      "index_settings_results": {
        "applied_to_data_stream_only": [
          "index.number_of_shards"
        ],
        "applied_to_data_stream_and_backing_indices": [
          "index.lifecycle.name"
        ]
      }
    }
  ]
}

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a setting is successfully applied to the data stream, but one of the backing indices, `.ds-my-data-stream-2025.05.28-000001`, has a write block. The response reports that the setting was not successfully applied to that index.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "number_of_shards": "11"
        }
      },
      "effective_settings": {
        "index": {
          "lifecycle": {
            "name": "new-test-policy"
          },
          "mode": "standard",
          "number_of_shards": "11",
          "number_of_replicas": "0"
        }
      },
      "index_settings_results": {
        "applied_to_data_stream_only": [
          "index.number_of_shards"
        ],
        "applied_to_data_stream_and_backing_indices": [
          "index.lifecycle.name"
        ],
        "errors": [
          {
            "index": ".ds-my-data-stream-2025.05.28-000001",
            "error": "index [.ds-my-data-stream-2025.05.28-000001] blocked by: [FORBIDDEN/9/index metadata (api)];"
          }
        ]
      }
    }
  ]
}

This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a user attempts to set a setting that is not allowed on a data stream. As a result, no change was applied to the data stream.

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": false,
      "error": "Cannot set the following settings on a data stream: [index.number_of_replicas]",
      "settings": {},
      "effective_settings": {},
      "index_settings_results": {
        "applied_to_data_stream_only": [],
        "applied_to_data_stream_and_backing_indices": []
      }
    }
  ]
}

Promote a data stream Generally available; Added in 7.9.0

POST /_data_stream/_promote/{name}

Api key auth Basic auth Bearer auth

Promote a data stream from a replicated data stream managed by cross-cluster replication (CCR) to a regular data stream.

With CCR auto following, a data stream from a remote cluster can be replicated to the local cluster. These data streams can't be rolled over in the local cluster. These replicated data streams roll over only if the upstream data stream rolls over. In the event that the remote cluster is no longer available, the data stream in the local cluster can be promoted to a regular data stream, which allows these data streams to be rolled over in the local cluster.

NOTE: When promoting a data stream, ensure the local cluster has a data stream enabled index template that matches the data stream. If this is missing, the data stream will not be able to roll over until a matching index template is created. This will affect the lifecycle management of the data stream and interfere with the data stream size and retention.

Path parameters

name string Required

The name of the data stream

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json

POST /_data_stream/_promote/{name}

POST /_data_stream/_promote/my-data-stream

resp = client.indices.promote_data_stream(
    name="my-data-stream",
)

const response = await client.indices.promoteDataStream({
  name: "my-data-stream",
});

response = client.indices.promote_data_stream(
  name: "my-data-stream"
)

$resp = $client->indices()->promoteDataStream([
    "name" => "my-data-stream",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/_promote/my-data-stream"

client.indices().promoteDataStream(p -> p
    .name("my-data-stream")
);

Create or update a document in an index Generally available

POST /{index}/_doc/{id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

POST /{index}/_doc

PUT /{index}/_doc/{id}

POST /{index}/_doc/{id}

Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.

NOTE: You cannot use this API to send update requests for existing documents in a data stream.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:

To add or overwrite a document using the PUT /<target>/_doc/<_id> request format, you must have the create, index, or write index privilege.
To add a document using the POST /<target>/_doc/ request format, you must have the create_doc, create, index, or write index privilege.
To automatically create a data stream or index with this API request, you must have the auto_configure, create_index, or manage index privilege.

Automatic data stream creation requires a matching index template with data stream enabled.

NOTE: Replica shards might not all be started when an indexing operation returns successfully. By default, only the primary is required. Set wait_for_active_shards to change this default behavior.

Automatically create data streams and indices

If the request's target doesn't exist and matches an index template with a data_stream definition, the index operation automatically creates the data stream.

If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.

NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.

If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.

Automatic index creation is controlled by the action.auto_create_index setting. If it is true, any index can be created automatically. You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false to turn off automatic index creation entirely. Specify a comma-separated list of patterns you want to allow or prefix each pattern with + or - to indicate whether it should be allowed or blocked. When a list is specified, the default behaviour is to disallow.

NOTE: The action.auto_create_index setting affects the automatic creation of indices only. It does not affect the creation of data streams.

Optimistic concurrency control

Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no and if_primary_term parameters. If a mismatch is detected, the operation will result in a VersionConflictException and a status code of 409.

Routing

By default, shard placement — or routing — is controlled by using a hash of the document's ID value. For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing parameter.

When setting up explicit mapping, you can also use the _routing field to direct the index operation to extract the routing value from the document itself. This does come at the (very minimal) cost of an additional document parsing pass. If the _routing mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.

NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing setting enabled in the template.

Distributed

The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.

Active shards

To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation. If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs. By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards is 1). This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards. To alter this behavior per operation, use the wait_for_active_shards request parameter.

Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas+1). Specifying a negative value or a number greater than the number of shard copies will throw an error.

For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes). If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding. This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data. If wait_for_active_shards is set on the request to 3 (and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding. This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard. However, if you set wait_for_active_shards to all (or to 4, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index. The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.

It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts. After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary. The _shards section of the API response reveals the number of shard copies on which replication succeeded and failed.

No operation (noop) updates

When updating a document by using this API, a new version of the document is always created even if the document hasn't changed. If this isn't acceptable use the _update API with detect_noop set to true. The detect_noop option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.

There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.

Versioning

Each indexed document is given a version number. By default, internal versioning is used that starts at 1 and increments with each update, deletes included. Optionally, the version number can be set to an external value (for example, if maintained in a database). To enable this functionality, version_type should be set to external. The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18.

NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks.

When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:

PUT my-index-000001/_doc/1?version=2&version_type=external
{
  "user": {
    "id": "elkbee"
  }
}

In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).

A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.

## Required authorization

* Index privileges: `index`

External documentation

Path parameters

index string Required

The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (*) pattern of an index template with a data_stream definition, this request creates the data stream. If the target doesn't exist and doesn't match a data stream template, this request creates the index. You can check for existing targets with the resolve index API.
id string Required

A unique identifier for the document. To automatically generate a document ID, use the POST /<target>/_doc/ request format and omit this parameter.

Query parameters

if_primary_term number

Only perform the operation if the document has this primary term.
if_seq_no number

Only perform the operation if the document has this sequence number.
include_source_on_error boolean

True or false if to include the document source in the error message in case of parsing errors.
op_type string
Set to create to only index the document if it does not already exist (put if absent). If a document with the specified _id already exists, the indexing operation will fail. The behavior is the same as using the <index>/_create endpoint. If a document ID is specified, this paramater defaults to index. Otherwise, it defaults to create. If the request targets a data stream, an op_type of create is required.

Supported values include:
- index: Overwrite any documents that already exist.
- create: Only index documents that do not already exist.
Values are index or create.
pipeline string

The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to _none disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.
refresh string

If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

Values are true, false, or wait_for.
routing string

A custom value that is used to route operations to a specific shard.
timeout string

The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.

This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.

Values are -1 or 0.
version number

An explicit version number for concurrency control. It must be a non-negative long number.
version_type string
The version type.

Supported values include:
- internal: Use internal versioning that starts at 1 and increments with each update or delete.
- external: Only index the document if the specified version is strictly higher than the version of the stored document or if there is no existing document.
- external_gte: Only index the document if the specified version is equal or higher than the version of the stored document or if there is no existing document. NOTE: The external_gte version type is meant for special use cases and should be used with care. If used incorrectly, it can result in loss of data.
- force: This option is deprecated because it can cause primary and replica shards to diverge.
Values are internal, external, external_gte, or force.
wait_for_active_shards number | string

The number of shard copies that must be active before proceeding with the operation. You can set it to all or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.

Values are all or index-setting.
require_alias boolean

If true, the destination must be an index alias.
require_data_stream boolean

If true, the request's actions must target a data stream (existing or to be created).

application/json

Body Required

object

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- _index string Required
- _primary_term number
  
  The primary term assigned to the document for the indexing operation.
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- _seq_no number
- _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
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number
- _version number Required
- forced_refresh boolean

POST /{index}/_doc/{id}

POST my-index-000001/_doc/
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

resp = client.index(
    index="my-index-000001",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)

const response = await client.index({
  index: "my-index-000001",
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});

response = client.index(
  index: "my-index-000001",
  body: {
    "@timestamp": "2099-11-15T13:12:00",
    "message": "GET /search HTTP/1.1 200 1070000",
    "user": {
      "id": "kimchy"
    }
  }
)

$resp = $client->index([
    "index" => "my-index-000001",
    "body" => [
        "@timestamp" => "2099-11-15T13:12:00",
        "message" => "GET /search HTTP/1.1 200 1070000",
        "user" => [
            "id" => "kimchy",
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"@timestamp":"2099-11-15T13:12:00","message":"GET /search HTTP/1.1 200 1070000","user":{"id":"kimchy"}}' "$ELASTICSEARCH_URL/my-index-000001/_doc/"

client.index(i -> i
    .index("my-index-000001")
    .document(JsonData.fromJson("{\"@timestamp\":\"2099-11-15T13:12:00\",\"message\":\"GET /search HTTP/1.1 200 1070000\",\"user\":{\"id\":\"kimchy\"}}"))
);

Request examples

Run `POST my-index-000001/_doc/` to index a document. When you use the `POST /<target>/_doc/` request format, the `op_type` is automatically set to `create` and the index operation generates a unique ID for the document.

{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

Run `PUT my-index-000001/_doc/1` to insert a JSON document into the `my-index-000001` index with an `_id` of 1.

{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

Response examples (200)

A successful response from `POST my-index-000001/_doc/`, which contains an automated document ID.

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "W0tpsmIBdwcYyG50zbta",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}

A successful response from `PUT my-index-000001/_doc/1`.

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}

Get EQL search results Generally available; Added in 7.9.0

POST /{index}/_eql/search

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /{index}/_eql/search

POST /{index}/_eql/search

Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

External documentation

Path parameters

index string | array[string] Required

The name of the index to scope the operation

Query parameters

allow_no_indices boolean

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
allow_partial_search_results boolean

If true, returns partial results if there are shard failures. If false, returns an error with no partial results.
allow_partial_sequence_results boolean

If true, sequence queries will return partial results in case of shard failures. If false, they will return no results at all. This flag has effect only if allow_partial_search_results is true.
expand_wildcards string | array[string]
Whether to expand wildcard expression to concrete indices that are open, closed or both.

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 are all, open, closed, hidden, or none.
ccs_minimize_roundtrips boolean

Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
keep_alive string

Period for which the search and its results are stored on the cluster.

Values are -1 or 0.
keep_on_completion boolean

If true, the search and its results are stored on the cluster.
wait_for_completion_timeout string

Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.

Values are -1 or 0.

application/json

Body Required

query string Required

EQL query you wish to run.
case_sensitive boolean
event_category_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
tiebreaker_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
timestamp_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
fetch_size number
filter object | array[object]

Query, written in Query DSL, used to filter the events on which the EQL query runs.

One of:
QueryContainer object array-2 array[object]

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

External documentation
keep_alive 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.
keep_on_completion boolean
wait_for_completion_timeout 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.
allow_partial_search_results boolean

Allow query execution also in case of shard failures. If true, the query will keep running and will return results based on the available shards. For sequences, the behavior can be further refined using allow_partial_sequence_results

Default value is true.
allow_partial_sequence_results boolean

This flag applies only to sequences and has effect only if allow_partial_search_results=true. If true, the sequence query will return results based on the available shards, ignoring the others. If false, the sequence query will return successfully, but will always have empty results.

Default value is false.
size number
fields object | array[object]

Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.
One of:
FieldAndFormat object array-2 array[object]
A reference to a field with formatting instructions on how to return the value
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean
A reference to a field with formatting instructions on how to return the value
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean
result_position string

Values are tail or head.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from number
  
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  
  Default value is 0.
  
  highlight object
  
  track_total_hits boolean | number
  
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  External documentation
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  
  A reference to a field with formatting instructions on how to return the value
  
  External documentation
  
  A reference to a field with formatting instructions on how to return the value
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  rescorer
  
  linear
  
  pinned
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  
  Default value is 10.
  
  slice object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  fields array[object]
  
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  
  A reference to a field with formatting instructions on how to return the value
  
  A reference to a field with formatting instructions on how to return the value
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  terminate_after number
  
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive 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.
  
  runtime_mappings object
  
  stats array[string]
  
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
max_samples_per_key number

By default, the response of a sample query contains up to 10 samples, with one sample per unique set of join keys. Use the size parameter to get a smaller or larger set of samples. To retrieve more than one sample per set of join keys, use the max_samples_per_key parameter. Pipes are not supported for sample queries.

Default value is 1.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- is_partial boolean
  
  If true, the response does not contain complete search results.
- is_running boolean
  
  If true, the search request is still executing.
- took number
  
  Time unit for milliseconds
- timed_out boolean
  
  If true, the request timed out before completion.
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object
  
  Hide total attributes Show total attributes object
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  events array[object]
  
  Contains events matching the query. Each object represents a matching event.
  
  Hide events attributes Show events attributes object
  
  _index string Required
  
  _id string Required
  
  _source object Required
  
  Original JSON body passed for the event at index time.
  
  missing boolean
  
  Set to true for events in a timespan-constrained sequence that do not meet a given condition.
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * array[object] Additional properties
  
  sequences array[object]
  
  Contains event sequences matching the query. Each object represents a matching sequence. This parameter is only returned for EQL queries containing a sequence.
  
  Hide sequences attributes Show sequences attributes object
  
  events array[object] Required
  
  Contains events matching the query. Each object represents a matching event.
  
  Hide events attributes Show events attributes object
  
  _index string Required
  
  _id string Required
  
  _source object Required
  
  Original JSON body passed for the event at index time.
  
  missing boolean
  
  Set to true for events in a timespan-constrained sequence that do not meet a given condition.
  
  fields object
  
  join_keys array[object]
  
  Shared field values used to constrain matches in the sequence. These are defined using the by keyword in the EQL query syntax.
- shard_failures array[object]
  
  Contains information about shard failures (if any), in case allow_partial_search_results=true
  
  Hide shard_failures attributes Show shard_failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string

POST /{index}/_eql/search

GET /my-data-stream/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

resp = client.eql.search(
    index="my-data-stream",
    query="\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
)

const response = await client.eql.search({
  index: "my-data-stream",
  query:
    '\n    process where (process.name == "cmd.exe" and process.pid != 2013)\n  ',
});

response = client.eql.search(
  index: "my-data-stream",
  body: {
    "query": "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "
  }
)

$resp = $client->eql()->search([
    "index" => "my-data-stream",
    "body" => [
        "query" => "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "}' "$ELASTICSEARCH_URL/my-data-stream/_eql/search"

client.eql().search(s -> s
    .index("my-data-stream")
    .query(" process where (process.name == \"cmd.exe\" and process.pid != 2013) ")
);

Request examples

Run `GET /my-data-stream/_eql/search` to search for events that have a `process.name` of `cmd.exe` and a `process.pid` other than `2013`.

{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

Run `GET /my-data-stream/_eql/search` to search for a sequence of events. The sequence starts with an event with an `event.category` of `file`, a `file.name` of `cmd.exe`, and a `process.pid` other than `2013`. It is followed by an event with an `event.category` of `process` and a `process.executable` that contains the substring `regsvr32`. These events must also share the same `process.pid` value.

{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}

Response examples (200)

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "AtOJ4UjUBAAx3XR5kcCM",
            "_source": {
              "@timestamp": "2099-12-06T11:04:07.000Z",
              "event": {
                "category": "file",
                "id": "dGCHwoeS",
                "sequence": 2
              },
              "file": {
                "accessed": "2099-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "pid": 2012,
                "name": "cmd.exe",
                "executable": "C:\\Windows\\System32\\cmd.exe"
              }
            }
          },
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "OQmfCaduce8zoHT93o4H",
            "_source": {
              "@timestamp": "2099-12-07T11:07:09.000Z",
              "event": {
                "category": "process",
                "id": "aR3NWVOs",
                "sequence": 4
              },
              "process": {
                "pid": 2012,
                "name": "regsvr32.exe",
                "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
                "executable": "C:\\Windows\\System32\\regsvr32.exe"
              }
            }
          }
        ]
      }
    ]
  }
}

Run an async ES|QL query Generally available; Added in 8.13.0

POST /_query/async

Api key auth Basic auth Bearer auth

Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.

The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.

Required authorization

Index privileges: read

External documentation

Query parameters

allow_partial_results boolean

If true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. If false, the query will fail if there are any failures.

To override the default behavior, you can set the esql.query.allow_partial_results cluster setting to false.
delimiter string

The character to use between values within a CSV row. It is valid only for the CSV format.
drop_null_columns boolean

Indicates whether columns that are entirely null will be removed from the columns and values portion of the results. If true, the response will include an extra section under the name all_columns which has the name of all the columns.
format string

A short version of the Accept header, e.g. json, yaml.

csv, tsv, and txt formats will return results in a tabular format, excluding other metadata fields from the response.

For async requests, nothing will be returned if the async query doesn't finish within the timeout. The query ID and running status are available in the X-Elasticsearch-Async-Id and X-Elasticsearch-Async-Is-Running HTTP headers of the response, respectively.

Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.

application/json

Body Required

columnar boolean

By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
filter object

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

External documentation
locale string
params array[number | string | boolean | null]

To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
profile boolean

If provided and true the response will include an extra profile object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query.
query string Required

The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
tables object

Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
Hide tables attribute Show tables attribute object
- * object Additional properties
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  integer array[number | array]
  
  One of:
  number-1 number array-2 array[number]
  
  keyword array[string | array]
  
  One of:
  string-1 string array-2 array[string]
  
  long array[number | array]
  
  One of:
  number-1 number array-2 array[number]
  
  double array[number | array]
  
  One of:
  number-1 number array-2 array[number]
include_ccs_metadata boolean

When set to true and performing a cross-cluster query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.

Default value is false.
wait_for_completion_timeout 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.
keep_alive 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.
keep_on_completion boolean

Indicates whether the query and its results are stored in the cluster. If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.

Default value is false.

Responses

200 application/json
Hide response attributes Show response attributes object
- Time unit for milliseconds
- is_partial boolean
- all_columns array[object]
  
  Hide all_columns attributes Show all_columns attributes object
  
  name string Required
  
  type string Required
- columns array[object] Required
  
  Hide columns attributes Show columns attributes object
  
  name string Required
  
  type string Required
- values array[array] Required
  
  A field value.
  
  A field value.
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  total number Required
  
  successful number Required
  
  running number Required
  
  skipped number Required
  
  partial number Required
  
  failed number Required
  
  details object Required
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  Time unit for milliseconds
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  total number Required
  
  successful number
  
  skipped number
  
  failed number
  
  failures array[object]
- profile object
  
  Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.
- id string
  
  The ID of the async query, to be used in subsequent requests to check the status or retrieve results.
  
  Also available in the X-Elasticsearch-Async-Id HTTP header.
- is_running boolean Required
  
  Indicates whether the async query is still running or has completed.
  
  Also available in the X-Elasticsearch-Async-Is-Running HTTP header.

POST /_query/async

POST /_query/async
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}

resp = client.esql.async_query(
    query="\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    wait_for_completion_timeout="2s",
    include_ccs_metadata=True,
)

const response = await client.esql.asyncQuery({
  query:
    "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
  wait_for_completion_timeout: "2s",
  include_ccs_metadata: true,
});

response = client.esql.async_query(
  body: {
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "wait_for_completion_timeout": "2s",
    "include_ccs_metadata": true
  }
)

$resp = $client->esql()->asyncQuery([
    "body" => [
        "query" => "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
        "wait_for_completion_timeout" => "2s",
        "include_ccs_metadata" => true,
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ","wait_for_completion_timeout":"2s","include_ccs_metadata":true}' "$ELASTICSEARCH_URL/_query/async"

Request example

{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}

Get the features Generally available; Added in 7.12.0

GET /_features

Api key auth Basic auth Bearer auth

Get a list of features that can be included in snapshots using the feature_states field when creating a snapshot. You can use this API to determine which feature states to include when taking a snapshot. By default, all feature states are included in a snapshot if that snapshot includes the global state, or none if it does not.

A feature state includes one or more system indices necessary for a given feature to function. In order to ensure data integrity, all system indices that comprise a feature state are snapshotted and restored together.

The features listed by this API are a combination of built-in features and features defined by plugins. In order for a feature state to be listed in this API and recognized as a valid feature state by the create snapshot API, the plugin that defines that feature must be installed on the master node.

External documentation

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- features array[object] Required
  
  Hide features attributes Show features attributes object
  
  name string Required
  
  description string Required

GET /_features

GET _features

resp = client.features.get_features()

const response = await client.features.getFeatures();

response = client.features.get_features

$resp = $client->features()->getFeatures();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_features"

client.features().getFeatures(g -> g);

Response examples (200)

A successful response for retrieving a list of feature states that can be included when taking a snapshot.

{
  "features": [
    {
      "name": "tasks",
      "description": "Manages task results"
    },
    {
      "name": "kibana",
      "description": "Manages Kibana configuration and reports"
    }
  ]
}

Run multiple Fleet searches Technical preview; Added in 7.16.0

POST /{index}/_fleet/_fleet_msearch

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_fleet/_fleet_msearch

POST /_fleet/_fleet_msearch

GET /{index}/_fleet/_fleet_msearch

POST /{index}/_fleet/_fleet_msearch

Run several Fleet searches with a single API request. The API follows the same structure as the multi search API. However, similar to the Fleet search API, it supports the wait_for_checkpoints parameter.

Required authorization

Index privileges: read

Path parameters

index string Required

A single target to search. If the target is an index alias, it must resolve to a single index.

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.
ccs_minimize_roundtrips boolean

If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
expand_wildcards string | array[string]
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

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 are all, open, closed, hidden, or none.
ignore_throttled boolean

If true, concrete, expanded or aliased indices are ignored when frozen.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
max_concurrent_searches number

Maximum number of concurrent searches the multi search API can execute.
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.
pre_filter_shard_size number

Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
search_type string
Indicates whether global term and document frequencies should be used when scoring returned documents.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_int boolean

If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
typed_keys boolean

Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
wait_for_checkpoints array[number]

A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.
allow_partial_search_results boolean

If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results, which is true by default.

application/json

Body object Required

Contains parameters used to limit or change the subsequent search body request.

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
External documentation
explain boolean

If true, the request returns detailed information about score computation as part of a hit.

Default value is false.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

Default value is 0.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 string-1 string string-2 string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
 
 Default value is .,!? \t\n.
- boundary_max_scan number
 
 How far to scan for boundary characters.
 
 Default value is 20.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 Default value is Locale.ROOT.
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
 
 Default value is 100.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 Default value is 0.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 Default value is 5.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 Default value is 256.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 Default value is true.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object | array[object] Required
 
 One of:
 object-1 object array-2 array[object]
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

A reference to a field with formatting instructions on how to return the value

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

Default value is 3.

from number

Inner hit starting document offset.

Default value is 0.

collapse object
External documentation

docvalue_fields array[object]

A reference to a field with formatting instructions on how to return the value

A reference to a field with formatting instructions on how to return the value

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields array[string]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

sort array[string | object]

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
boolean-1 boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

Default value is false.

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

Default value is 3.

from number

Inner hit starting document offset.

Default value is 0.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields array[string]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

sort

_source

stored_fields string | array[string]

track_scores boolean

Default value is false.

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
post_filter object

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

External documentation
profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.

Default value is false.
query object

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

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
object-2 object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

query_weight number

Relative importance of the original query versus the rescore query.

Default value is 1.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

Default value is 1.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature
Hide attributes Show attributes object

window_size number

query object

learning_to_rank object
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort array[string | object]
  
  collapse object
  External documentation
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
  
  query string
  
  fields array[string]
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string Required
  
  The text snippet used as the basis for similarity comparison
  
  field string Required
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  ruleset_ids string | array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  One of:
  Id string array-2 array[string]
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
- rescorer object
  Hide rescorer attributes Show rescorer attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retriever object Required
  
  rescore array[object] Required
- linear object
  Hide linear attributes Show linear attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retrievers array[object]
  
  Inner retrievers.
  
  rank_window_size number
  
  query string
  
  fields array[string]
  
  normalizer string
  
  Values are none, minmax, or l2_norm.
- pinned object
  Hide pinned attributes Show pinned attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retriever object Required
  
  ids array[string]
  
  docs array[object]
  
  rank_window_size number
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.

Default value is 10.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object array-2 array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
boolean-1 boolean SourceFilter object
Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

A reference to a field with formatting instructions on how to return the value
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.

If set to 0 (default), the query does not terminate early.

Default value is 0.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.

Default value is false.
version boolean

If true, the request returns the document version as part of a hit.

Default value is false.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive 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.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attribute Show response attribute object
- docs array[object] Required
  
  One of:
  object-2 object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  The response returned by Elasticsearch when request execution did not succeed.
  
  Hide attributes Show attributes
  
  error object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  status number Required

POST /{index}/_fleet/_fleet_msearch

curl \
 --request POST 'http://api.example.com/{index}/_fleet/_fleet_msearch' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'

Create or update a component template Generally available; Added in 7.8.0

POST /_component_template/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /_component_template/{name}

POST /_component_template/{name}

Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

An index template can be composed of multiple component templates. To use a component template, specify it in an index template’s composed_of list. Component templates are only applied to new data streams and indices as part of a matching index template.

Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.

Component templates are only used during index creation. For data streams, this includes data stream creation and the creation of a stream’s backing indices. Changes to component templates do not affect existing indices, including a stream’s backing indices.

You can use C-style /* *\/ block comments in component templates. You can include comments anywhere in the request body except before the opening curly bracket.

Applying component templates

You cannot directly apply a component template to a data stream or index. To be applied, a component template must be included in an index template's composed_of list.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string Required

Name of the component template to create. Elasticsearch includes the following built-in component templates: logs-mappings; logs-settings; metrics-mappings; metrics-settings;synthetics-mapping; synthetics-settings. Elastic Agent uses these templates to configure backing indices for its data streams. If you use Elastic Agent and want to overwrite one of these templates, set the version for your replacement template higher than the current version. If you don’t use Elastic Agent and want to disable all built-in component and index templates, set stack.templates.enabled to false using the cluster update settings API.

Query parameters

create boolean

If true, this request cannot replace or update existing component templates.
cause string

User defined reason for create the component template.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

application/json

Body Required

template object Required
Hide template attributes Show template attributes object
- aliases object
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  Default value is false.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  Default value is false.
  
  routing string
  
  search_routing string
- mappings object
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
- settings object
  Index settings
- defaults object
  Index settings
- data_stream string
- lifecycle object
  
  Data stream lifecycle denotes that a data stream is managed by the data stream lifecycle and contains the configuration.
  Hide lifecycle attributes Show lifecycle attributes object
  
  data_retention 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.
  
  downsampling object
  
  Hide downsampling attribute Show downsampling attribute object
  
  rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  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.
  
  config object Required
  
  Hide config attribute Show config attribute object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
  
  enabled boolean
  
  If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.
  
  Default value is true.
version number
_meta object
Hide _meta attribute Show _meta attribute object
- * object Additional properties
deprecated boolean

Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.

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.

POST /_component_template/{name}

PUT _component_template/template_1
{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}

resp = client.cluster.put_component_template(
    name="template_1",
    template=None,
    settings={
        "number_of_shards": 1
    },
    mappings={
        "_source": {
            "enabled": False
        },
        "properties": {
            "host_name": {
                "type": "keyword"
            },
            "created_at": {
                "type": "date",
                "format": "EEE MMM dd HH:mm:ss Z yyyy"
            }
        }
    },
)

const response = await client.cluster.putComponentTemplate({
  name: "template_1",
  template: null,
  settings: {
    number_of_shards: 1,
  },
  mappings: {
    _source: {
      enabled: false,
    },
    properties: {
      host_name: {
        type: "keyword",
      },
      created_at: {
        type: "date",
        format: "EEE MMM dd HH:mm:ss Z yyyy",
      },
    },
  },
});

response = client.cluster.put_component_template(
  name: "template_1",
  body: {
    "template": nil,
    "settings": {
      "number_of_shards": 1
    },
    "mappings": {
      "_source": {
        "enabled": false
      },
      "properties": {
        "host_name": {
          "type": "keyword"
        },
        "created_at": {
          "type": "date",
          "format": "EEE MMM dd HH:mm:ss Z yyyy"
        }
      }
    }
  }
)

$resp = $client->cluster()->putComponentTemplate([
    "name" => "template_1",
    "body" => [
        "template" => null,
        "settings" => [
            "number_of_shards" => 1,
        ],
        "mappings" => [
            "_source" => [
                "enabled" => false,
            ],
            "properties" => [
                "host_name" => [
                    "type" => "keyword",
                ],
                "created_at" => [
                    "type" => "date",
                    "format" => "EEE MMM dd HH:mm:ss Z yyyy",
                ],
            ],
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"template":null,"settings":{"number_of_shards":1},"mappings":{"_source":{"enabled":false},"properties":{"host_name":{"type":"keyword"},"created_at":{"type":"date","format":"EEE MMM dd HH:mm:ss Z yyyy"}}}}' "$ELASTICSEARCH_URL/_component_template/template_1"

Request examples

{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "mappings": {
    "_source": {
      "enabled": false
    },
    "properties": {
      "host_name": {
        "type": "keyword"
      },
      "created_at": {
        "type": "date",
        "format": "EEE MMM dd HH:mm:ss Z yyyy"
      }
    }
  }
}

You can include index aliases in a component template. During index creation, the `{index}` placeholder in the alias name will be replaced with the actual index name that the template gets applied to.

{
  "template": null,
  "settings": {
    "number_of_shards": 1
  },
  "aliases": {
    "alias1": {},
    "alias2": {
      "filter": {
        "term": {
          "user.id": "kimchy"
        }
      },
      "routing": "shard-1"
    },
    "{index}-alias": {}
  }
}

Import a dangling index Generally available; Added in 7.9.0

POST /_dangling/{index_uuid}

Api key auth Basic auth Bearer auth

If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

Required authorization

Cluster privileges: manage

Path parameters

index_uuid string Required

The UUID of the index to import. Use the get dangling indices API to locate the UUID.

Query parameters

accept_data_loss boolean Required

This parameter must be set to true to import a dangling index. Because Elasticsearch cannot know where the dangling index data came from or determine which shard copies are fresh and which are stale, it cannot guarantee that the imported data represents the latest state of the index when it was last in the cluster.
master_timeout string

Specify timeout for connection to master

Values are -1 or 0.
timeout string

Explicit operation timeout

Values are -1 or 0.

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.

POST /_dangling/{index_uuid}

POST /_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true

resp = client.dangling_indices.import_dangling_index(
    index_uuid="zmM4e0JtBkeUjiHD-MihPQ",
    accept_data_loss=True,
)

const response = await client.danglingIndices.importDanglingIndex({
  index_uuid: "zmM4e0JtBkeUjiHD-MihPQ",
  accept_data_loss: "true",
});

response = client.dangling_indices.import_dangling_index(
  index_uuid: "zmM4e0JtBkeUjiHD-MihPQ",
  accept_data_loss: "true"
)

$resp = $client->danglingIndices()->importDanglingIndex([
    "index_uuid" => "zmM4e0JtBkeUjiHD-MihPQ",
    "accept_data_loss" => "true",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true"

client.danglingIndices().importDanglingIndex(i -> i
    .acceptDataLoss(true)
    .indexUuid("zmM4e0JtBkeUjiHD-MihPQ")
);

Response examples (200)

A successful response from `POST /_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true`.

{
  "acknowledged": true
}

Delete data stream lifecycles Generally available; Added in 8.11.0

DELETE /_data_stream/{name}/_lifecycle

Api key auth Basic auth Bearer auth

Removes the data stream lifecycle from a data stream, rendering it not managed by the data stream lifecycle.

External documentation

Path parameters

name string | array[string] Required

A comma-separated list of data streams of which the data stream lifecycle will be deleted; use * to get all data streams

Query parameters

expand_wildcards string | array[string]
Whether wildcard expressions should get expanded to open or closed indices (default: open)

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 are all, open, closed, hidden, or none.
master_timeout string

Specify timeout for connection to master

Values are -1 or 0.
timeout string

Explicit timestamp for the document

Values are -1 or 0.

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 /_data_stream/{name}/_lifecycle

DELETE _data_stream/my-data-stream/_lifecycle

resp = client.indices.delete_data_lifecycle(
    name="my-data-stream",
)

const response = await client.indices.deleteDataLifecycle({
  name: "my-data-stream",
});

response = client.indices.delete_data_lifecycle(
  name: "my-data-stream"
)

$resp = $client->indices()->deleteDataLifecycle([
    "name" => "my-data-stream",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_lifecycle"

client.indices().deleteDataLifecycle(d -> d
    .name("my-data-stream")
);

Response examples (200)

A successful response for deleting a data stream lifecycle.

{
  "acknowledged": true
}

Delete an index template Generally available; Added in 7.8.0

DELETE /_index_template/{name}

Api key auth Basic auth Bearer auth

The provided may contain multiple template names separated by a comma. If multiple template names are specified then there is no wildcard support and the provided names should match completely with existing templates.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string | array[string] Required

Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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

Values are -1 or 0.

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 /_index_template/{name}

DELETE /_index_template/my-index-template

resp = client.indices.delete_index_template(
    name="my-index-template",
)

const response = await client.indices.deleteIndexTemplate({
  name: "my-index-template",
});

response = client.indices.delete_index_template(
  name: "my-index-template"
)

$resp = $client->indices()->deleteIndexTemplate([
    "name" => "my-index-template",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_index_template/my-index-template"

client.indices().deleteIndexTemplate(d -> d
    .name("my-index-template")
);

Check index templates Generally available

HEAD /_index_template/{name}

Api key auth Basic auth Bearer auth

Check whether index templates exist.

Required authorization

Cluster privileges: manage_index_templates

Path parameters

name string Required

Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.

Query parameters

local boolean

If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
flat_settings boolean

If true, returns settings in flat format.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json

HEAD /_index_template/{name}

curl \
 --request HEAD 'http://api.example.com/_index_template/{name}' \
 --header "Authorization: $API_KEY"

Get mapping definitions Generally available

GET /{index}/_mapping/field/{fields}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_mapping/field/{fields}

GET /{index}/_mapping/field/{fields}

Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices.

This API is useful if you don't need a complete mapping or if an index mapping contains a large number of fields.

Required authorization

Index privileges: view_index_metadata

Path parameters

index string | array[string] Required

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.
fields string | array[string] Required

Comma-separated list or wildcard expression of fields used to limit returned information. Supports wildcards (*).

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.
expand_wildcards string | array[string]
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 are all, open, closed, hidden, or none.
ignore_unavailable boolean

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

If true, return all default settings in the response.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  mappings object Required
  
  Hide mappings attribute Show mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  full_name string Required
  
  mapping object Required

GET /{index}/_mapping/field/{fields}

GET publications/_mapping/field/title

resp = client.indices.get_field_mapping(
    index="publications",
    fields="title",
)

const response = await client.indices.getFieldMapping({
  index: "publications",
  fields: "title",
});

response = client.indices.get_field_mapping(
  index: "publications",
  fields: "title"
)

$resp = $client->indices()->getFieldMapping([
    "index" => "publications",
    "fields" => "title",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/publications/_mapping/field/title"

client.indices().getFieldMapping(g -> g
    .fields("title")
    .index("publications")
);

Response examples (200)

A sucessful response from `GET publications/_mapping/field/title`, which returns the mapping of a field called `title`.

{
   "publications": {
      "mappings": {
          "title": {
             "full_name": "title",
             "mapping": {
                "title": {
                   "type": "text"
                }
             }
          }
       }
   }
}

A successful response from `GET publications/_mapping/field/author.id,abstract,name`. The get field mapping API also supports wildcard notation.

{
   "publications": {
      "mappings": {
        "author.id": {
           "full_name": "author.id",
           "mapping": {
              "id": {
                 "type": "text"
              }
           }
        },
        "abstract": {
           "full_name": "abstract",
           "mapping": {
              "abstract": {
                 "type": "text"
              }
           }
        }
     }
   }
}

A successful response from `GET publications/_mapping/field/a*`.

{
   "publications": {
      "mappings": {
         "author.name": {
            "full_name": "author.name",
            "mapping": {
               "name": {
                 "type": "text"
               }
            }
         },
         "abstract": {
            "full_name": "abstract",
            "mapping": {
               "abstract": {
                  "type": "text"
               }
            }
         },
         "author.id": {
            "full_name": "author.id",
            "mapping": {
               "id": {
                  "type": "text"
               }
            }
         }
      }
   }
}

Get mapping definitions Generally available

GET /{index}/_mapping

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_mapping

GET /{index}/_mapping

For data streams, the API retrieves mappings for the stream’s backing indices.

Required authorization

Index privileges: view_index_metadata

Path parameters

index string | array[string] Required

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.

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.
expand_wildcards string | array[string]
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 are all, open, closed, hidden, or none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
local boolean Deprecated

If true, the request retrieves information from the local node only.
master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attributes Show * attributes object
  
  item object
  
  Hide item attributes Show item attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
  
  mappings object Required
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required

GET /{index}/_mapping

GET /books/_mapping

resp = client.indices.get_mapping(
    index="books",
)

const response = await client.indices.getMapping({
  index: "books",
});

response = client.indices.get_mapping(
  index: "books"
)

$resp = $client->indices()->getMapping([
    "index" => "books",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/books/_mapping"

client.indices().getMapping(g -> g
    .index("books")
);

Start the ILM plugin Generally available; Added in 6.6.0

POST /_ilm/start

Api key auth Basic auth Bearer auth

Start the index lifecycle management plugin if it is currently stopped. ILM is started automatically when the cluster is formed. Restarting ILM is necessary only when it has been stopped using the stop ILM API.

Required authorization

Cluster privileges: manage_ilm

Query parameters

master_timeout string

Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Values are -1 or 0.
timeout string

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

Values are -1 or 0.

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.

POST /_ilm/start

POST _ilm/start

resp = client.ilm.start()

const response = await client.ilm.start();

response = client.ilm.start

$resp = $client->ilm()->start();

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ilm/start"

client.ilm().start(s -> s);

Response examples (200)

A successful response when stating the ILM plugin.

{
  "acknowledged": true
}

Delete a Logstash pipeline Generally available; Added in 7.12.0

DELETE /_logstash/pipeline/{id}

Api key auth Basic auth Bearer auth

Delete a pipeline that is used for Logstash Central Management. If the request succeeds, you receive an empty response with an appropriate status code.

Required authorization

Cluster privileges: manage_logstash_pipelines

External documentation

Path parameters

id string Required

An identifier for the pipeline.

Responses

200 application/json

DELETE /_logstash/pipeline/{id}

DELETE _logstash/pipeline/my_pipeline

resp = client.logstash.delete_pipeline(
    id="my_pipeline",
)

const response = await client.logstash.deletePipeline({
  id: "my_pipeline",
});

response = client.logstash.delete_pipeline(
  id: "my_pipeline"
)

$resp = $client->logstash()->deletePipeline([
    "id" => "my_pipeline",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_logstash/pipeline/my_pipeline"

client.logstash().deletePipeline(d -> d
    .id("my_pipeline")
);

Close anomaly detection jobs Generally available; Added in 5.4.0

POST /_ml/anomaly_detectors/{job_id}/_close

Api key auth Basic auth Bearer auth

A job can be opened and closed multiple times throughout its lifecycle. A closed job cannot receive data or perform analysis operations, but you can still explore and navigate results. When you close a job, it runs housekeeping tasks such as pruning the model history, flushing buffers, calculating final results and persisting the model snapshots. Depending upon the size of the job, it could take several minutes to close and the equivalent time to re-open. After it is closed, the job has a minimal overhead on the cluster except for maintaining its meta data. Therefore it is a best practice to close jobs that are no longer required to process data. If you close an anomaly detection job whose datafeed is running, the request first tries to stop the datafeed. This behavior is equivalent to calling stop datafeed API with the same timeout and force parameters as the close job request. When a datafeed that has a specified end date stops, it automatically closes its associated job.

Required authorization

Cluster privileges: manage_ml

Path parameters

job_id string Required

Identifier for the anomaly detection job. It can be a job identifier, a group name, or a wildcard expression. You can close multiple anomaly detection jobs in a single API request by using a group name, a comma-separated list of jobs, or a wildcard expression. You can close all jobs by using _all or by specifying * as the job identifier.

Query parameters

allow_no_match boolean

Specifies what to do when the request: contains wildcard expressions and there are no jobs that match; contains the _all string or no identifiers and there are no matches; or contains wildcard expressions and there are only partial matches. By default, it returns an empty jobs array when there are no matches and the subset of results when there are partial matches. If false, the request returns a 404 status code when there are no matches or only partial matches.
force boolean

Use to close a failed job, or to forcefully close a job which has not responded to its initial close request; the request returns without performing the associated actions such as flushing buffers and persisting the model snapshots. If you want the job to be in a consistent state after the close job API returns, do not set to true. This parameter should be used only in situations where the job has already failed or where you are not interested in results the job might have recently produced or might produce in the future.
timeout string

Controls the time to wait until a job has closed.

Values are -1 or 0.

application/json

Body

allow_no_match boolean

Refer to the description for the allow_no_match query parameter.

Default value is true.
force boolean

Refer to the descriptiion for the force query parameter.

Default value is false.
timeout 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.

Responses

200 application/json
Hide response attribute Show response attribute object
- closed boolean Required

POST /_ml/anomaly_detectors/{job_id}/_close

POST _ml/anomaly_detectors/low_request_rate/_close

resp = client.ml.close_job(
    job_id="low_request_rate",
)

const response = await client.ml.closeJob({
  job_id: "low_request_rate",
});

response = client.ml.close_job(
  job_id: "low_request_rate"
)

$resp = $client->ml()->closeJob([
    "job_id" => "low_request_rate",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/_close"

client.ml().closeJob(c -> c
    .jobId("low_request_rate")
);

Response examples (200)

A successful response when closing anomaly detection jobs.

{
  "closed": true
}

Clear trained model deployment cache Generally available; Added in 8.5.0

POST /_ml/trained_models/{model_id}/deployment/cache/_clear

Api key auth Basic auth Bearer auth

Cache will be cleared on all nodes where the trained model is assigned. A trained model deployment may have an inference cache enabled. As requests are handled by each allocated node, their responses may be cached on that individual node. Calling this API clears the caches without restarting the deployment.

Required authorization

Cluster privileges: manage_ml

Path parameters

model_id string Required

The unique identifier of the trained model.

Responses

200 application/json
Hide response attribute Show response attribute object
- cleared boolean Required

POST /_ml/trained_models/{model_id}/deployment/cache/_clear

POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/cache/_clear

resp = client.ml.clear_trained_model_deployment_cache(
    model_id="elastic__distilbert-base-uncased-finetuned-conll03-english",
)

const response = await client.ml.clearTrainedModelDeploymentCache({
  model_id: "elastic__distilbert-base-uncased-finetuned-conll03-english",
});

response = client.ml.clear_trained_model_deployment_cache(
  model_id: "elastic__distilbert-base-uncased-finetuned-conll03-english"
)

$resp = $client->ml()->clearTrainedModelDeploymentCache([
    "model_id" => "elastic__distilbert-base-uncased-finetuned-conll03-english",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/cache/_clear"

client.ml().clearTrainedModelDeploymentCache(c -> c
    .modelId("elastic__distilbert-base-uncased-finetuned-conll03-english")
);

Response examples (200)

A successful response when clearing the inference cache.

{
  "cleared": true
}

Get trained model configuration info Generally available; Added in 7.10.0

GET /_ml/trained_models/{model_id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_ml/trained_models

GET /_ml/trained_models/{model_id}

Required authorization

Cluster privileges: monitor_ml

Path parameters

model_id string | array[string] Required

The unique identifier of the trained model or a model alias.

You can get information for multiple trained models in a single API request by using a comma-separated list of model IDs or a wildcard expression.

Query parameters

allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no models that match.
- Contains the _all string or no identifiers and there are no matches.
- Contains wildcard expressions and there are only partial matches.
If true, it returns an empty array when there are no matches and the subset of results when there are partial matches.
decompress_definition boolean

Specifies whether the included model definition should be returned as a JSON map (true) or in a custom compressed format (false).
exclude_generated boolean

Indicates if certain fields should be removed from the configuration on retrieval. This allows the configuration to be in an acceptable format to be retrieved and then added to another cluster.
from number

Skips the specified number of models.
include string
A comma delimited string of optional fields to include in the response body.

Supported values include:
- definition: Includes the model definition.
- feature_importance_baseline: Includes the baseline for feature importance values.
- hyperparameters: Includes the information about hyperparameters used to train the model. This information consists of the value, the absolute and relative importance of the hyperparameter as well as an indicator of whether it was specified by the user or tuned during hyperparameter optimization.
- total_feature_importance: Includes the total feature importance for the training data set. The baseline and total feature importance values are returned in the metadata field in the response body.
- definition_status: Includes the model definition status.
Values are definition, feature_importance_baseline, hyperparameters, total_feature_importance, or definition_status.
size number

Specifies the maximum number of models to obtain.
tags string | array[string]

A comma delimited string of tags. A trained model can have many tags, or none. When supplied, only trained models that contain all the supplied tags are returned.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- trained_model_configs array[object] Required
  
  An array of trained model resources, which are sorted by the model_id value in ascending order.
  
  Hide trained_model_configs attributes Show trained_model_configs attributes object
  
  model_id string Required
  
  model_type string
  
  Values are tree_ensemble, lang_ident, or pytorch.
  
  tags array[string] Required
  
  A comma delimited string of tags. A trained model can have many tags, or none.
  
  version string
  
  compressed_definition string
  
  created_by string
  
  Information on the creator of the trained model.
  
  create_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  string-1 string UnitMillis number
  
  default_field_map object
  
  Any field map described in the inference configuration takes precedence.
  
  Hide default_field_map attribute Show default_field_map attribute object
  
  * string Additional properties
  
  description string
  
  The free-text description of the trained model.
  
  estimated_heap_memory_usage_bytes number
  
  The estimated heap usage in bytes to keep the trained model in memory.
  
  estimated_operations number
  
  The estimated number of operations to use the trained model.
  
  fully_defined boolean
  
  True if the full model definition is present.
  
  inference_config object
  
  Inference configuration provided when storing the model config
  
  Hide inference_config attributes Show inference_config attributes object
  
  regression object
  
  Hide regression attributes Show regression attributes object
  
  results_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  num_top_feature_importance_values number
  
  Specifies the maximum number of feature importance values per document.
  
  Default value is 0.
  
  classification object
  
  Hide classification attributes Show classification attributes object
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  num_top_feature_importance_values number
  
  Specifies the maximum number of feature importance values per document.
  
  Default value is 0.
  
  prediction_field_type string
  
  Specifies the type of the predicted field to write. Acceptable values are: string, number, boolean. When boolean is provided 1.0 is transformed to true and 0.0 to false.
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  top_classes_results_field string
  
  Specifies the field to which the top classes are written. Defaults to top_classes.
  
  text_classification object
  
  Text classification configuration options
  
  Hide text_classification attributes Show text_classification attributes object
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  classification_labels array[string]
  
  Classification labels to apply other than the stored labels. Must have the same deminsions as the default configured labels
  
  vocabulary object
  
  Hide vocabulary attribute Show vocabulary attribute object
  
  index string Required
  
  zero_shot_classification object
  
  Zero shot classification configuration options
  
  Hide zero_shot_classification attributes Show zero_shot_classification attributes object
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  hypothesis_template string
  
  Hypothesis template used when tokenizing labels for prediction
  
  Default value is "This example is {}.".
  
  classification_labels array[string] Required
  
  The zero shot classification labels indicating entailment, neutral, and contradiction Must contain exactly and only entailment, neutral, and contradiction
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  multi_label boolean
  
  Indicates if more than one true label exists.
  
  Default value is false.
  
  labels array[string]
  
  The labels to predict.
  
  fill_mask object
  
  Fill mask inference options
  
  Hide fill_mask attributes Show fill_mask attributes object
  
  mask_token string
  
  The string/token which will be removed from incoming documents and replaced with the inference prediction(s). In a response, this field contains the mask token for the specified model/tokenizer. Each model and tokenizer has a predefined mask token which cannot be changed. Thus, it is recommended not to set this value in requests. However, if this field is present in a request, its value must match the predefined value for that model/tokenizer, otherwise the request will fail.
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  vocabulary object Required
  
  Hide vocabulary attribute Show vocabulary attribute object
  
  index string Required
  
  learning_to_rank object
  
  Hide learning_to_rank attributes Show learning_to_rank attributes object
  
  default_params object
  
  Hide default_params attribute Show default_params attribute object
  
  * object Additional properties
  
  feature_extractors array[object]
  
  num_top_feature_importance_values number Required
  
  ner object
  
  Named entity recognition options
  
  Hide ner attributes Show ner attributes object
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  classification_labels array[string]
  
  The token classification labels. Must be IOB formatted tags
  
  vocabulary object
  
  Hide vocabulary attribute Show vocabulary attribute object
  
  index string Required
  
  pass_through object
  
  Pass through configuration options
  
  Hide pass_through attributes Show pass_through attributes object
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  vocabulary object
  
  Hide vocabulary attribute Show vocabulary attribute object
  
  index string Required
  
  text_embedding object
  
  Text embedding inference options
  
  Hide text_embedding attributes Show text_embedding attributes object
  
  embedding_size number
  
  The number of dimensions in the embedding output
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  vocabulary object Required
  
  Hide vocabulary attribute Show vocabulary attribute object
  
  index string Required
  
  text_expansion object
  
  Text expansion inference options
  
  Hide text_expansion attributes Show text_expansion attributes object
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  vocabulary object Required
  
  Hide vocabulary attribute Show vocabulary attribute object
  
  index string Required
  
  question_answering object
  
  Question answering inference options
  
  Hide question_answering attributes Show question_answering attributes object
  
  num_top_classes number
  
  Specifies the number of top class predictions to return. Defaults to 0.
  
  tokenization object
  
  Tokenization options stored in inference configuration
  
  Hide tokenization attributes Show tokenization attributes object
  
  bert
  
  bert_ja
  
  mpnet
  
  roberta
  
  xlm_roberta
  
  results_field string
  
  The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.
  
  max_answer_length number
  
  The maximum answer length to consider
  
  input object Required
  
  Hide input attribute Show input attribute object
  
  field_names array[string] Required
  
  An array of input field names for the model.
  
  license_level string
  
  The license level of the trained model.
  
  metadata object
  
  Hide metadata attributes Show metadata attributes object
  
  model_aliases array[string]
  
  feature_importance_baseline object
  
  An object that contains the baseline for feature importance values. For regression analysis, it is a single value. For classification analysis, there is a value for each class.
  
  Hide feature_importance_baseline attribute Show feature_importance_baseline attribute object
  
  * string Additional properties
  
  hyperparameters array[object]
  
  List of the available hyperparameters optimized during the fine_parameter_tuning phase as well as specified by the user.
  
  Hide hyperparameters attributes Show hyperparameters attributes object
  
  absolute_importance number
  
  A positive number showing how much the parameter influences the variation of the loss function. For hyperparameters with values that are not specified by the user but tuned during hyperparameter optimization.
  
  name string Required
  
  relative_importance number
  
  A number between 0 and 1 showing the proportion of influence on the variation of the loss function among all tuned hyperparameters. For hyperparameters with values that are not specified by the user but tuned during hyperparameter optimization.
  
  supplied boolean Required
  
  Indicates if the hyperparameter is specified by the user (true) or optimized (false).
  
  value number Required
  
  The value of the hyperparameter, either optimized or specified by the user.
  
  total_feature_importance array[object]
  
  An array of the total feature importance for each feature used from the training data set. This array of objects is returned if data frame analytics trained the model and the request includes total_feature_importance in the include request parameter.
  
  Hide total_feature_importance attributes Show total_feature_importance attributes object
  
  feature_name string Required
  
  importance array[object] Required
  
  A collection of feature importance statistics related to the training data set for this particular feature.
  
  classes array[object] Required
  
  If the trained model is a classification model, feature importance statistics are gathered per target class value.
  
  model_size_bytes number | string
  
  One of:
  number-1 number string-2 string
  
  model_package object
  
  Hide model_package attributes Show model_package attributes object
  
  create_time number
  
  Time unit for milliseconds
  
  description string
  
  inference_config object
  
  Hide inference_config attribute Show inference_config attribute object
  
  * object Additional properties
  
  metadata object
  
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties
  
  minimum_version string
  
  model_repository string
  
  model_type string
  
  packaged_model_id string Required
  
  platform_architecture string
  
  prefix_strings object
  
  Hide prefix_strings attributes Show prefix_strings attributes object
  
  ingest string
  
  String prepended to input at ingest
  
  search string
  
  String prepended to input at search
  
  size number | string
  
  One of:
  number-1 number string-2 string
  
  sha256 string
  
  tags array[string]
  
  vocabulary_file string
  
  location object
  
  Hide location attribute Show location attribute object
  
  index object Required
  
  Hide index attribute Show index attribute object
  
  name string Required
  
  platform_architecture string
  
  prefix_strings object
  
  Hide prefix_strings attributes Show prefix_strings attributes object
  
  ingest string
  
  String prepended to input at ingest
  
  search string
  
  String prepended to input at search

GET /_ml/trained_models/{model_id}

GET _ml/trained_models/

resp = client.ml.get_trained_models()

const response = await client.ml.getTrainedModels();

response = client.ml.get_trained_models

$resp = $client->ml()->getTrainedModels();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/trained_models/"

client.ml().getTrainedModels(g -> g);

Create an index from a source index Technical preview; Added in 8.18.0

POST /_create_from/{source}/{dest}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /_create_from/{source}/{dest}

POST /_create_from/{source}/{dest}

Copy the mappings and settings from the source index to a destination index while allowing request settings and mappings to override the source values.

Path parameters

source string Required

The source index or data stream name
dest string Required

The destination index or data stream name

application/json

Body Required

mappings_override object
Hide mappings_override attributes Show mappings_override attributes object
- all_field object
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
- date_detection boolean
- dynamic string
  
  Values are strict, runtime, true, or false.
- dynamic_date_formats array[string]
- dynamic_templates array[object]
- _field_names object
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
- index_field object
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
- _meta object
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- numeric_detection boolean
- properties object
- _routing object
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
- _size object
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
- _source object
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
- runtime object
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  collapse object
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  from number
  
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  
  Default value is 0.
  
  highlight
  
  track_total_hits boolean | number
  
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  
  knn
  
  rank object
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  rescore
  
  retriever object
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  
  Default value is 10.
  
  slice object
  
  sort
  
  _source
  
  fields array[object]
  
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  
  suggest object
  
  terminate_after number
  
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  stored_fields string | array[string]
  
  pit object
  
  runtime_mappings object
  
  stats array[string]
  
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- enabled boolean
- subobjects string
  
  Values are true or false.
- _data_stream_timestamp object
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
settings_override object
Index settings
remove_index_blocks boolean

If index blocks should be removed when creating destination index (optional)

Default value is true.

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- index string Required
- shards_acknowledged boolean Required

POST /_create_from/{source}/{dest}

POST _create_from/my-index/my-new-index

resp = client.perform_request(
    "POST",
    "/_create_from/my-index/my-new-index",
)

const response = await client.transport.request({
  method: "POST",
  path: "/_create_from/my-index/my-new-index",
});

response = client.perform_request(
  "POST",
  "/_create_from/my-index/my-new-index",
  {},
)

$requestFactory = Psr17FactoryDiscovery::findRequestFactory();
$request = $requestFactory->createRequest(
    "POST",
    "/_create_from/my-index/my-new-index",
);
$resp = $client->sendRequest($request);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_create_from/my-index/my-new-index"

client.indices().createFrom(c -> c
    .dest("my-new-index")
    .source("my-index")
    .createFrom(cr -> cr)
);

Get script languages Generally available

GET /_script_language

Api key auth Basic auth Bearer auth

Get a list of available script types, languages, and contexts.

Required authorization

Cluster privileges: manage

Responses

200 application/json
Hide response attributes Show response attributes object
- language_contexts array[object] Required
  
  Hide language_contexts attributes Show language_contexts attributes object
  
  contexts array[string] Required
  
  language string Required
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
- types_allowed array[string] Required

GET /_script_language

GET _script_language

resp = client.get_script_languages()

const response = await client.getScriptLanguages();

response = client.get_script_languages

$resp = $client->getScriptLanguages();

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_script_language"

client.getScriptLanguages();

Count search results Generally available

GET /{index}/_count

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

POST /_count

GET /_count

POST /{index}/_count

GET /{index}/_count

Get the number of documents matching a query.

The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. The query is optional. When no query is provided, the API uses match_all to count all the documents.

The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count.

Required authorization

Index privileges: read

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams and indices, omit this parameter or use * or _all.

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.
analyzer string

The analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.
analyze_wildcard boolean

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
default_operator string

The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

Values are and, AND, or, or OR.
df string

The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.
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.

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 are all, open, closed, hidden, or none.
ignore_throttled boolean Deprecated

If true, concrete, expanded, or aliased indices are ignored when frozen.
ignore_unavailable boolean

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

If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.
min_score number

The minimum _score value that documents must have to be included in the result.
preference string

The node or shard the operation should be performed on. By default, it is random.
routing string

A custom value used to route operations to a specific shard.
terminate_after number

The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
q string

The query in Lucene query string syntax. This parameter cannot be used with a request body.

application/json

Body

query object

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

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- _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
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number

GET /{index}/_count

GET /my-index-000001/_count
{
  "query" : {
    "term" : { "user.id" : "kimchy" }
  }
}

resp = client.count(
    index="my-index-000001",
    query={
        "term": {
            "user.id": "kimchy"
        }
    },
)

const response = await client.count({
  index: "my-index-000001",
  query: {
    term: {
      "user.id": "kimchy",
    },
  },
});

response = client.count(
  index: "my-index-000001",
  body: {
    "query": {
      "term": {
        "user.id": "kimchy"
      }
    }
  }
)

$resp = $client->count([
    "index" => "my-index-000001",
    "body" => [
        "query" => [
            "term" => [
                "user.id" => "kimchy",
            ],
        ],
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"term":{"user.id":"kimchy"}}}' "$ELASTICSEARCH_URL/my-index-000001/_count"

client.count(c -> c
    .index("my-index-000001")
    .query(q -> q
        .term(t -> t
            .field("user.id")
            .value(FieldValue.of("kimchy"))
        )
    )
);

Request example

Run `GET /my-index-000001/_count?q=user:kimchy`. Alternatively, run `GET /my-index-000001/_count` with the same query in the request body. Both requests count the number of documents in `my-index-000001` with a `user.id` of `kimchy`.

{
  "query" : {
    "term" : { "user.id" : "kimchy" }
  }
}

Response examples (200)

A successful response from `GET /my-index-000001/_count?q=user:kimchy`.

{
  "count": 1,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}

Get the field capabilities Generally available; Added in 5.4.0

POST /{index}/_field_caps

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_field_caps

POST /_field_caps

GET /{index}/_field_caps

POST /{index}/_field_caps

Get information about the capabilities of fields among multiple indices.

For data streams, the API returns field capabilities among the stream’s backing indices. It returns runtime fields like any other field. For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the keyword family.

Required authorization

Index privileges: view_index_metadata,read

Path parameters

index string | array[string] Required

A 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.

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. 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 are all, open, closed, hidden, or none.
fields string | array[string]

A comma-separated list of fields to retrieve capabilities for. Wildcard (*) expressions are supported.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
include_unmapped boolean

If true, unmapped fields are included in the response.
filters string Generally available; Added in 8.2.0

A comma-separated list of filters to apply to the response.
types array[string] Generally available; Added in 8.2.0

A comma-separated list of field types to include. Any fields that do not match one of these types will be excluded from the results. It defaults to empty, meaning that all field types are returned.
include_empty_fields boolean Generally available; Added in 8.13.0

If false, empty fields are not included in the response.

application/json

Body

fields string | array[string]
index_filter object

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

External documentation
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  Hide attributes Show attributes
  
  aggregations object
  
  Defines the aggregations that are run as part of the search request.
  
  External documentation
  
  collapse object
  External documentation
  
  explain boolean
  
  If true, the request returns detailed information about score computation as part of a hit.
  
  Default value is false.
  
  ext object
  
  Configuration of search extensions defined by Elasticsearch plugins.
  
  Hide ext attribute Show ext attribute object
  
  * object Additional properties
  
  from number
  
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  
  Default value is 0.
  
  highlight object
  
  track_total_hits boolean | number
  
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  
  indices_boost array[object]
  
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  
  External documentation
  
  docvalue_fields array[object]
  
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  
  A reference to a field with formatting instructions on how to return the value
  
  External documentation
  
  A reference to a field with formatting instructions on how to return the value
  
  knn object | array[object]
  
  The approximate kNN search to run.
  
  One of:
  KnnSearch object array-2 array[object]
  
  rank object
  
  Hide rank attribute Show rank attribute object
  
  rrf
  
  min_score number
  
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  
  post_filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  profile boolean
  
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  
  Default value is false.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  rescore array[object]
  
  retriever object
  
  Hide retriever attributes Show retriever attributes object
  
  standard
  
  knn
  
  rrf
  
  text_similarity_reranker
  
  rule
  
  rescorer
  
  linear
  
  pinned
  
  script_fields object
  
  Retrieve a script evaluation (based on different fields) for each hit.
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  size number
  
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  
  Default value is 10.
  
  slice object
  
  Hide slice attributes Show slice attributes object
  
  field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  id string Required
  
  max number Required
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  boolean-1 boolean SourceFilter object
  
  fields array[object]
  
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  
  A reference to a field with formatting instructions on how to return the value
  
  A reference to a field with formatting instructions on how to return the value
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
  
  terminate_after number
  
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  
  If set to 0 (default), the query does not terminate early.
  
  Default value is 0.
  
  timeout string
  
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  
  track_scores boolean
  
  If true, calculate and return document scores, even if the scores are not used for sorting.
  
  Default value is false.
  
  version boolean
  
  If true, the request returns the document version as part of a hit.
  
  Default value is false.
  
  seq_no_primary_term boolean
  
  If true, the request returns sequence number and primary term of the last modification of each hit.
  
  External documentation
  
  stored_fields string | array[string]
  
  pit object
  
  Hide pit attributes Show pit attributes object
  
  id string Required
  
  keep_alive 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.
  
  runtime_mappings object
  
  stats array[string]
  
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

Responses

200 application/json
Hide response attributes Show response attributes object
- indices string | array[string] Required
- fields object Required
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  aggregatable boolean Required
  
  Whether this field can be aggregated on all indices.
  
  indices string | array[string]
  
  meta object
  
  Hide meta attribute Show meta attribute object
  
  * object Additional properties
  
  non_aggregatable_indices string | array[string]
  
  non_searchable_indices string | array[string]
  
  searchable boolean Required
  
  Whether this field is indexed for search on all indices.
  
  type string Required
  
  metadata_field boolean
  
  Whether this field is registered as a metadata field.
  
  time_series_dimension boolean Technical preview; Added in 8.0.0
  
  Whether this field is used as a time series dimension.
  
  time_series_metric string
  
  Values are gauge, counter, summary, histogram, or position.
  
  non_dimension_indices array[string] Technical preview; Added in 8.0.0
  
  If this list is present in response then some indices have the field marked as a dimension and other indices, the ones in this list, do not.
  
  metric_conflicts_indices array[string] Technical preview; Added in 8.0.0
  
  The list of indices where this field is present if these indices don’t have the same time_series_metric value for this field.

POST /{index}/_field_caps

POST my-index-*/_field_caps?fields=rating
{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

resp = client.field_caps(
    index="my-index-*",
    fields="rating",
    index_filter={
        "range": {
            "@timestamp": {
                "gte": "2018"
            }
        }
    },
)

const response = await client.fieldCaps({
  index: "my-index-*",
  fields: "rating",
  index_filter: {
    range: {
      "@timestamp": {
        gte: "2018",
      },
    },
  },
});

response = client.field_caps(
  index: "my-index-*",
  fields: "rating",
  body: {
    "index_filter": {
      "range": {
        "@timestamp": {
          "gte": "2018"
        }
      }
    }
  }
)

$resp = $client->fieldCaps([
    "index" => "my-index-*",
    "fields" => "rating",
    "body" => [
        "index_filter" => [
            "range" => [
                "@timestamp" => [
                    "gte" => "2018",
                ],
            ],
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index_filter":{"range":{"@timestamp":{"gte":"2018"}}}}' "$ELASTICSEARCH_URL/my-index-*/_field_caps?fields=rating"

Request example

Run `POST my-index-*/_field_caps?fields=rating` to get field capabilities and filter indices with a query. Indices that rewrite the provided filter to `match_none` on every shard will be filtered from the response.

{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

Response examples (200)

A successful response from `GET _field_caps?fields=rating,title`. The field `rating` is defined as a long in `index1` and `index2` and as a `keyword` in `index3` and `index4`. The field `rating` is not aggregatable in `index1`. The field `rating` is not searchable in `index4`. The field `title` is defined as text in all indices.

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
    "rating": {                                   
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]  
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]    
      }
    },
    "title": {                                    
      "text": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false
      }
    }
  }
}

A successful response from `GET _field_caps?fields=rating,title&include_unmapped`. The response contains an entry for each field that is present in some indices but not all. For example, the `rating` and `title` fields are unmapped in `index5`.

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
    "rating": {                                   
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]  
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]    
      }
    },
    "title": {                                    
      "text": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false
      }
    }
  }
}

Run multiple searches Generally available; Added in 1.3.0

POST /{index}/_msearch

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_msearch

POST /_msearch

GET /{index}/_msearch

POST /{index}/_msearch

The format of the request is similar to the bulk API format and makes use of the newline delimited JSON (NDJSON) format. The structure is as follows:

header\n
body\n
header\n
body\n

This structure is specifically optimized to reduce parsing if a specific search ends up redirected to another node.

IMPORTANT: The final line of data must end with a newline character \n. Each newline character may be preceded by a carriage return \r. When sending requests to this endpoint the Content-Type header should be set to application/x-ndjson.

Required authorization

Index privileges: read

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, and index aliases to search.

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.
ccs_minimize_roundtrips boolean

If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
expand_wildcards string | array[string]
Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.

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 are all, open, closed, hidden, or none.
ignore_throttled boolean

If true, concrete, expanded or aliased indices are ignored when frozen.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
include_named_queries_score boolean

Indicates whether hit.matched_queries should be rendered as a map that includes the name of the matched query associated with its score (true) or as an array containing the name of the matched queries (false) This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
index string | array[string]

Comma-separated list of data streams, indices, and index aliases to use as default
max_concurrent_searches number

Maximum number of concurrent searches the multi search API can execute. Defaults to max(1, (# of data nodes * min(search thread pool size, 10))).
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.
pre_filter_shard_size number

Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
rest_total_hits_as_int boolean

If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
routing string

Custom routing value used to route search operations to a specific shard.
search_type string
Indicates whether global term and document frequencies should be used when scoring returned documents.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
typed_keys boolean

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

application/json

Body object Required

Contains parameters used to limit or change the subsequent search body request.

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
External documentation
explain boolean

If true, the request returns detailed information about score computation as part of a hit.

Default value is false.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

Default value is 0.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 string-1 string string-2 string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
 
 Default value is .,!? \t\n.
- boundary_max_scan number
 
 How far to scan for boundary characters.
 
 Default value is 20.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 Default value is Locale.ROOT.
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
 
 Default value is 100.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 Default value is 0.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 Default value is 5.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 Default value is 256.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 Default value is true.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object | array[object] Required
 
 One of:
 object-1 object array-2 array[object]
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

A reference to a field with formatting instructions on how to return the value

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

Default value is 3.

from number

Inner hit starting document offset.

Default value is 0.

collapse object
External documentation

docvalue_fields array[object]

A reference to a field with formatting instructions on how to return the value

A reference to a field with formatting instructions on how to return the value

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields array[string]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

sort array[string | object]

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
boolean-1 boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

Default value is false.

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

Default value is 3.

from number

Inner hit starting document offset.

Default value is 0.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields array[string]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

sort

_source

stored_fields string | array[string]

track_scores boolean

Default value is false.

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
post_filter object

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

External documentation
profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.

Default value is false.
query object

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

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
object-2 object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

query_weight number

Relative importance of the original query versus the rescore query.

Default value is 1.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

Default value is 1.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature
Hide attributes Show attributes object

window_size number

query object

learning_to_rank object
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort array[string | object]
  
  collapse object
  External documentation
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
  
  query string
  
  fields array[string]
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string Required
  
  The text snippet used as the basis for similarity comparison
  
  field string Required
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  ruleset_ids string | array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  One of:
  Id string array-2 array[string]
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
- rescorer object
  Hide rescorer attributes Show rescorer attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retriever object Required
  
  rescore array[object] Required
- linear object
  Hide linear attributes Show linear attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retrievers array[object]
  
  Inner retrievers.
  
  rank_window_size number
  
  query string
  
  fields array[string]
  
  normalizer string
  
  Values are none, minmax, or l2_norm.
- pinned object
  Hide pinned attributes Show pinned attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  _name string
  
  Retriever name.
  
  retriever object Required
  
  ids array[string]
  
  docs array[object]
  
  rank_window_size number
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.

Default value is 10.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object array-2 array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
boolean-1 boolean SourceFilter object
Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

A reference to a field with formatting instructions on how to return the value
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.

If set to 0 (default), the query does not terminate early.

Default value is 0.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.

Default value is false.
version boolean

If true, the request returns the document version as part of a hit.

Default value is false.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive 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.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  string-1 string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- responses array[object] Required
  
  One of:
  object-2 object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  The response returned by Elasticsearch when request execution did not succeed.
  
  Hide attributes Show attributes
  
  error object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  status number Required

POST /{index}/_msearch

GET my-index-000001/_msearch
{ }
{"query" : {"match" : { "message": "this is a test"}}}
{"index": "my-index-000002"}
{"query" : {"match_all" : {}}}

resp = client.msearch(
    index="my-index-000001",
    searches=[
        {},
        {
            "query": {
                "match": {
                    "message": "this is a test"
                }
            }
        },
        {
            "index": "my-index-000002"
        },
        {
            "query": {
                "match_all": {}
            }
        }
    ],
)

const response = await client.msearch({
  index: "my-index-000001",
  searches: [
    {},
    {
      query: {
        match: {
          message: "this is a test",
        },
      },
    },
    {
      index: "my-index-000002",
    },
    {
      query: {
        match_all: {},
      },
    },
  ],
});

response = client.msearch(
  index: "my-index-000001",
  body: [
    {},
    {
      "query": {
        "match": {
          "message": "this is a test"
        }
      }
    },
    {
      "index": "my-index-000002"
    },
    {
      "query": {
        "match_all": {}
      }
    }
  ]
)

$resp = $client->msearch([
    "index" => "my-index-000001",
    "body" => array(
        new ArrayObject([]),
        [
            "query" => [
                "match" => [
                    "message" => "this is a test",
                ],
            ],
        ],
        [
            "index" => "my-index-000002",
        ],
        [
            "query" => [
                "match_all" => new ArrayObject([]),
            ],
        ],
    ),
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '[{},{"query":{"match":{"message":"this is a test"}}},{"index":"my-index-000002"},{"query":{"match_all":{}}}]' "$ELASTICSEARCH_URL/my-index-000001/_msearch"

Request example

An example body for a `GET my-index-000001/_msearch` request.

{ }
{"query" : {"match" : { "message": "this is a test"}}}
{"index": "my-index-000002"}
{"query" : {"match_all" : {}}}

Run multiple templated searches Generally available; Added in 5.0.0

POST /{index}/_msearch/template

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_msearch/template

POST /_msearch/template

GET /{index}/_msearch/template

POST /{index}/_msearch/template

Run multiple templated searches with a single request. If you are providing a text file or text input to curl, use the --data-binary flag instead of -d to preserve newlines. For example:

$ cat requests
{ "index": "my-index" }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ "index": "my-other-index" }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo

Required authorization

Index privileges: read

External documentation

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams and indices, omit this parameter or use *.

Query parameters

ccs_minimize_roundtrips boolean

If true, network round-trips are minimized for cross-cluster search requests.
max_concurrent_searches number

The maximum number of concurrent searches the API can run.
search_type string
The type of the search operation.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_int boolean

If true, the response returns hits.total as an integer. If false, it returns hits.total as an object.
typed_keys boolean

If true, the response prefixes aggregation and suggester names with their respective types.

application/json

Body object Required

Contains parameters used to limit or change the subsequent search body request.

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

explain boolean

If true, returns detailed information about score calculation as part of each hit.

Default value is false.
id string
params object

Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.
Hide params attribute Show params attribute object
- * object Additional properties
profile boolean

If true, the query execution is profiled.

Default value is false.
source string | object
One of:
string-1 string SearchRequestBody object
Hide attributes Show attributes

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation

collapse object
External documentation

explain boolean

If true, the request returns detailed information about score computation as part of a hit.

Default value is false.

ext object

Configuration of search extensions defined by Elasticsearch plugins.

Hide ext attribute Show ext attribute object

* object Additional properties

from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.

Default value is 0.

highlight object

Hide highlight attributes Show highlight attributes object

type

boundary_chars string

A string that contains each boundary character.

Default value is .,!? \t\n.

boundary_max_scan number

How far to scan for boundary characters.

Default value is 20.

boundary_scanner string

Values are chars, sentence, or word.

boundary_scanner_locale string

Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

Default value is Locale.ROOT.

force_source boolean Deprecated

fragmenter string

Values are simple or span.

fragment_size number

The size of the highlighted fragment in characters.

Default value is 100.

highlight_filter boolean

highlight_query object

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

max_fragment_length number

max_analyzed_offset number

If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

no_match_size number

The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

Default value is 0.

number_of_fragments number

The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

Default value is 5.

options object

order string

Value is score.

phrase_limit number

Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

Default value is 256.

post_tags array[string]

Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

pre_tags array[string]

Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

require_field_match boolean

By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

Default value is true.

tags_schema string

Value is styled.

encoder string

Values are default or html.

fields

track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.

indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation

Hide indices_boost attribute Show indices_boost attribute object

* number Additional properties

docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

A reference to a field with formatting instructions on how to return the value

External documentation

Hide docvalue_fields attributes Show docvalue_fields attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean

knn object | array[object]

The approximate kNN search to run.

One of:
KnnSearch object array-2 array[object]

Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

rescore_vector object

rank object

Hide rank attribute Show rank attribute object

rrf object

min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.

post_filter object

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

External documentation

profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.

Default value is false.

query object

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

External documentation

rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.

One of:
object-2 object array-2 array[object]

retriever object

Hide retriever attributes Show retriever attributes object

standard object

knn object

rrf object

text_similarity_reranker object

rule object

rescorer object

linear object

pinned object

script_fields object

Retrieve a script evaluation (based on different fields) for each hit.

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

Hide * attributes Show * attributes object

script object Required

ignore_failure boolean

search_after array[number | string | boolean | null]

A field value.

size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.

Default value is 10.

slice object

Hide slice attributes Show slice attributes object

field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

id string Required

max number Required

sort string | object | array[string | object]

One of:
Field string SortOptions object array-2 array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
boolean-1 boolean SourceFilter object

Hide attributes Show attributes

exclude_vectors boolean

If true, vector fields are excluded from the returned source.

This option takes precedence over includes: any vector field will remain excluded even if it matches an includes rule.

excludes string | array[string]

includes string | array[string]

fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

A reference to a field with formatting instructions on how to return the value

Hide fields attributes Show fields attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean

suggest object

Hide suggest attribute Show suggest attribute object

text string

Global suggest text, to avoid repetition when the same text is used in several suggesters

terminate_after number

The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.

If set to 0 (default), the query does not terminate early.

Default value is 0.

timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.

track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.

Default value is false.

version boolean

If true, the request returns the document version as part of a hit.

Default value is false.

seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation

stored_fields string | array[string]

pit object

Hide pit attributes Show pit attributes object

id string Required

keep_alive 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.

runtime_mappings object

Hide runtime_mappings attribute Show runtime_mappings attribute object

* object Additional properties

Hide * attributes Show * attributes object

fields object

For type composite

fetch_fields array[object]

For type lookup

format string

A custom format for date type runtime fields.

input_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

target_field string

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

target_index string

script object

type string Required

Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- responses array[object] Required
  
  One of:
  object-2 object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  The response returned by Elasticsearch when request execution did not succeed.
  
  Hide attributes Show attributes
  
  error object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  status number Required

POST /{index}/_msearch/template

GET my-index/_msearch/template
{ }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

resp = client.msearch_template(
    index="my-index",
    search_templates=[
        {},
        {
            "id": "my-search-template",
            "params": {
                "query_string": "hello world",
                "from": 0,
                "size": 10
            }
        },
        {},
        {
            "id": "my-other-search-template",
            "params": {
                "query_type": "match_all"
            }
        }
    ],
)

const response = await client.msearchTemplate({
  index: "my-index",
  search_templates: [
    {},
    {
      id: "my-search-template",
      params: {
        query_string: "hello world",
        from: 0,
        size: 10,
      },
    },
    {},
    {
      id: "my-other-search-template",
      params: {
        query_type: "match_all",
      },
    },
  ],
});

response = client.msearch_template(
  index: "my-index",
  body: [
    {},
    {
      "id": "my-search-template",
      "params": {
        "query_string": "hello world",
        "from": 0,
        "size": 10
      }
    },
    {},
    {
      "id": "my-other-search-template",
      "params": {
        "query_type": "match_all"
      }
    }
  ]
)

$resp = $client->msearchTemplate([
    "index" => "my-index",
    "body" => array(
        new ArrayObject([]),
        [
            "id" => "my-search-template",
            "params" => [
                "query_string" => "hello world",
                "from" => 0,
                "size" => 10,
            ],
        ],
        new ArrayObject([]),
        [
            "id" => "my-other-search-template",
            "params" => [
                "query_type" => "match_all",
            ],
        ],
    ),
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '[{},{"id":"my-search-template","params":{"query_string":"hello world","from":0,"size":10}},{},{"id":"my-other-search-template","params":{"query_type":"match_all"}}]' "$ELASTICSEARCH_URL/my-index/_msearch/template"

Request example

Run `GET my-index/_msearch/template` to run multiple templated searches.

{ }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

Open a point in time Generally available; Added in 7.10.0

POST /{index}/_pit

Api key auth Basic auth Bearer auth

A search request by default runs against the most recent visible data of the target indices, which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple search requests using the same point in time. For example, if refreshes happen between search_after requests, then the results of those requests might not be consistent as changes happening between searches are only visible to the more recent point in time.

A point in time must be opened explicitly before being used in search requests.

A subsequent search request with the pit parameter must not specify index, routing, or preference values as these parameters are copied from the point in time.

Just like regular searches, you can use from and size to page through point in time search results, up to the first 10,000 hits. If you want to retrieve more hits, use PIT with search_after.

IMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.

When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a NoShardAvailableActionException exception. To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.

Keeping point in time alive

The keep_alive parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time. The value does not need to be long enough to process all data — it just needs to be long enough for the next request.

Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments. Once the smaller segments are no longer needed they are deleted. However, open point-in-times prevent the old segments from being deleted since they are still in use.

TIP: Keeping older segments alive means that more disk space and file handles are needed. Ensure that you have configured your nodes to have ample free file handles.

Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request. Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates. Note that a point-in-time doesn't prevent its associated indices from being deleted. You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.

Required authorization

Index privileges: read

Path parameters

index string | array[string] Required

A comma-separated list of index names to open point in time; use _all or empty string to perform the operation on all indices

Query parameters

keep_alive string Required

Extend the length of time that the point in time persists.

Values are -1 or 0.
ignore_unavailable boolean

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

The node or shard the operation should be performed on. By default, it is random.
routing string

A custom value that is used to route operations to a specific shard.
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.

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 are all, open, closed, hidden, or none.
allow_partial_search_results boolean

Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT. If false, creating a point in time request when a shard is missing or unavailable will throw an exception. If true, the point in time will contain all the shards that are available at the time of the request.
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.

application/json

Body

index_filter object

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

External documentation

Responses

200 application/json
Hide response attributes Show response attributes object
- _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
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  shard number Required
  
  status string
  
  skipped number
- id string Required

POST /{index}/_pit

POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true

resp = client.open_point_in_time(
    index="my-index-000001",
    keep_alive="1m",
    allow_partial_search_results=True,
)

const response = await client.openPointInTime({
  index: "my-index-000001",
  keep_alive: "1m",
  allow_partial_search_results: "true",
});

response = client.open_point_in_time(
  index: "my-index-000001",
  keep_alive: "1m",
  allow_partial_search_results: "true"
)

$resp = $client->openPointInTime([
    "index" => "my-index-000001",
    "keep_alive" => "1m",
    "allow_partial_search_results" => "true",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true"

client.openPointInTime(o -> o
    .allowPartialSearchResults(true)
    .index("my-index-000001")
    .keepAlive(k -> k
        .offset(1)
    )
);

Response examples (200)

A successful response from `POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true`. It includes a summary of the total number of shards, as well as the number of successful shards when creating the PIT.

{
  "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=",
  "_shards": {
    "total": 10,
    "successful": 10,
    "skipped": 0,
    "failed": 0
  }
}

Clear the cache Technical preview; Added in 7.10.0

POST /{index}/_searchable_snapshots/cache/clear

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

POST /_searchable_snapshots/cache/clear

POST /{index}/_searchable_snapshots/cache/clear

Clear indices and data streams from the shared cache for partially mounted indices.

Required authorization

Index privileges: manage
Cluster privileges: manage

External documentation

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to clear from the cache. It supports wildcards (*).

Query parameters

expand_wildcards string | array[string]
Whether to expand wildcard expression to concrete indices that are open, closed or both.

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 are all, open, closed, hidden, or none.
allow_no_indices boolean

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
ignore_unavailable boolean

Whether specified concrete indices should be ignored when unavailable (missing or closed)

Responses

200 application/json

POST /{index}/_searchable_snapshots/cache/clear

POST /my-index/_searchable_snapshots/cache/clear

resp = client.searchable_snapshots.clear_cache(
    index="my-index",
)

const response = await client.searchableSnapshots.clearCache({
  index: "my-index",
});

response = client.searchable_snapshots.clear_cache(
  index: "my-index"
)

$resp = $client->searchableSnapshots()->clearCache([
    "index" => "my-index",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/my-index/_searchable_snapshots/cache/clear"

client.searchableSnapshots().clearCache(c -> c
    .index("my-index")
);

Invalidate API keys Generally available; Added in 6.7.0

DELETE /_security/api_key

Api key auth Basic auth Bearer auth

This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.

To use this API, you must have at least the manage_security, manage_api_key, or manage_own_api_key cluster privileges. The manage_security privilege allows deleting any API key, including both REST and cross cluster API keys. The manage_api_key privilege allows deleting any REST API key, but not cross cluster API keys. The manage_own_api_key only allows deleting REST API keys that are owned by the user. In addition, with the manage_own_api_key privilege, an invalidation request must be issued in one of the three formats:

Set the parameter owner=true.
Or, set both username and realm_name to match the user's identity.
Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the ids field.

Required authorization

Cluster privileges: manage_api_key,manage_own_api_key

application/json

Body Required

id string
ids array[string]

A list of API key ids. This parameter cannot be used with any of name, realm_name, or username.
name string
owner boolean

Query API keys owned by the currently authenticated user. The realm_name or username parameters cannot be specified when this parameter is set to true as they are assumed to be the currently authenticated ones.

NOTE: At least one of ids, name, username, and realm_name must be specified if owner is false.

Default value is false.
realm_name string

The name of an authentication realm. This parameter cannot be used with either ids or name, or when owner flag is set to true.
username string

Responses

200 application/json
Hide response attributes Show response attributes object
- error_count number Required
  
  The number of errors that were encountered when invalidating the API keys.
- error_details array[object]
  
  Details about the errors. This field is not present in the response when error_count is 0.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide error_details attributes Show error_details attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
- invalidated_api_keys array[string] Required
  
  The IDs of the API keys that were invalidated as part of this request.
- previously_invalidated_api_keys array[string] Required
  
  The IDs of the API keys that were already invalidated.

DELETE /_security/api_key

DELETE /_security/api_key
{
  "ids" : [ "VuaCfGcBCdbkQm-e5aOx" ]
}

resp = client.security.invalidate_api_key(
    ids=[
        "VuaCfGcBCdbkQm-e5aOx"
    ],
)

const response = await client.security.invalidateApiKey({
  ids: ["VuaCfGcBCdbkQm-e5aOx"],
});

response = client.security.invalidate_api_key(
  body: {
    "ids": [
      "VuaCfGcBCdbkQm-e5aOx"
    ]
  }
)

$resp = $client->security()->invalidateApiKey([
    "body" => [
        "ids" => array(
            "VuaCfGcBCdbkQm-e5aOx",
        ),
    ],
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"ids":["VuaCfGcBCdbkQm-e5aOx"]}' "$ELASTICSEARCH_URL/_security/api_key"

client.security().invalidateApiKey(i -> i
    .ids("VuaCfGcBCdbkQm-e5aOx")
);

Request examples

Run `DELETE /_security/api_key` to invalidate the API keys identified by ID.

{
  "ids" : [ "VuaCfGcBCdbkQm-e5aOx" ]
}

Run `DELETE /_security/api_key` to invalidate the API keys identified by name.

{
  "name" : "my-api-key"
}

Run `DELETE /_security/api_key` to invalidate all API keys for the `native1` realm.

{
  "realm_name" : "native1"
}

Run `DELETE /_security/api_key` to invalidate all API keys for the user `myuser` in all realms.

{
  "username" : "myuser"
}

Run `DELETE /_security/api_key` to invalidate the API keys identified by ID if they are owned by the currently authenticated user.

{
  "ids" : ["VuaCfGcBCdbkQm-e5aOx"],
  "owner" : "true"
}

Run `DELETE /_security/api_key` to invalidate all API keys for the user `myuser` in the `native1` realm .

{
  "username" : "myuser",
  "realm_name" : "native1"
}

Response examples (200)

A successful response from `DELETE /_security/api_key`.

{
  "invalidated_api_keys": [ 
    "api-key-id-1"
  ],
  "previously_invalidated_api_keys": [ 
    "api-key-id-2",
    "api-key-id-3"
  ],
  "error_count": 2, 
  "error_details": [ 
    {
      "type": "exception",
      "reason": "error occurred while invalidating api keys",
      "caused_by": {
        "type": "illegal_argument_exception",
        "reason": "invalid api key id"
      }
    },
    {
      "type": "exception",
      "reason": "error occurred while invalidating api keys",
      "caused_by": {
        "type": "illegal_argument_exception",
        "reason": "invalid api key id"
      }
    }
  ]
}

Create a service account token Generally available

POST /_security/service/{namespace}/{service}/credential/token/{name}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

POST /_security/service/{namespace}/{service}/credential/token

PUT /_security/service/{namespace}/{service}/credential/token/{name}

POST /_security/service/{namespace}/{service}/credential/token/{name}

Create a service accounts token for access without requiring basic authentication.

NOTE: Service account tokens never expire. You must actively delete them if they are no longer needed.

Required authorization

Cluster privileges: manage_service_account

External documentation

Path parameters

namespace string Required

The name of the namespace, which is a top-level grouping of service accounts.
service string Required

The name of the service.
name string Required

The name for the service account token. If omitted, a random name will be generated.

Token names must be at least one and no more than 256 characters. They can contain alphanumeric characters (a-z, A-Z, 0-9), dashes (-), and underscores (_), but cannot begin with an underscore.

NOTE: Token names must be unique in the context of the associated service account. They must also be globally unique with their fully qualified names, which are comprised of the service account principal and token name, such as <namespace>/<service>/<token-name>.

Query parameters

refresh string

If true then refresh the affected shards to make this operation visible to search, if wait_for (the default) then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

Values are true, false, or wait_for.

Responses

200 application/json
Hide response attributes Show response attributes object
- created boolean Required
- token object Required
  
  Hide token attributes Show token attributes object
  
  name string Required
  
  value string Required

POST /_security/service/{namespace}/{service}/credential/token/{name}

POST /_security/service/elastic/fleet-server/credential/token/token1

resp = client.security.create_service_token(
    namespace="elastic",
    service="fleet-server",
    name="token1",
)

const response = await client.security.createServiceToken({
  namespace: "elastic",
  service: "fleet-server",
  name: "token1",
});

response = client.security.create_service_token(
  namespace: "elastic",
  service: "fleet-server",
  name: "token1"
)

$resp = $client->security()->createServiceToken([
    "namespace" => "elastic",
    "service" => "fleet-server",
    "name" => "token1",
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_security/service/elastic/fleet-server/credential/token/token1"

client.security().createServiceToken(c -> c
    .name("token1")
    .namespace("elastic")
    .service("fleet-server")
);

Response examples (200)

A successful response from `POST /_security/service/elastic/fleet-server/credential/token/token1`. The response includes the service account token, its name, and its secret value as a bearer token.

{
  "created": true,
  "token": {
    "name": "token1",
    "value": "AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" 
  }
}

Logout of OpenID Connect Generally available

POST /_security/oidc/logout

Api key auth Basic auth Bearer auth

Invalidate an access token and a refresh token that were generated as a response to the /_security/oidc/authenticate API.

If the OpenID Connect authentication realm in Elasticsearch is accordingly configured, the response to this call will contain a URI pointing to the end session endpoint of the OpenID Connect Provider in order to perform single logout.

Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

application/json

Body Required

token string Required

The access token to be invalidated.
refresh_token string

The refresh token to be invalidated.

Responses

200 application/json
Hide response attribute Show response attribute object
- redirect string Required
  
  A URI that points to the end session endpoint of the OpenID Connect Provider with all the parameters of the logout request as HTTP GET parameters.

POST /_security/oidc/logout

POST /_security/oidc/logout
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

resp = client.security.oidc_logout(
    token="dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
    refresh_token="vLBPvmAB6KvwvJZr27cS",
)

const response = await client.security.oidcLogout({
  token:
    "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  refresh_token: "vLBPvmAB6KvwvJZr27cS",
});

response = client.security.oidc_logout(
  body: {
    "token": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
    "refresh_token": "vLBPvmAB6KvwvJZr27cS"
  }
)

$resp = $client->security()->oidcLogout([
    "body" => [
        "token" => "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
        "refresh_token" => "vLBPvmAB6KvwvJZr27cS",
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"token":"dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==","refresh_token":"vLBPvmAB6KvwvJZr27cS"}' "$ELASTICSEARCH_URL/_security/oidc/logout"

client.security().oidcLogout(o -> o
    .refreshToken("vLBPvmAB6KvwvJZr27cS")
    .token("dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==")
);

Request example

Run `POST /_security/oidc/logout` to perform the logout.

{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

Response examples (200)

A successful response from `POST /_security/oidc/logout`, which contains the URI pointing to the End Session Endpoint of the OpenID Connect Provider with all the parameters of the Logout Request as HTTP GET parameters.

{
  "redirect" : "https://op-provider.org/logout?id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c&post_logout_redirect_uri=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Foidc-kibana.elastic.co%2Floggedout&state=lGYK0EcSLjqH6pkT5EVZjC6eIW5YCGgywj2sxROO"
}

Create or update an autoscaling policy Generally available; Added in 7.11.0

Path parameters

Query parameters

Body Required

Responses

Compact and aligned text (CAT)

Get aliases Generally available

Required authorization

Path parameters

Query parameters

Responses

Get component templates Generally available; Added in 5.1.0

Required authorization

Path parameters

Query parameters

Responses

version string | null Required

Get a document count Generally available

Required authorization

Path parameters

Query parameters

Responses

epoch number | string

Get index template information Generally available; Added in 5.2.0

Required authorization

Path parameters

Query parameters

Responses

version string | null

Update the cluster settings Generally available

Query parameters

Body Required

Responses

Get the cluster health Generally available; Added in 8.7.0

Path parameters

Query parameters

Responses

Claim a connector sync job Technical preview

Path parameters

Body Required

Responses

Update the connector API key ID Beta; Added in 8.12.0

Path parameters

Body Required

Responses

Update data stream settings Generally available; Added in 9.1.0

Required authorization

Path parameters

Query parameters

Body Required

Responses

Promote a data stream Generally available; Added in 7.9.0

Path parameters

Query parameters

Responses

Create or update a document in an index Generally available

Path parameters

Query parameters

Body Required

Responses

reason string | null

Get EQL search results Generally available; Added in 7.9.0

Path parameters

Query parameters

Body Required

filter object | array[object]

fields object | array[object]

source string | object

lang string

Responses

reason string | null

ES|QL

Run an async ES|QL query Generally available; Added in 8.13.0

Required authorization

Query parameters

Body Required

Responses

Get the features Generally available; Added in 7.12.0

Query parameters

Responses