Elasticsearch APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example:
curl -X GET "${ES_URL}/_cat/indices?v=true" \
-H "Authorization: ApiKey ${API_KEY}"
For more information about where to find API keys for the Elasticsearch endpoint (${ES_URL}) for a project, go to Get started with Elasticsearch Serverless.
The associated data stream is also deleted.
The name of the analytics collection to be deleted
curl \
--request DELETE 'http://api.example.com/_application/analytics/{name}' \
--header "Authorization: $API_KEY"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.
List of columns to appear in the response. Supports simple wildcards.
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.
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.
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.
curl \
--request GET 'http://api.example.com/_cat/aliases' \
--header "Authorization: $API_KEY"[
{
"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 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.
curl \
--request GET 'http://api.example.com/_cat/count' \
--header "Authorization: $API_KEY"[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "120"
}
][
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "121"
}
]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.
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.
curl \
--request GET 'http://api.example.com/_cat/count/{index}' \
--header "Authorization: $API_KEY"[
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "120"
}
][
{
"epoch": "1475868259",
"timestamp": "15:24:20",
"count": "121"
}
]curl \
--request GET 'http://api.example.com/_cat' \
--header "Authorization: $API_KEY"The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index.
Connectors are Elasticsearch integrations for syncing content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure.
This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
This API requires the manage_connector privilege or, for read-only endpoints, the monitor_connector privilege.
Update the last_seen field in the connector and set it to the current timestamp.
The unique identifier of the connector to be checked in
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_check_in' \
--header "Authorization: $API_KEY"{
"result": "updated"
}Cancel a connector sync job, which sets the status to cancelling and updates cancellation_requested_at to the current time.
The connector service is then responsible for setting the status of connector sync jobs to cancelled.
The unique identifier of the connector sync job
curl \
--request PUT 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_cancel' \
--header "Authorization: $API_KEY"The unique identifier of the connector to be updated
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_service_type' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service_type\": \"sharepoint_online\"\n}"'{
"service_type": "sharepoint_online"
}{
"result": "updated"
}Deletes one or more data streams and their backing indices.
Comma-separated list of data streams to delete. Wildcard (*) expressions are supported.
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.
Type of data stream that wildcard patterns can match. Supports comma-separated values,such as open,hidden.
curl \
--request DELETE 'http://api.example.com/_data_stream/{name}' \
--header "Authorization: $API_KEY"Converts an index alias to a data stream.
You must have a matching index template that is data stream enabled.
The alias must meet the following criteria:
The alias must have a write index;
All indices for the alias must have a @timestamp field mapping of a date or date_nanos field type;
The alias must not have any filters;
The alias must not use custom routing.
If successful, the request removes the alias and creates a data stream with the same name.
The indices for the alias become hidden backing indices for the stream.
The write index for the alias becomes the write index for the stream.
Name of the index alias to convert to a data stream.
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.
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request POST 'http://api.example.com/_data_stream/_migrate/{name}' \
--header "Authorization: $API_KEY"Performs one or more data stream modification actions in a single atomic operation.
curl \
--request POST 'http://api.example.com/_data_stream/_modify' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"actions":[{"add_backing_index":{"data_stream":"string","index":"string"},"remove_backing_index":{"data_stream":"string","index":"string"}}]}'Get the source of a document. For example:
GET my-index-000001/_source/1
You can use the source filtering parameters to control which parts of the _source are returned:
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
A comma-separated list of stored fields to return as part of a hit.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Values are internal, external, external_gte, or force.
curl \
--request GET 'http://api.example.com/{index}/_source/{id}' \
--header "Authorization: $API_KEY"Check whether a document source exists in an index. For example:
HEAD my-index-000001/_source/1
A document's source is not available if it is disabled in the mapping.
The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
If true, the request is real-time as opposed to near-real-time.
If true, the request refreshes the relevant shards before retrieving the document.
Setting it to true should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing).
A custom value used to route operations to a specific shard.
Indicates whether to return the _source field (true or false) or lists the fields to return.
A comma-separated list of source fields to exclude in the response.
A comma-separated list of source fields to include in the response.
The version number for concurrency control. It must match the current version of the document for the request to succeed.
The version type.
Values are internal, external, external_gte, or force.
curl \
--request HEAD 'http://api.example.com/{index}/_source/{id}' \
--header "Authorization: $API_KEY"Get the current status and available results for an async EQL search or a stored synchronous EQL search.
Identifier for the search.
Period for which the search and its results are stored on the cluster. Defaults to the keep_alive value set by the search’s EQL search API request.
Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.
curl \
--request GET 'http://api.example.com/_eql/search/{id}' \
--header "Authorization: $API_KEY"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.
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.
Valid values are: all, open, closed, hidden, none.
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.
curl \
--request GET 'http://api.example.com/_alias' \
--header "Authorization: $API_KEY"A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.
By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds.
You can change this default interval with the index.refresh_interval setting.
Refresh requests are synchronous and do not return a response until the refresh operation completes.
Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.
If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option.
This option ensures the indexing operation waits for a periodic refresh before running the search.
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.
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.
Valid values are: all, open, closed, hidden, none.
curl \
--request POST 'http://api.example.com/_refresh' \
--header "Authorization: $API_KEY"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.
If true, the validation is executed on all shards instead of one random shard per index.
Analyzer to use for the query string.
This parameter can only be used when the q query string parameter is specified.
If true, wildcard and prefix queries are analyzed.
The default operator for query string query: AND or OR.
Values are and, AND, or, or OR.
Field to use as default where no field prefix is given in the query string.
This parameter can only be used when the q query string parameter is specified.
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.
Valid values are: all, open, closed, hidden, none.
If true, the response returns detailed information if an error has occurred.
If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
If true, returns a more detailed explanation showing the actual Lucene query that will be executed.
Query in the Lucene query string syntax.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
curl \
--request GET 'http://api.example.com/_validate/query' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":{}}'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.
If true, the validation is executed on all shards instead of one random shard per index.
Analyzer to use for the query string.
This parameter can only be used when the q query string parameter is specified.
If true, wildcard and prefix queries are analyzed.
The default operator for query string query: AND or OR.
Values are and, AND, or, or OR.
Field to use as default where no field prefix is given in the query string.
This parameter can only be used when the q query string parameter is specified.
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.
Valid values are: all, open, closed, hidden, none.
If true, the response returns detailed information if an error has occurred.
If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
If true, returns a more detailed explanation showing the actual Lucene query that will be executed.
Query in the Lucene query string syntax.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
curl \
--request POST 'http://api.example.com/_validate/query' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":{}}'Inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
The task type
Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.
The inference Id
curl \
--request GET 'http://api.example.com/_inference/{task_type}/{inference_id}' \
--header "Authorization: $API_KEY"This API enables you to use machine learning models to perform specific tasks on data that you provide as an input. It returns a response with the results of the tasks. The inference endpoint you use can perform one specific task that has been defined when the endpoint was created with the create inference API.
For details about using this API with a service, such as Amazon Bedrock, Anthropic, or HuggingFace, refer to the service-specific documentation.
The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
The type of inference task that the model performs.
Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.
The unique identifier for the inference endpoint.
The amount of time to wait for the inference request to complete.
The query input, which is required only for the rerank task.
It is not required for other tasks.
The text on which you want to perform the inference task. It can be a single string or an array.
Inference endpoints for the completion task type currently only support a single string as input.
curl \
--request POST 'http://api.example.com/_inference/{task_type}/{inference_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":"string","input":"string","task_settings":{}}'Create an inference endpoint to perform an inference task with the openai service or openai compatible APIs.
When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running.
After creating the endpoint, wait for the model deployment to complete before using it.
To verify the deployment status, use the get trained model statistics API.
Look for "state": "fully_allocated" in the response and ensure that the "allocation_count" matches the "target_allocation_count".
Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.
The type of the inference task that the model will perform.
NOTE: The chat_completion task type only supports streaming and only through the _stream API.
Values are chat_completion, completion, or text_embedding.
The unique identifier of the inference endpoint.
Value is openai.
curl \
--request PUT 'http://api.example.com/_inference/{task_type}/{openai_inference_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service\": \"openai\",\n \"service_settings\": {\n \"api_key\": \"OpenAI-API-Key\",\n \"model_id\": \"text-embedding-3-small\",\n \"dimensions\": 128\n }\n}"'{
"service": "openai",
"service_settings": {
"api_key": "OpenAI-API-Key",
"model_id": "text-embedding-3-small",
"dimensions": 128
}
}{
"service": "amazonbedrock",
"service_settings": {
"access_key": "AWS-access-key",
"secret_key": "AWS-secret-key",
"region": "us-east-1",
"provider": "amazontitan",
"model": "amazon.titan-text-premier-v1:0"
}
}Create an inference endpoint to perform an inference task with the voyageai service.
Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.
The type of the inference task that the model will perform.
Values are text_embedding or rerank.
The unique identifier of the inference endpoint.
Value is voyageai.
curl \
--request PUT 'http://api.example.com/_inference/{task_type}/{voyageai_inference_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service\": \"voyageai\",\n \"service_settings\": {\n \"model_id\": \"voyage-3-large\",\n \"dimensions\": 512\n }\n}"'{
"service": "voyageai",
"service_settings": {
"model_id": "voyage-3-large",
"dimensions": 512
}
}{
"service": "voyageai",
"service_settings": {
"model_id": "rerank-2"
}
}Ingest APIs enable you to manage tasks and resources related to ingest pipelines and processors.
Extract structured fields out of a single text field within a document. You must choose which field to extract matched fields from, as well as the grok pattern you expect will match. A grok pattern is like a regular expression that supports aliased expressions that can be reused.
curl \
--request GET 'http://api.example.com/_ingest/processor/grok' \
--header "Authorization: $API_KEY"Logstash APIs enable you to manage pipelines that are used by Logstash Central Management.
Get pipelines that are used for Logstash Central Management.
curl \
--request GET 'http://api.example.com/_logstash/pipeline' \
--header "Authorization: $API_KEY"{
"my_pipeline": {
"description": "Sample pipeline for illustration purposes",
"last_modified": "2021-01-02T02:50:51.250Z",
"pipeline_metadata": {
"type": "logstash_pipeline",
"version": "1"
},
"username": "elastic",
"pipeline": "input {}\\n filter { grok {} }\\n output {}",
"pipeline_settings": {
"pipeline.workers": 1,
"pipeline.batch.size": 125,
"pipeline.batch.delay": 50,
"queue.type": "memory",
"queue.max_bytes": "1gb",
"queue.checkpoint.writes": 1024
}
}
}A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using _all or * or by omitting the calendar identifier.
curl \
--request GET 'http://api.example.com/_ml/calendars/{calendar_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'A string that uniquely identifies a calendar.
An array of anomaly detection job identifiers.
A description of the calendar.
curl \
--request PUT 'http://api.example.com/_ml/calendars/{calendar_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"job_ids":["string"],"description":"string"}'curl \
--request POST 'http://api.example.com/_ml/calendars' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'You can get statistics for multiple datafeeds in a single API request by
using a comma-separated list of datafeeds or a wildcard expression. You can
get statistics for all datafeeds by using _all, by specifying * as the
<feed_id>, or by omitting the <feed_id>. If the datafeed is stopped, the
only information you receive is the datafeed_id and the state.
This API returns a maximum of 10,000 datafeeds.
Identifier for the datafeed. It can be a datafeed identifier or a wildcard expression. If you do not specify one of these options, the API returns information about all datafeeds.
Specifies what to do when the request:
_all string or no identifiers and there are no matches.The default value is true, which returns an empty datafeeds array
when there are no matches and the subset of results when there are
partial matches. If this parameter is false, the request returns a
404 status code when there are no matches or only partial matches.
curl \
--request GET 'http://api.example.com/_ml/datafeeds/{datafeed_id}/_stats' \
--header "Authorization: $API_KEY"All model state and results are deleted. The job is ready to start over as if it had just been created. It is not currently possible to reset multiple jobs using wildcards or a comma separated list.
The ID of the job to reset.
Should this request wait until the operation has completed before returning.
Specifies whether annotations that have been added by the user should be deleted along with any auto-generated annotations when the job is reset.
curl \
--request POST 'http://api.example.com/_ml/anomaly_detectors/{job_id}/_reset' \
--header "Authorization: $API_KEY"Updates the description of a filter, adds items, or removes items from the list.
A string that uniquely identifies a filter.
The items to add to the filter.
A description for the filter.
The items to remove from the filter.
curl \
--request POST 'http://api.example.com/_ml/filters/{filter_id}/_update' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"add_items":["string"],"description":"string","remove_items":["string"]}'A data frame analytics job can be started and stopped multiple times
throughout its lifecycle.
If the destination index does not exist, it is created automatically the
first time you start the data frame analytics job. The
index.number_of_shards and index.number_of_replicas settings for the
destination index are copied from the source index. If there are multiple
source indices, the destination index copies the highest setting values. The
mappings for the destination index are also copied from the source indices.
If there are any mapping conflicts, the job fails to start.
If the destination index exists, it is used as is. You can therefore set up
the destination index in advance with custom settings and mappings.
Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.
Controls the amount of time to wait until the data frame analytics job starts.
curl \
--request POST 'http://api.example.com/_ml/data_frame/analytics/{id}/_start' \
--header "Authorization: $API_KEY"This API deletes an existing model alias that refers to a trained model. If
the model alias is missing or refers to a model other than the one identified
by the model_id, this API returns an error.
The trained model ID to which the model alias refers.
The model alias to delete.
curl \
--request DELETE 'http://api.example.com/_ml/trained_models/{model_id}/model_aliases/{model_alias}' \
--header "Authorization: $API_KEY"{
"acknowledged": true
}The definition part for the model. Must be a base64 encoded string.
The total uncompressed definition length in bytes. Not base64 encoded.
The total number of parts that will be uploaded. Must be greater than 0.
curl \
--request PUT 'http://api.example.com/_ml/trained_models/{model_id}/definition/{part}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"definition":"string","total_definition_length":42.0,"total_parts":42.0}'The unique identifier of the trained model.
Specifies what to do when the request: contains wildcard expressions and there are no deployments 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 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.
Forcefully stops the deployment, even if it is used by ingest pipelines. You can't use these pipelines until you restart the model deployment.
curl \
--request POST 'http://api.example.com/_ml/trained_models/{model_id}/deployment/_stop' \
--header "Authorization: $API_KEY"Deletes a stored script or search template.
The identifier for the stored script or search template.
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.
It can also be set to -1 to indicate that the request should never timeout.
The period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.
It can also be set to -1 to indicate that the request should never timeout.
curl \
--request DELETE 'http://api.example.com/_scripts/{id}' \
--header "Authorization: $API_KEY"If the asynchronous search is still running, it is cancelled.
Otherwise, the saved search results are deleted.
If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the cancel_task cluster privilege.
A unique identifier for the async search.
curl \
--request DELETE 'http://api.example.com/_async_search/{id}' \
--header "Authorization: $API_KEY"Clear the search context and results for a scrolling search.
A comma-separated list of scroll IDs to clear.
To clear all scroll IDs, use _all.
IMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter.
curl \
--request DELETE 'http://api.example.com/_search/scroll/{scroll_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"scroll_id\": \"DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==\"\n}"'{
"scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}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.
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.
The analyzer to use for the query string.
This parameter can be used only when the q query string parameter is specified.
If true, wildcard and prefix queries are analyzed.
This parameter can be used only when the q query string parameter is specified.
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.
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.
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.
If true, concrete, expanded, or aliased indices are ignored when frozen.
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.
The minimum _score value that documents must have to be included in the result.
The node or shard the operation should be performed on. By default, it is random.
A custom value used to route operations to a specific shard.
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.
The query in Lucene query string syntax. This parameter cannot be used with a request body.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
curl \
--request POST 'http://api.example.com/_count' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\" : {\n \"term\" : { \"user.id\" : \"kimchy\" }\n }\n}"'{
"query" : {
"term" : { "user.id" : "kimchy" }
}
}{
"count": 1,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
}
}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.
A comma-separated list of index names to open point in time; use _all or empty string to perform the operation on all indices
Extend the length of time that the point in time persists.
The node or shard the operation should be performed on. By default, it is random.
A custom value that is used to route operations to a specific shard.
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. Valid values are: all, open, closed, hidden, none.
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.
Maximum number of concurrent shard requests that each sub-search request executes per node.
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
curl \
--request POST 'http://api.example.com/{index}/_pit?keep_alive=string' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"index_filter":{}}'{
"id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=",
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
}
}Determine whether the specified user has a specified list of privileges. All users can use this API, but only to determine their own privileges. To check the privileges of other users, you must use the run as feature.
Username
A list of the cluster privileges that you want to check.
curl \
--request GET 'http://api.example.com/_security/user/{user}/_has_privileges' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"cluster\": [ \"monitor\", \"manage\" ],\n \"index\" : [\n {\n \"names\": [ \"suppliers\", \"products\" ],\n \"privileges\": [ \"read\" ]\n },\n {\n \"names\": [ \"inventory\" ],\n \"privileges\" : [ \"read\", \"write\" ]\n }\n ],\n \"application\": [\n {\n \"application\": \"inventory_manager\",\n \"privileges\" : [ \"read\", \"data:write/inventory\" ],\n \"resources\" : [ \"product/1852563\" ]\n }\n ]\n}"'{
"cluster": [ "monitor", "manage" ],
"index" : [
{
"names": [ "suppliers", "products" ],
"privileges": [ "read" ]
},
{
"names": [ "inventory" ],
"privileges" : [ "read", "write" ]
}
],
"application": [
{
"application": "inventory_manager",
"privileges" : [ "read", "data:write/inventory" ],
"resources" : [ "product/1852563" ]
}
]
}{
"username": "rdeniro",
"has_all_requested" : false,
"cluster" : {
"monitor" : true,
"manage" : false
},
"index" : {
"suppliers" : {
"read" : true
},
"products" : {
"read" : true
},
"inventory" : {
"read" : true,
"write" : false
}
},
"application" : {
"inventory_manager" : {
"product/1852563" : {
"read": false,
"data:write/inventory": false
}
}
}
}Elasticsearch's SQL APIs enable you to run SQL queries on Elasticsearch indices and data streams.
Delete an async SQL search or a stored synchronous SQL search. If the search is still running, the API cancels it.
If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:
cancel_task cluster privilege.The identifier for the search.
curl \
--request DELETE 'http://api.example.com/_sql/async/delete/{id}' \
--header "Authorization: $API_KEY"Get the current status of an async SQL search or a stored synchronous SQL search.
The identifier for the search.
curl \
--request GET 'http://api.example.com/_sql/async/status/{id}' \
--header "Authorization: $API_KEY"