Delete a behavioral analytics collection
Deprecated
Technical preview
The associated data stream is also deleted.
Path parameters
-
name
string Required The name of the analytics collection to be deleted
DELETE _application/analytics/my_analytics_collection/
curl \
--request DELETE 'http://api.example.com/_application/analytics/{name}' \
--header "Authorization: $API_KEY"
Get behavioral analytics collections
Deprecated
Technical preview
GET _application/analytics/my*
curl \
--request GET 'http://api.example.com/_application/analytics' \
--header "Authorization: $API_KEY"
{
"my_analytics_collection": {
"event_data_stream": {
"name": "behavioral_analytics-events-my_analytics_collection"
}
},
"my_analytics_collection2": {
"event_data_stream": {
"name": "behavioral_analytics-events-my_analytics_collection2"
}
}
}
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 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
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
.Values are
all
,open
,closed
,hidden
, ornone
. -
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
or0
.
GET _cat/aliases?format=json&v=true
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 a document count
Generally available
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
GET /_cat/count/my-index-000001?v=true&format=json
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"
}
]
curl \
--request GET 'http://api.example.com/_cat' \
--header "Authorization: $API_KEY"
Get data frame analytics jobs
Generally available
Get configuration and usage information about data frame analytics jobs.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API.
Required authorization
- Cluster privileges:
monitor_ml
Path parameters
-
id
string Required The ID of the data frame analytics to fetch
Query parameters
-
allow_no_match
boolean Whether to ignore if a wildcard expression matches no configs. (This includes
_all
string or when no configs have been specified) -
bytes
string The unit in which to display byte values
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
h
string | array[string] Comma-separated list of column names to display.
Values are
assignment_explanation
,ae
,create_time
,ct
,createTime
,description
,d
,dest_index
,di
,destIndex
,failure_reason
,fr
,failureReason
,id
,model_memory_limit
,mml
,modelMemoryLimit
,node.address
,na
,nodeAddress
,node.ephemeral_id
,ne
,nodeEphemeralId
,node.id
,ni
,nodeId
,node.name
,nn
,nodeName
,progress
,p
,source_index
,si
,sourceIndex
,state
,s
,type
,t
,version
, orv
. -
s
string | array[string] Comma-separated list of column names or column aliases used to sort the response.
Values are
assignment_explanation
,ae
,create_time
,ct
,createTime
,description
,d
,dest_index
,di
,destIndex
,failure_reason
,fr
,failureReason
,id
,model_memory_limit
,mml
,modelMemoryLimit
,node.address
,na
,nodeAddress
,node.ephemeral_id
,ne
,nodeEphemeralId
,node.id
,ni
,nodeId
,node.name
,nn
,nodeName
,progress
,p
,source_index
,si
,sourceIndex
,state
,s
,type
,t
,version
, orv
. -
time
string Unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
GET _cat/ml/data_frame/analytics?v=true&format=json
curl \
--request GET 'http://api.example.com/_cat/ml/data_frame/analytics/{id}' \
--header "Authorization: $API_KEY"
[
{
"id": "classifier_job_1",
"type": "classification",
"create_time": "2020-02-12T11:49:09.594Z",
"state": "stopped"
},
{
"id": "classifier_job_2",
"type": "classification",
"create_time": "2020-02-12T11:49:14.479Z",
"state": "stopped"
},
{
"id": "classifier_job_3",
"type": "classification",
"create_time": "2020-02-12T11:49:16.928Z",
"state": "stopped"
},
{
"id": "classifier_job_4",
"type": "classification",
"create_time": "2020-02-12T11:49:19.127Z",
"state": "stopped"
},
{
"id": "classifier_job_5",
"type": "classification",
"create_time": "2020-02-12T11:49:21.349Z",
"state": "stopped"
}
]
Get datafeeds
Generally available
Get configuration and usage information about datafeeds.
This API returns a maximum of 10,000 datafeeds.
If the Elasticsearch security features are enabled, you must have monitor_ml
, monitor
, manage_ml
, or manage
cluster privileges to use this API.
IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get datafeed statistics API.
Required authorization
- Cluster privileges:
monitor_ml
Query parameters
-
allow_no_match
boolean Specifies what to do when the request:
- Contains wildcard expressions and there are no datafeeds 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
, the API returns an empty datafeeds array when there are no matches and the subset of results when there are partial matches. Iffalse
, the API returns a 404 status code when there are no matches or only partial matches. -
h
string | array[string] Comma-separated list of column names to display.
Values are
ae
,assignment_explanation
,bc
,buckets.count
,bucketsCount
,id
,na
,node.address
,nodeAddress
,ne
,node.ephemeral_id
,nodeEphemeralId
,ni
,node.id
,nodeId
,nn
,node.name
,nodeName
,sba
,search.bucket_avg
,searchBucketAvg
,sc
,search.count
,searchCount
,seah
,search.exp_avg_hour
,searchExpAvgHour
,st
,search.time
,searchTime
,s
, orstate
. -
s
string | array[string] Comma-separated list of column names or column aliases used to sort the response.
Values are
ae
,assignment_explanation
,bc
,buckets.count
,bucketsCount
,id
,na
,node.address
,nodeAddress
,ne
,node.ephemeral_id
,nodeEphemeralId
,ni
,node.id
,nodeId
,nn
,node.name
,nodeName
,sba
,search.bucket_avg
,searchBucketAvg
,sc
,search.count
,searchCount
,seah
,search.exp_avg_hour
,searchExpAvgHour
,st
,search.time
,searchTime
,s
, orstate
. -
time
string The unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
.
GET _cat/ml/datafeeds?v=true&format=json
curl \
--request GET 'http://api.example.com/_cat/ml/datafeeds' \
--header "Authorization: $API_KEY"
[
{
"id": "datafeed-high_sum_total_sales",
"state": "stopped",
"buckets.count": "743",
"search.count": "7"
},
{
"id": "datafeed-low_request_rate",
"state": "stopped",
"buckets.count": "1457",
"search.count": "3"
},
{
"id": "datafeed-response_code_rates",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
},
{
"id": "datafeed-url_scanning",
"state": "stopped",
"buckets.count": "1460",
"search.count": "18"
}
]
Get transform information
Generally available
Get configuration and usage information about transforms.
CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get transform statistics API.
Required authorization
- Cluster privileges:
monitor_transform
Path parameters
-
transform_id
string Required A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.
Query parameters
-
allow_no_match
boolean Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the
_all
string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. Iftrue
, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. Iffalse
, the request returns a 404 status code when there are no matches or only partial matches. -
from
number Skips the specified number of transforms.
-
h
string | array[string] Comma-separated list of column names to display.
Values are
changes_last_detection_time
,cldt
,checkpoint
,cp
,checkpoint_duration_time_exp_avg
,cdtea
,checkpointTimeExpAvg
,checkpoint_progress
,c
,checkpointProgress
,create_time
,ct
,createTime
,delete_time
,dtime
,description
,d
,dest_index
,di
,destIndex
,documents_deleted
,docd
,documents_indexed
,doci
,docs_per_second
,dps
,documents_processed
,docp
,frequency
,f
,id
,index_failure
,if
,index_time
,itime
,index_total
,it
,indexed_documents_exp_avg
,idea
,last_search_time
,lst
,lastSearchTime
,max_page_search_size
,mpsz
,pages_processed
,pp
,pipeline
,p
,processed_documents_exp_avg
,pdea
,processing_time
,pt
,reason
,r
,search_failure
,sf
,search_time
,stime
,search_total
,st
,source_index
,si
,sourceIndex
,state
,s
,transform_type
,tt
,trigger_count
,tc
,version
, orv
. -
s
string | array[string] Comma-separated list of column names or column aliases used to sort the response.
Values are
changes_last_detection_time
,cldt
,checkpoint
,cp
,checkpoint_duration_time_exp_avg
,cdtea
,checkpointTimeExpAvg
,checkpoint_progress
,c
,checkpointProgress
,create_time
,ct
,createTime
,delete_time
,dtime
,description
,d
,dest_index
,di
,destIndex
,documents_deleted
,docd
,documents_indexed
,doci
,docs_per_second
,dps
,documents_processed
,docp
,frequency
,f
,id
,index_failure
,if
,index_time
,itime
,index_total
,it
,indexed_documents_exp_avg
,idea
,last_search_time
,lst
,lastSearchTime
,max_page_search_size
,mpsz
,pages_processed
,pp
,pipeline
,p
,processed_documents_exp_avg
,pdea
,processing_time
,pt
,reason
,r
,search_failure
,sf
,search_time
,stime
,search_total
,st
,source_index
,si
,sourceIndex
,state
,s
,transform_type
,tt
,trigger_count
,tc
,version
, orv
. -
time
string The unit used to display time values.
Values are
nanos
,micros
,ms
,s
,m
,h
, ord
. -
size
number The maximum number of transforms to obtain.
GET /_cat/transforms?v=true&format=json
curl \
--request GET 'http://api.example.com/_cat/transforms/{transform_id}' \
--header "Authorization: $API_KEY"
[
{
"id" : "ecommerce_transform",
"state" : "started",
"checkpoint" : "1",
"documents_processed" : "705",
"checkpoint_progress" : "100.00",
"changes_last_detection_time" : null
}
]
Check in a connector
Technical preview
Update the last_seen
field in the connector and set it to the current timestamp.
Path parameters
-
connector_id
string Required The unique identifier of the connector to be checked in
PUT _connector/my-connector/_check_in
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_check_in' \
--header "Authorization: $API_KEY"
{
"result": "updated"
}
Path parameters
-
connector_sync_job_id
string Required The unique identifier of the connector sync job
GET _connector/_sync_job/my-connector-sync-job
curl \
--request GET 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}' \
--header "Authorization: $API_KEY"
Create a connector sync job
Beta
Create a connector sync job document in the internal index and initialize its counters and timestamps with default values.
Body
Required
-
id
string Required -
job_type
string Values are
full
,incremental
, oraccess_control
. -
trigger_method
string Values are
on_demand
orscheduled
.
POST _connector/_sync_job
{
"id": "connector-id",
"job_type": "full",
"trigger_method": "on_demand"
}
curl \
--request POST 'http://api.example.com/_connector/_sync_job' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"id\": \"connector-id\",\n \"job_type\": \"full\",\n \"trigger_method\": \"on_demand\"\n}"'
{
"id": "connector-id",
"job_type": "full",
"trigger_method": "on_demand"
}
Update the connector draft filtering validation
Technical preview
Update the draft filtering validation info for a connector.
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
Body
Required
-
validation
object Required
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_filtering/_validation' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"validation":{"errors":[{"ids":["string"],"messages":["string"]}],"state":"edited"}}'
Update the connector index name
Beta
Update the index_name
field of a connector, specifying the index where the data ingested by the connector is stored.
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
Body
Required
index_name
string | null
PUT _connector/my-connector/_index_name
{
"index_name": "data-from-my-google-drive"
}
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_index_name' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"index_name\": \"data-from-my-google-drive\"\n}"'
{
"index_name": "data-from-my-google-drive"
}
{
"result": "updated"
}
Path parameters
-
connector_id
string Required The unique identifier of the connector to be updated
Body
Required
-
name
string -
description
string
PUT _connector/my-connector/_name
{
"name": "Custom connector",
"description": "This is my customized connector"
}
curl \
--request PUT 'http://api.example.com/_connector/{connector_id}/_name' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"name\": \"Custom connector\",\n \"description\": \"This is my customized connector\"\n}"'
{
"name": "Custom connector",
"description": "This is my customized connector"
}
{
"result": "updated"
}
Get data streams
Generally available
Get information about one or more data streams.
Required authorization
- Index privileges:
view_index_metadata
Path parameters
-
name
string | array[string] Required Comma-separated list of data stream names used to limit the request. Wildcard (
*
) expressions are supported. If omitted, all data streams are returned.
Query parameters
-
expand_wildcards
string | array[string] Type of data stream that wildcard patterns can match. Supports comma-separated values, such as
open,hidden
.Values are
all
,open
,closed
,hidden
, ornone
. -
include_defaults
boolean If true, returns all relevant default configurations for the index 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
or0
. -
verbose
boolean Whether the maximum timestamp for each data stream should be calculated and returned.
GET _data_stream/my-data-stream
curl \
--request GET 'http://api.example.com/_data_stream/{name}' \
--header "Authorization: $API_KEY"
{
"data_streams": [
{
"name": "my-data-stream",
"timestamp_field": {
"name": "@timestamp"
},
"indices": [
{
"index_name": ".ds-my-data-stream-2099.03.07-000001",
"index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
},
{
"index_name": ".ds-my-data-stream-2099.03.08-000002",
"index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
}
],
"generation": 2,
"_meta": {
"my-meta-field": "foo"
},
"status": "GREEN",
"next_generation_managed_by": "Index Lifecycle Management",
"prefer_ilm": true,
"template": "my-index-template",
"ilm_policy": "my-lifecycle-policy",
"hidden": false,
"system": false,
"allow_custom_routing": false,
"replicated": false,
"rollover_on_write": false
},
{
"name": "my-data-stream-two",
"timestamp_field": {
"name": "@timestamp"
},
"indices": [
{
"index_name": ".ds-my-data-stream-two-2099.03.08-000001",
"index_uuid": "3liBu2SYS5axasRt6fUIpA",
"prefer_ilm": true,
"ilm_policy": "my-lifecycle-policy",
"managed_by": "Index Lifecycle Management"
}
],
"generation": 1,
"_meta": {
"my-meta-field": "foo"
},
"status": "YELLOW",
"next_generation_managed_by": "Index Lifecycle Management",
"prefer_ilm": true,
"template": "my-index-template",
"ilm_policy": "my-lifecycle-policy",
"hidden": false,
"system": false,
"allow_custom_routing": false,
"replicated": false,
"rollover_on_write": false
}
]
}
Delete data streams
Generally available
Deletes one or more data streams and their backing indices.
Required authorization
- Index privileges:
delete_index
Path parameters
-
name
string | array[string] Required Comma-separated list of data streams to delete. 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
or0
. -
expand_wildcards
string | array[string] Type of data stream that wildcard patterns can match. Supports comma-separated values,such as
open,hidden
.Values are
all
,open
,closed
,hidden
, ornone
.
DELETE _data_stream/my-data-stream
curl \
--request DELETE 'http://api.example.com/_data_stream/{name}' \
--header "Authorization: $API_KEY"
Bulk index or delete documents
Generally available
Perform multiple index
, create
, delete
, and update
actions in a single request.
This reduces overhead and can greatly increase indexing speed.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To use the
create
action, you must have thecreate_doc
,create
,index
, orwrite
index privilege. Data streams support only thecreate
action. - To use the
index
action, you must have thecreate
,index
, orwrite
index privilege. - To use the
delete
action, you must have thedelete
orwrite
index privilege. - To use the
update
action, you must have theindex
orwrite
index privilege. - To automatically create a data stream or index with a bulk API request, you must have the
auto_configure
,create_index
, ormanage
index privilege. - To make the result of a bulk operation visible to search using the
refresh
parameter, you must have themaintenance
ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
The actions are specified in the request body using a newline delimited JSON (NDJSON) structure:
action_and_meta_data\n
optional_source\n
action_and_meta_data\n
optional_source\n
....
action_and_meta_data\n
optional_source\n
The index
and create
actions expect a source on the next line and have the same semantics as the op_type
parameter in the standard index API.
A create
action fails if a document with the same ID already exists in the target
An index
action adds or replaces a document as necessary.
NOTE: Data streams support only the create
action.
To update or delete a document in a data stream, you must target the backing index containing the document.
An update
action expects that the partial doc, upsert, and script and its options are specified on the next line.
A delete
action does not expect a source on the next line and has the same semantics as the standard delete API.
NOTE: 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 NDJSON data to the _bulk
endpoint, use a Content-Type
header of application/json
or application/x-ndjson
.
Because this format uses literal newline characters (\n
) as delimiters, make sure that the JSON actions and sources are not pretty printed.
If you provide a target in the request path, it is used for any actions that don't explicitly specify an _index
argument.
A note on the format: the idea here is to make processing as fast as possible.
As some of the actions are redirected to other shards on other nodes, only action_meta_data
is parsed on the receiving node side.
Client libraries using this protocol should try and strive to do something similar on the client side, and reduce buffering as much as possible.
There is no "correct" number of actions to perform in a single bulk request. Experiment with different settings to find the optimal size for your particular workload. Note that Elasticsearch limits the maximum size of a HTTP request to 100mb by default so clients must ensure that no request exceeds this size. It is not possible to index a single document that exceeds the size limit, so you must pre-process any such documents into smaller pieces before sending them to Elasticsearch. For instance, split documents into pages or chapters before indexing them, or store raw binary data in a system outside Elasticsearch and replace the raw data with a link to the external system in the documents that you send to Elasticsearch.
Client suppport for bulk requests
Some of the officially supported clients provide helpers to assist with bulk requests and reindexing:
- Go: Check out
esutil.BulkIndexer
- Perl: Check out
Search::Elasticsearch::Client::5_0::Bulk
andSearch::Elasticsearch::Client::5_0::Scroll
- Python: Check out
elasticsearch.helpers.*
- JavaScript: Check out
client.helpers.*
- .NET: Check out
BulkAllObservable
- PHP: Check out bulk indexing.
Submitting bulk requests with cURL
If you're providing text file input to curl
, you must use the --data-binary
flag instead of plain -d
.
The latter doesn't preserve newlines. For example:
$ cat requests
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
$ curl -s -H "Content-Type: application/x-ndjson" -XPOST localhost:9200/_bulk --data-binary "@requests"; echo
{"took":7, "errors": false, "items":[{"index":{"_index":"test","_id":"1","_version":1,"result":"created","forced_refresh":false}}]}
Optimistic concurrency control
Each index
and delete
action within a bulk API call may include the if_seq_no
and if_primary_term
parameters in their respective action and meta data lines.
The if_seq_no
and if_primary_term
parameters control how operations are run, based on the last modification to existing documents. See Optimistic concurrency control for more details.
Versioning
Each bulk item can include the version value using the version
field.
It automatically follows the behavior of the index or delete operation based on the _version
mapping.
It also support the version_type
.
Routing
Each bulk item can include the routing value using the routing
field.
It automatically follows the behavior of the index or delete operation based on the _routing
mapping.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Wait for active shards
When making bulk calls, you can set the wait_for_active_shards
parameter to require a minimum number of shard copies to be active before starting to process the bulk request.
Refresh
Control when the changes made by this request are visible to search.
NOTE: Only the shards that receive the bulk request will be affected by refresh.
Imagine a _bulk?refresh=wait_for
request with three documents in it that happen to be routed to different shards in an index with five shards.
The request will only wait for those three shards to refresh.
The other two shards that make up the index do not participate in the _bulk
request at all.
Query parameters
-
include_source_on_error
boolean True or false if to include the document source in the error message in case of parsing errors.
-
list_executed_pipelines
boolean If
true
, the response will include the ingest pipelines that were run for each index or create. -
pipeline
string The pipeline identifier to use to preprocess incoming documents. If the index has a default ingest pipeline specified, setting the value to
_none
turns off 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. Ifwait_for
, wait for a refresh to make this operation visible to search. Iffalse
, do nothing with refreshes. Valid values:true
,false
,wait_for
.Values are
true
,false
, orwait_for
. -
routing
string A custom value that is used to route operations to a specific shard.
-
_source
boolean | string | array[string] Indicates whether to return the
_source
field (true
orfalse
) or contains a list of fields to return. -
_source_excludes
string | array[string] A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in
_source_includes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
_source_includes
string | array[string] A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the
_source_excludes
query parameter. If the_source
parameter isfalse
, this parameter is ignored. -
timeout
string The period each action waits for the following operations: automatic index creation, dynamic mapping updates, and waiting for active shards. The default is
1m
(one minute), which guarantees Elasticsearch waits for at least the timeout before failing. The actual wait time could be longer, particularly when multiple waits occur.Values are
-1
or0
. -
wait_for_active_shards
number | string The number of shard copies that must be active before proceeding with the operation. Set to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default is1
, which waits for each primary shard to be active.Values are
all
orindex-setting
. -
require_alias
boolean If
true
, the request's actions must target an index alias. -
require_data_stream
boolean If
true
, the request's actions must target a data stream (existing or to be created).
POST _bulk
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
curl \
--request PUT 'http://api.example.com/_bulk' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{ \"index\" : { \"_index\" : \"test\", \"_id\" : \"1\" } }\n{ \"field1\" : \"value1\" }\n{ \"delete\" : { \"_index\" : \"test\", \"_id\" : \"2\" } }\n{ \"create\" : { \"_index\" : \"test\", \"_id\" : \"3\" } }\n{ \"field1\" : \"value3\" }\n{ \"update\" : {\"_id\" : \"1\", \"_index\" : \"test\"} }\n{ \"doc\" : {\"field2\" : \"value2\"} }"'
{ "index" : { "_index" : "test", "_id" : "1" } }
{ "field1" : "value1" }
{ "delete" : { "_index" : "test", "_id" : "2" } }
{ "create" : { "_index" : "test", "_id" : "3" } }
{ "field1" : "value3" }
{ "update" : {"_id" : "1", "_index" : "test"} }
{ "doc" : {"field2" : "value2"} }
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"} }
{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }
{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}
{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }
{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }
{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }
{ "doc" : {"field" : "value"} }
{ "update" : {"_id" : "4", "_index" : "index1"} }
{ "doc" : {"field" : "value"}, "_source": true}
{ "update": {"_id": "5", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "update": {"_id": "6", "_index": "index1"} }
{ "doc": {"my_field": "foo"} }
{ "create": {"_id": "7", "_index": "index1"} }
{ "my_field": "foo" }
{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }
{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}
{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }
{ "field" : "value2", "home_location": "41.12,-71.34"}
{
"took": 30,
"errors": false,
"items": [
{
"index": {
"_index": "test",
"_id": "1",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 201,
"_seq_no" : 0,
"_primary_term": 1
}
},
{
"delete": {
"_index": "test",
"_id": "2",
"_version": 1,
"result": "not_found",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 404,
"_seq_no" : 1,
"_primary_term" : 2
}
},
{
"create": {
"_index": "test",
"_id": "3",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 201,
"_seq_no" : 2,
"_primary_term" : 3
}
},
{
"update": {
"_index": "test",
"_id": "1",
"_version": 2,
"result": "updated",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"status": 200,
"_seq_no" : 3,
"_primary_term" : 4
}
}
]
}
{
"took": 486,
"errors": true,
"items": [
{
"update": {
"_index": "index1",
"_id": "5",
"status": 404,
"error": {
"type": "document_missing_exception",
"reason": "[5]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"update": {
"_index": "index1",
"_id": "6",
"status": 404,
"error": {
"type": "document_missing_exception",
"reason": "[6]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"create": {
"_index": "index1",
"_id": "7",
"_version": 1,
"result": "created",
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"_seq_no": 0,
"_primary_term": 1,
"status": 201
}
}
]
}
{
"items": [
{
"update": {
"error": {
"type": "document_missing_exception",
"reason": "[5]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
},
{
"update": {
"error": {
"type": "document_missing_exception",
"reason": "[6]: document missing",
"index_uuid": "aAsFqTI0Tc2W0LCWgPNrOA",
"shard": "0",
"index": "index1"
}
}
}
]
}
Delete a document
Generally available
Remove a JSON document from the specified index.
NOTE: You cannot send deletion requests directly to a data stream. To delete a document in a data stream, you must target the backing index containing the document.
Optimistic concurrency control
Delete 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
.
Versioning
Each document indexed is versioned.
When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime.
Every write operation run on a document, deletes included, causes its version to be incremented.
The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations.
The length of time for which a deleted document's version remains available is determined by the index.gc_deletes
index setting.
Routing
If routing is used during indexing, the routing value also needs to be specified to delete a document.
If the _routing
mapping is set to required
and no routing value is specified, the delete API throws a RoutingMissingException
and rejects the request.
For example:
DELETE /my-index-000001/_doc/1?routing=shard-1
This request deletes the document with ID 1, but it is routed based on the user. The document is not deleted if the correct routing is not specified.
Distributed
The delete operation gets hashed into a specific shard ID. It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.
Required authorization
- Index privileges:
delete
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.
-
refresh
string If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, it waits for a refresh to make this operation visible to search. Iffalse
, it does nothing with refreshes.Values are
true
,false
, orwait_for
. -
routing
string A custom value used to route operations to a specific shard.
-
timeout
string The period to wait for active shards.
This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. Some reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation. By default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.
Values are
-1
or0
. -
version
number An explicit version number for concurrency control. It must match the current version of the document for the request to succeed.
-
version_type
string The version type.
Values are
internal
,external
,external_gte
, orforce
. -
wait_for_active_shards
number | string The minimum 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 of1
means it waits for each primary shard to be active.Values are
all
orindex-setting
.
DELETE /my-index-000001/_doc/1
curl \
--request DELETE 'http://api.example.com/{index}/_doc/{id}' \
--header "Authorization: $API_KEY"
{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 5,
"result": "deleted"
}
Create or update an alias
Generally available
Adds a data stream or index to an alias.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams or indices to add. Supports wildcards (
*
). Wildcard patterns that match both data streams and indices return an error. -
name
string Required Alias to update. If the alias doesn’t exist, the request creates it. Index alias names support date math.
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
or0
. -
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
or0
.
Body
-
filter
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
index_routing
string -
is_write_index
boolean If
true
, sets the write index or data stream for the alias. If an alias points to multiple indices or data streams andis_write_index
isn’t set, the alias rejects write requests. If an index alias points to one index andis_write_index
isn’t set, the index automatically acts as the write index. Data stream aliases don’t automatically set a write data stream, even if the alias points to one data stream. -
routing
string -
search_routing
string
POST _aliases
{
"actions": [
{
"add": {
"index": "my-data-stream",
"alias": "my-alias"
}
}
]
}
curl \
--request PUT 'http://api.example.com/{index}/_aliases/{name}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"actions\": [\n {\n \"add\": {\n \"index\": \"my-data-stream\",\n \"alias\": \"my-alias\"\n }\n }\n ]\n}"'
{
"actions": [
{
"add": {
"index": "my-data-stream",
"alias": "my-alias"
}
}
]
}
Validate a query
Generally available
Validates a query without running it.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (
*
). To search all data streams or 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. -
all_shards
boolean If
true
, the validation is executed on all shards instead of one random shard per index. -
analyzer
string Analyzer to use for the query string. This parameter can only be used when the
q
query string parameter is specified. -
analyze_wildcard
boolean If
true
, wildcard and prefix queries are analyzed. -
default_operator
string The default operator for query string query:
AND
orOR
.Values are
and
,AND
,or
, orOR
. -
df
string 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. -
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
. Valid values are:all
,open
,closed
,hidden
,none
.Values are
all
,open
,closed
,hidden
, ornone
. -
explain
boolean If
true
, the response returns detailed information if an error has occurred. -
lenient
boolean If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. -
rewrite
boolean If
true
, returns a more detailed explanation showing the actual Lucene query that will be executed. -
q
string Query in the Lucene query string syntax.
Body
-
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
GET my-index-000001/_validate/query?q=user.id:kimchy
curl \
--request GET 'http://api.example.com/{index}/_validate/query' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":{}}'
Delete an inference endpoint
Generally available
Path parameters
-
task_type
string Required The task type
Values are
sparse_embedding
,text_embedding
,rerank
,completion
, orchat_completion
. -
inference_id
string Required The inference identifier.
DELETE /_inference/sparse_embedding/my-elser-model
curl \
--request DELETE 'http://api.example.com/_inference/{task_type}/{inference_id}' \
--header "Authorization: $API_KEY"
GET _inference/sparse_embedding/my-elser-model
curl \
--request GET 'http://api.example.com/_inference' \
--header "Authorization: $API_KEY"
Create an ELSER inference endpoint
Deprecated
Generally available
Create an inference endpoint to perform an inference task with the elser
service.
You can also deploy ELSER by using the Elasticsearch inference integration.
Your Elasticsearch deployment contains a preconfigured ELSER inference endpoint, you only need to create the enpoint using the API if you want to customize the settings.
The API request will automatically download and deploy the ELSER model if it isn't already downloaded.
You might see a 502 bad gateway error in the response when using the Kibana Console. This error usually just reflects a timeout, while the model downloads in the background. You can check the download progress in the Machine Learning UI. If using the Python client, you can set the timeout parameter to a higher value.
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.
Required authorization
- Cluster privileges:
manage_inference
Path parameters
-
task_type
string Required The type of the inference task that the model will perform.
Value is
sparse_embedding
. -
elser_inference_id
string Required The unique identifier of the inference endpoint.
Body
-
chunking_settings
object -
service
string Required Value is
elser
. -
service_settings
object Required
PUT _inference/sparse_embedding/my-elser-model
{
"service": "elser",
"service_settings": {
"num_allocations": 1,
"num_threads": 1
}
}
curl \
--request PUT 'http://api.example.com/_inference/{task_type}/{elser_inference_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service\": \"elser\",\n \"service_settings\": {\n \"num_allocations\": 1,\n \"num_threads\": 1\n }\n}"'
{
"service": "elser",
"service_settings": {
"num_allocations": 1,
"num_threads": 1
}
}
{
"service": "elser",
"service_settings": {
"adaptive_allocations": {
"enabled": true,
"min_number_of_allocations": 3,
"max_number_of_allocations": 10
},
"num_threads": 1
}
}
{
"inference_id": "my-elser-model",
"task_type": "sparse_embedding",
"service": "elser",
"service_settings": {
"num_allocations": 1,
"num_threads": 1
},
"task_settings": {}
}
Create a VoyageAI inference endpoint
Generally available
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.
Required authorization
- Cluster privileges:
manage_inference
Path parameters
-
task_type
string Required The type of the inference task that the model will perform.
Values are
text_embedding
orrerank
. -
voyageai_inference_id
string Required The unique identifier of the inference endpoint.
Body
-
chunking_settings
object -
service
string Required Value is
voyageai
. -
service_settings
object Required -
task_settings
object
PUT _inference/text_embedding/openai-embeddings
{
"service": "voyageai",
"service_settings": {
"model_id": "voyage-3-large",
"dimensions": 512
}
}
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
Ingest APIs enable you to manage tasks and resources related to ingest pipelines and processors.
Force buffered data to be processed
Deprecated
Generally available
The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send more data for analysis. When flushing, the job remains open and is available to continue analyzing data. A close operation additionally prunes and persists the model state to disk and the job must be opened again before analyzing further data.
Required authorization
- Cluster privileges:
manage_ml
Path parameters
-
job_id
string Required Identifier for the anomaly detection job.
Query parameters
-
advance_time
string | number Specifies to advance to a particular time value. Results are generated and the model is updated for data from the specified time interval.
-
calc_interim
boolean If true, calculates the interim results for the most recent bucket or all buckets within the latency period.
-
end
string | number When used in conjunction with
calc_interim
andstart
, specifies the range of buckets on which to calculate interim results. -
skip_time
string | number Specifies to skip to a particular time value. Results are not generated and the model is not updated for data from the specified time interval.
-
start
string | number When used in conjunction with
calc_interim
, specifies the range of buckets on which to calculate interim results.
Body
advance_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.
-
calc_interim
boolean Refer to the description for the
calc_interim
query parameter. end
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.
skip_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.
start
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.
POST _ml/anomaly_detectors/low_request_rate/_flush
{
"calc_interim": true
}
curl \
--request POST 'http://api.example.com/_ml/anomaly_detectors/{job_id}/_flush' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"calc_interim\": true\n}"'
{
"calc_interim": true
}
Get overall bucket results
Generally available
Retrievs overall bucket results that summarize the bucket results of multiple anomaly detection jobs.
The overall_score
is calculated by combining the scores of all the
buckets within the overall bucket span. First, the maximum
anomaly_score
per anomaly detection job in the overall bucket is
calculated. Then the top_n
of those scores are averaged to result in
the overall_score
. This means that you can fine-tune the
overall_score
so that it is more or less sensitive to the number of
jobs that detect an anomaly at the same time. For example, if you set
top_n
to 1
, the overall_score
is the maximum bucket score in the
overall bucket. Alternatively, if you set top_n
to the number of jobs,
the overall_score
is high only when all jobs detect anomalies in that
overall bucket. If you set the bucket_span
parameter (to a value
greater than its default), the overall_score
is the maximum
overall_score
of the overall buckets that have a span equal to the
jobs' largest bucket span.
Required authorization
- Cluster privileges:
monitor_ml
Path parameters
-
job_id
string Required Identifier for the anomaly detection job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression.
You can summarize the bucket results for all anomaly detection jobs by using
_all
or by specifying*
as the<job_id>
.
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. - Contains wildcard expressions and there are only partial matches.
If
true
, the request returns an emptyjobs
array when there are no matches and the subset of results when there are partial matches. If this parameter isfalse
, the request returns a404
status code when there are no matches or only partial matches. -
bucket_span
string The span of the overall buckets. Must be greater or equal to the largest bucket span of the specified anomaly detection jobs, which is the default value.
By default, an overall bucket has a span equal to the largest bucket span of the specified anomaly detection jobs. To override that behavior, use the optional
bucket_span
parameter.Values are
-1
or0
. -
end
string | number Returns overall buckets with timestamps earlier than this time.
-
exclude_interim
boolean If
true
, the output excludes interim results. -
overall_score
number | string Returns overall buckets with overall scores greater than or equal to this value.
-
start
string | number Returns overall buckets with timestamps after this time.
-
top_n
number The number of top anomaly detection job bucket scores to be used in the
overall_score
calculation.
Body
-
allow_no_match
boolean Refer to the description for the
allow_no_match
query parameter. -
bucket_span
string A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(days). Also accepts "0" without a unit and "-1" to indicate an unspecified value. end
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.
-
exclude_interim
boolean Refer to the description for the
exclude_interim
query parameter. overall_score
number | string Refer to the description for the
overall_score
query parameter.start
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.
-
top_n
number Refer to the description for the
top_n
query parameter.
GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
"overall_score": 80,
"start": "1403532000000"
}
curl \
--request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/results/overall_buckets' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"overall_score\": 80,\n \"start\": \"1403532000000\"\n}"'
{
"overall_score": 80,
"start": "1403532000000"
}
Update a trained model deployment
Beta
Required authorization
- Cluster privileges:
manage_ml
Path parameters
-
model_id
string Required The unique identifier of the trained model. Currently, only PyTorch models are supported.
Query parameters
-
number_of_allocations
number The number of model allocations on each node where the model is deployed. All allocations on a node share the same copy of the model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed to a value less than the number of hardware threads.
Body
-
number_of_allocations
number The number of model allocations on each node where the model is deployed. All allocations on a node share the same copy of the model in memory but use a separate set of threads to evaluate the model. Increasing this value generally increases the throughput. If this setting is greater than the number of hardware threads it will automatically be changed to a value less than the number of hardware threads. If adaptive_allocations is enabled, do not set this value, because it’s automatically set.
-
adaptive_allocations
object
POST _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/deployment/_update
{
"number_of_allocations": 4
}
curl \
--request POST 'http://api.example.com/_ml/trained_models/{model_id}/deployment/_update' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"number_of_allocations\": 4\n}"'
{
"number_of_allocations": 4
}
Get a query ruleset
Generally available
Get details about a query ruleset.
Required authorization
- Cluster privileges:
manage_search_query_rules
Path parameters
-
ruleset_id
string Required The unique identifier of the query ruleset
GET _query_rules/my-ruleset/
curl \
--request GET 'http://api.example.com/_query_rules/{ruleset_id}' \
--header "Authorization: $API_KEY"
{
"ruleset_id": "my-ruleset",
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "query_string",
"values": [ "pugs", "puggles" ]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "fuzzy",
"metadata": "query_string",
"values": [ "rescue dogs" ]
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
Create or update a query ruleset
Generally available
There is a limit of 100 rules per ruleset.
This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset
cluster setting.
IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids
or docs
, but cannot use both in single rule.
It is advised to use one or the other in query rulesets, to avoid errors.
Additionally, pinned queries have a maximum limit of 100 pinned hits.
If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.
Required authorization
- Cluster privileges:
manage_search_query_rules
Path parameters
-
ruleset_id
string Required The unique identifier of the query ruleset to be created or updated.
PUT _query_rules/my-ruleset
{
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "user_query",
"values": [ "pugs", "puggles" ]
},
{
"type": "exact",
"metadata": "user_country",
"values": [ "us" ]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "fuzzy",
"metadata": "user_query",
"values": [ "rescue dogs" ]
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
curl \
--request PUT 'http://api.example.com/_query_rules/{ruleset_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"rules\": [\n {\n \"rule_id\": \"my-rule1\",\n \"type\": \"pinned\",\n \"criteria\": [\n {\n \"type\": \"contains\",\n \"metadata\": \"user_query\",\n \"values\": [ \"pugs\", \"puggles\" ]\n },\n {\n \"type\": \"exact\",\n \"metadata\": \"user_country\",\n \"values\": [ \"us\" ]\n }\n ],\n \"actions\": {\n \"ids\": [\n \"id1\",\n \"id2\"\n ]\n }\n },\n {\n \"rule_id\": \"my-rule2\",\n \"type\": \"pinned\",\n \"criteria\": [\n {\n \"type\": \"fuzzy\",\n \"metadata\": \"user_query\",\n \"values\": [ \"rescue dogs\" ]\n }\n ],\n \"actions\": {\n \"docs\": [\n {\n \"_index\": \"index1\",\n \"_id\": \"id3\"\n },\n {\n \"_index\": \"index2\",\n \"_id\": \"id4\"\n }\n ]\n }\n }\n ]\n}"'
{
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "user_query",
"values": [ "pugs", "puggles" ]
},
{
"type": "exact",
"metadata": "user_country",
"values": [ "us" ]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "fuzzy",
"metadata": "user_query",
"values": [ "rescue dogs" ]
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
Delete a query ruleset
Generally available
Remove a query ruleset and its associated data. This is a destructive action that is not recoverable.
Required authorization
- Cluster privileges:
manage_search_query_rules
Path parameters
-
ruleset_id
string Required The unique identifier of the query ruleset to delete
DELETE _query_rules/my-ruleset/
curl \
--request DELETE 'http://api.example.com/_query_rules/{ruleset_id}' \
--header "Authorization: $API_KEY"
Get all query rulesets
Generally available
Get summarized information about the query rulesets.
Required authorization
- Cluster privileges:
manage_search_query_rules
GET _query_rules/?from=0&size=3
curl \
--request GET 'http://api.example.com/_query_rules' \
--header "Authorization: $API_KEY"
{
"count": 3,
"results": [
{
"ruleset_id": "ruleset-1",
"rule_total_count": 1,
"rule_criteria_types_counts": {
"exact": 1
}
},
{
"ruleset_id": "ruleset-2",
"rule_total_count": 2,
"rule_criteria_types_counts": {
"exact": 1,
"fuzzy": 1
}
},
{
"ruleset_id": "ruleset-3",
"rule_total_count": 3,
"rule_criteria_types_counts": {
"exact": 1,
"fuzzy": 2
}
}
]
}
Get a script or search template
Generally available
Path parameters
-
id
string Required The identifier for the stored script or search template.
Query parameters
-
master_timeout
string The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. It can also be set to
-1
to indicate that the request should never timeout.Values are
-1
or0
.
GET _scripts/my-search-template
curl \
--request GET 'http://api.example.com/_scripts/{id}' \
--header "Authorization: $API_KEY"
Create or update a script or search template
Generally available
Creates or updates a stored script or search template.
Required authorization
- Cluster privileges:
manage
Path parameters
-
id
string Required The identifier for the stored script or search template. It must be unique within the cluster.
Query parameters
-
context
string The context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context. If you specify both this and the
<context>
path parameter, the API uses the request path parameter. -
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. It can also be set to
-1
to indicate that the request should never timeout.Values are
-1
or0
. -
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. It can also be set to
-1
to indicate that the request should never timeout.Values are
-1
or0
.
PUT _scripts/my-search-template
{
"script": {
"lang": "mustache",
"source": {
"query": {
"match": {
"message": "{{query_string}}"
}
},
"from": "{{from}}",
"size": "{{size}}"
}
}
}
curl \
--request POST 'http://api.example.com/_scripts/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"lang\": \"mustache\",\n \"source\": {\n \"query\": {\n \"match\": {\n \"message\": \"{{query_string}}\"\n }\n },\n \"from\": \"{{from}}\",\n \"size\": \"{{size}}\"\n }\n }\n}"'
{
"script": {
"lang": "mustache",
"source": {
"query": {
"match": {
"message": "{{query_string}}"
}
},
"from": "{{from}}",
"size": "{{size}}"
}
}
}
{
"script": {
"lang": "painless",
"source": "Math.log(_score * 2) + params['my_modifier']"
}
}
Delete a script or search template
Generally available
Path parameters
-
id
string Required The identifier for the stored script or search template.
Query parameters
-
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. It can also be set to
-1
to indicate that the request should never timeout.Values are
-1
or0
. -
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. It can also be set to
-1
to indicate that the request should never timeout.Values are
-1
or0
.
DELETE _scripts/my-search-template
curl \
--request DELETE 'http://api.example.com/_scripts/{id}' \
--header "Authorization: $API_KEY"
Run a script
Technical preview
Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.
Each context requires a script, but additional parameters depend on the context you're using for that script.
Body
-
context
string Values are
painless_test
,filter
,score
,boolean_field
,date_field
,double_field
,geo_point_field
,ip_field
,keyword_field
,long_field
, orcomposite_field
. -
context_setup
object -
script
object
POST /_scripts/painless/_execute
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
curl \
--request GET 'http://api.example.com/_scripts/painless/_execute' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"source\": \"params.count / params.total\",\n \"params\": {\n \"count\": 100.0,\n \"total\": 1000.0\n }\n }\n}"'
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
{
"script": {
"source": "doc['field'].value.length() <= params.max_length",
"params": {
"max_length": 4
}
},
"context": "filter",
"context_setup": {
"index": "my-index-000001",
"document": {
"field": "four"
}
}
}
{
"script": {
"source": "doc['rank'].value / params.max_rank",
"params": {
"max_rank": 5.0
}
},
"context": "score",
"context_setup": {
"index": "my-index-000001",
"document": {
"rank": 4
}
}
}
{
"result": "0.1"
}
{
"result": true
}
{
"result": 0.8
}
Run a script
Technical preview
Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.
The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.
Each context requires a script, but additional parameters depend on the context you're using for that script.
Body
-
context
string Values are
painless_test
,filter
,score
,boolean_field
,date_field
,double_field
,geo_point_field
,ip_field
,keyword_field
,long_field
, orcomposite_field
. -
context_setup
object -
script
object
POST /_scripts/painless/_execute
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
curl \
--request POST 'http://api.example.com/_scripts/painless/_execute' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"script\": {\n \"source\": \"params.count / params.total\",\n \"params\": {\n \"count\": 100.0,\n \"total\": 1000.0\n }\n }\n}"'
{
"script": {
"source": "params.count / params.total",
"params": {
"count": 100.0,
"total": 1000.0
}
}
}
{
"script": {
"source": "doc['field'].value.length() <= params.max_length",
"params": {
"max_length": 4
}
},
"context": "filter",
"context_setup": {
"index": "my-index-000001",
"document": {
"field": "four"
}
}
}
{
"script": {
"source": "doc['rank'].value / params.max_rank",
"params": {
"max_rank": 5.0
}
},
"context": "score",
"context_setup": {
"index": "my-index-000001",
"document": {
"rank": 4
}
}
}
{
"result": "0.1"
}
{
"result": true
}
{
"result": 0.8
}
Get async search results
Generally available
Retrieve the results of a previously submitted asynchronous search request. If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
Path parameters
-
id
string Required A unique identifier for the async search.
Query parameters
-
keep_alive
string The length of time that the async search should be available in the cluster. When not specified, the
keep_alive
set with the corresponding submit async request will be used. Otherwise, it is possible to override the value and extend the validity of the request. When this period expires, the search, if still running, is cancelled. If the search is completed, its saved results are deleted.Values are
-1
or0
. -
typed_keys
boolean Specify whether aggregation and suggester names should be prefixed by their respective types in the response
-
wait_for_completion_timeout
string Specifies to wait for the search to be completed up until the provided timeout. Final results will be returned if available before the timeout expires, otherwise the currently available results will be returned once the timeout expires. By default no timeout is set meaning that the currently available results will be returned without any additional wait.
Values are
-1
or0
.
GET /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=
curl \
--request GET 'http://api.example.com/_async_search/{id}' \
--header "Authorization: $API_KEY"
{
"id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_partial" : false,
"is_running" : false,
"start_time_in_millis" : 1583945890986,
"expiration_time_in_millis" : 1584377890986,
"completion_time_in_millis" : 1583945903130,
"response" : {
"took" : 12144,
"timed_out" : false,
"num_reduce_phases" : 46,
"_shards" : {
"total" : 562,
"successful" : 188,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 456433,
"relation" : "eq"
},
"max_score" : null,
"hits" : [ ]
},
"aggregations" : {
"sale_date" : {
"buckets" : []
}
}
}
}
Run an async search
Generally available
When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.
Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.
By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size
cluster level setting.
Query parameters
-
wait_for_completion_timeout
string Blocks and waits until the search is completed up to a certain timeout. When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster.
Values are
-1
or0
. -
keep_alive
string Specifies how long the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period.
Values are
-1
or0
. -
keep_on_completion
boolean If
true
, results are stored for later retrieval when the search completes within thewait_for_completion_timeout
. -
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 Indicate if an error should be returned if there is a partial search failure or timeout
-
analyzer
string The analyzer to use for the query string
-
analyze_wildcard
boolean Specify whether wildcard and prefix queries should be analyzed (default: false)
-
batched_reduce_size
number Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).
-
ccs_minimize_roundtrips
boolean The default value is the only supported value.
-
default_operator
string The default operator for query string query (AND or OR)
Values are
and
,AND
,or
, orOR
. -
df
string The field to use as default where no field prefix is given in the query string
-
docvalue_fields
string | array[string] A comma-separated list of fields to return as the docvalue representation of a field for each hit
-
expand_wildcards
string | array[string] Whether to expand wildcard expression to concrete indices that are open, closed or both.
Values are
all
,open
,closed
,hidden
, ornone
. -
explain
boolean Specify whether to return detailed information about score computation as part of a hit
-
ignore_throttled
boolean Whether specified concrete, expanded or aliased indices should be ignored when throttled
-
lenient
boolean Specify whether format-based query failures (such as providing text to a numeric field) should be ignored
-
The number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests
-
preference
string Specify the node or shard the operation should be performed on (default: random)
-
request_cache
boolean Specify if request cache should be used for this request or not, defaults to true
-
routing
string A comma-separated list of specific routing values
-
search_type
string Search operation type
Values are
query_then_fetch
ordfs_query_then_fetch
. -
stats
array[string] Specific 'tag' of the request for logging and statistical purposes
-
stored_fields
string | array[string] A comma-separated list of stored fields to return as part of a hit
-
suggest_field
string Specifies which field to use for suggestions.
-
suggest_mode
string Specify suggest mode
Values are
missing
,popular
, oralways
. -
suggest_size
number How many suggestions to return in response
-
suggest_text
string The source text for which the suggestions should be returned.
-
terminate_after
number The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.
-
timeout
string Explicit operation timeout
Values are
-1
or0
. -
track_total_hits
boolean | number Indicate if the number of documents that match the query should be tracked. A number can also be specified, to accurately track the total hit count up to the number.
-
track_scores
boolean Whether to calculate and return scores even if they are not used for sorting
-
typed_keys
boolean Specify whether aggregation and suggester names should be prefixed by their respective types in the response
-
rest_total_hits_as_int
boolean Indicates whether hits.total should be rendered as an integer or an object in the rest search response
-
version
boolean Specify whether to return document version as part of a hit
-
_source
boolean | string | array[string] True or false to return the _source field or not, or a list of fields to return
-
_source_excludes
string | array[string] A list of fields to exclude from the returned _source field
-
_source_includes
string | array[string] A list of fields to extract and return from the _source field
-
seq_no_primary_term
boolean Specify whether to return sequence number and primary term of the last modification of each hit
-
q
string Query in the Lucene query string syntax
-
size
number Number of hits to return (default: 10)
-
from
number Starting offset (default: 0)
-
sort
string | array[string] A comma-separated list of : pairs
Body
-
aggregations
object -
collapse
object External documentation -
explain
boolean If true, returns detailed information about score computation as part of a hit.
-
ext
object Configuration of search extensions defined by Elasticsearch plugins.
-
from
number Starting document offset. 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.
-
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] Boosts the _score of documents from specified indices.
-
docvalue_fields
array[object] Array of wildcard (*) patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
knn
object | array[object] Defines the approximate kNN search to run.
-
min_score
number Minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.
-
post_filter
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
profile
boolean -
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation rescore
object | array[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. 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.
-
slice
object _source
boolean | object Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
-
fields
array[object] Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
-
suggest
object -
terminate_after
number 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. Defaults to 0, which does not terminate query execution early.
-
timeout
string Specifies 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.
-
version
boolean If true, returns document version as part of a hit.
-
seq_no_primary_term
boolean If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.
-
stored_fields
string | array[string] -
pit
object -
runtime_mappings
object -
stats
array[string] 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.
POST /sales*/_async_search?size=0
{
"sort": [
{ "date": { "order": "asc" } }
],
"aggs": {
"sale_date": {
"date_histogram": {
"field": "date",
"calendar_interval": "1d"
}
}
}
}
curl \
--request POST 'http://api.example.com/_async_search' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"sort\": [\n { \"date\": { \"order\": \"asc\" } }\n ],\n \"aggs\": {\n \"sale_date\": {\n \"date_histogram\": {\n \"field\": \"date\",\n \"calendar_interval\": \"1d\"\n }\n }\n }\n}"'
{
"sort": [
{ "date": { "order": "asc" } }
],
"aggs": {
"sale_date": {
"date_histogram": {
"field": "date",
"calendar_interval": "1d"
}
}
}
}
{
"id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_partial" : true,
"is_running" : true,
"start_time_in_millis" : 1583945890986,
"expiration_time_in_millis" : 1584377890986,
"response" : {
"took" : 1122,
"timed_out" : false,
"num_reduce_phases" : 0,
"_shards" : {
"total" : 562,
"successful" : 3,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 157483,
"relation" : "gte"
},
"max_score" : null,
"hits" : [ ]
}
}
}
Run a scrolling search
Generally available
IMPORTANT: The scroll API is no longer recommend for deep pagination. If you need to preserve the index state while paging through more than 10,000 hits, use the search_after
parameter with a point in time (PIT).
The scroll API gets large sets of results from a single scrolling search request.
To get the necessary scroll ID, submit a search API request that includes an argument for the scroll
query parameter.
The scroll
parameter indicates how long Elasticsearch should retain the search context for the request.
The search response returns a scroll ID in the _scroll_id
response body parameter.
You can then use the scroll ID with the scroll API to retrieve the next batch of results for the request.
If the Elasticsearch security features are enabled, the access to the results of a specific scroll ID is restricted to the user or API key that submitted the search.
You can also use the scroll API to specify a new scroll parameter that extends or shortens the retention period for the search context.
IMPORTANT: Results from a scrolling search reflect the state of the index at the time of the initial search request. Subsequent indexing or document changes only affect later search and scroll requests.
Required authorization
- Index privileges:
read
Path parameters
-
scroll_id
string Required Deprecated The scroll ID
Query parameters
-
scroll
string The period to retain the search context for scrolling.
Values are
-1
or0
. -
scroll_id
string Deprecated The scroll ID for scrolled search
-
rest_total_hits_as_int
boolean If true, the API response’s hit.total property is returned as an integer. If false, the API response’s hit.total property is returned as an object.
GET /_search/scroll
{
"scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}
curl \
--request POST '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=="
}
Delete an async SQL search
Generally available
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:
- Users with the
cancel_task
cluster privilege. - The user who first submitted the search.
Required authorization
- Cluster privileges:
cancel_task
Path parameters
-
id
string Required The identifier for the search.
DELETE _sql/async/delete/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=
curl \
--request DELETE 'http://api.example.com/_sql/async/delete/{id}' \
--header "Authorization: $API_KEY"
Translate SQL into Elasticsearch queries
Generally available
Translate an SQL search into a search API request containing Query DSL.
It accepts the same request body parameters as the SQL search API, excluding cursor
.
Required authorization
- Index privileges:
read
Body
Required
-
fetch_size
number The maximum number of rows (or entries) to return in one response.
-
filter
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation -
query
string Required The SQL query to run.
-
time_zone
string
POST _sql/translate
{
"query": "SELECT * FROM library ORDER BY page_count DESC",
"fetch_size": 10
}
curl \
--request GET 'http://api.example.com/_sql/translate' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": \"SELECT * FROM library ORDER BY page_count DESC\",\n \"fetch_size\": 10\n}"'
{
"query": "SELECT * FROM library ORDER BY page_count DESC",
"fetch_size": 10
}
Synonyms
The synonyms management API provides a convenient way to define and manage synonyms in an internal system index. Related synonyms can be grouped in a "synonyms set". Create as many synonym sets as you need.