Get user privileges | Elasticsearch API documentation

Get aliases

GET /_cat/aliases

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.

Query parameters

h string | array[string]

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

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
expand_wildcards string | array[string]
The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
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.

Responses

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

GET /_cat/aliases

curl \
 --request GET 'http://api.example.com/_cat/aliases' \
 --header "Authorization: $API_KEY"

Response examples (200)

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

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

Get an enrich policy Added in 7.5.0

GET /_enrich/policy

Api key auth Basic auth Bearer auth

Returns information about an enrich policy.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attribute Show response attribute object
- policies array[object] Required
  
  Hide policies attribute Show policies attribute object
  
  config object Required
  
  Hide config attribute Show config attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  enrich_fields string | array[string] Required
  
  indices string | array[string] Required
  
  match_field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  name string
  
  elasticsearch_version string

GET /_enrich/policy

curl \
 --request GET 'http://api.example.com/_enrich/policy' \
 --header "Authorization: $API_KEY"

Run multiple Fleet searches Technical preview

POST /_fleet/_fleet_msearch

Api key auth Basic auth Bearer auth

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

Query parameters

allow_no_indices boolean

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

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

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_throttled boolean

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

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

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

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

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

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

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

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

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

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

application/json

Body object Required

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

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

aggregations object

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

External documentation
collapse object
External documentation
explain boolean

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

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

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

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

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

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

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

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

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

field string Required

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

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

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

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object
External documentation

docvalue_fields array[object]

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields array[string]

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

sort array[string | object]

_source boolean | object

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

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

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

field string Required

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

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

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

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

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields array[string]

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

sort

_source

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

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

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

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

External documentation
profile boolean

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

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

External documentation
rescore object | array[object]

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

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

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

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

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

window_size number

query object

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

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

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

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

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

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

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

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

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

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

nested object
One of:
Field string SortOptions object

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

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

excludes string | array[string]

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

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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

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

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

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

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

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

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

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

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

Responses

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

POST /_fleet/_fleet_msearch

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

Run a Fleet search Technical preview

POST /{index}/_fleet/_fleet_search

Api key auth Basic auth Bearer auth

The purpose of the Fleet search API is to provide an API where the search will be run only after the provided checkpoint has been processed and is visible for searches inside of Elasticsearch.

Path parameters

index string Required

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

Query parameters

allow_no_indices boolean
analyzer string
analyze_wildcard boolean
batched_reduce_size number
ccs_minimize_roundtrips boolean
default_operator string

Values are and, AND, or, or OR.
df string
docvalue_fields string | array[string]
expand_wildcards string | array[string]
Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
explain boolean
ignore_throttled boolean
ignore_unavailable boolean
lenient boolean
max_concurrent_shard_requests number
preference string
pre_filter_shard_size number
request_cache boolean
routing string
scroll string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
search_type string
Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
stats array[string]
stored_fields string | array[string]
suggest_field string

Specifies which field to use for suggestions.
suggest_mode string
Supported values include:
- missing: Only generate suggestions for terms that are not in the shard.
- popular: Only suggest terms that occur in more docs on the shard than the original term.
- always: Suggest any matching suggestions based on terms in the suggest text.
Values are missing, popular, or always.
suggest_size number
suggest_text string

The source text for which the suggestions should be returned.
terminate_after number
timeout string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
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.
track_scores boolean
typed_keys boolean
rest_total_hits_as_int boolean
version boolean
_source boolean | string | array[string]

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered. Used as a query parameter along with the _source_includes and _source_excludes parameters.
_source_excludes string | array[string]
_source_includes string | array[string]
seq_no_primary_term boolean
q string
size number
from number
sort string | array[string]
wait_for_checkpoints array[number]

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

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

application/json

Body

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

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

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

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
Hide attributes Show attributes object

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

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

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
script_fields object

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

A field value.
size number

The number of hits to return. 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
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

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

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

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

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

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

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

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

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source string | object

One of:
ScriptSource string SearchRequestBody object

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

Hide params attribute Show params attribute object

* object Additional properties

lang string

Any of:
ScriptLanguage string ScriptLanguage string

Values are painless, expression, mustache, or java.

options object

Hide options attribute Show options attribute object

* string Additional properties

type string

Values are string, number, or version.

mode string

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

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Field string SortOptions object

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

Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

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

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

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

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

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

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

type string

Values are string, number, or version.

mode string

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

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

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

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

excludes string | array[string]

includes string | array[string]
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.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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

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

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- timed_out boolean Required
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object | number
  
  Total hit count information, present only if track_total_hits wasn't false in the search request.
  
  One of:
  TotalHits object number-2 number
  
  Hide attributes Show attributes
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  hits array[object] Required
  
  Hide hits attributes Show hits attributes object
  
  _index string Required
  
  _id string
  
  _score number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  _explanation object
  
  Hide _explanation attributes Show _explanation attributes object
  
  description string Required
  
  details array[object] Required
  
  value number Required
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  * array[string] Additional properties
  
  inner_hits object
  
  Hide inner_hits attribute Show inner_hits attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  hits object Required
  
  matched_queries array[string] | object
  
  One of:
  array-1 array[string] object-2 object
  
  _nested object
  
  Hide _nested attributes Show _nested attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  offset number Required
  
  _nested object
  
  _ignored array[string]
  
  ignored_field_values object
  
  Hide ignored_field_values attribute Show ignored_field_values attribute object
  
  * array[object] Additional properties
  
  _shard string
  
  _node string
  
  _routing string
  
  _source object
  
  _rank number
  
  _seq_no number
  
  _primary_term number
  
  _version number
  
  sort array[number | string | boolean | null]
  
  A field value.
  
  max_score number | string | null
  
  One of:
  number-1 number string-2 string | null
- aggregations object
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  took number
  
  Time unit for milliseconds
  
  timed_out boolean Required
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  shard number Required
  
  status string
- fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
- max_score number
- num_reduce_phases number
- profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  Hide shards attributes Show shards attributes object
  
  aggregations array[object] Required
  
  Hide aggregations attributes Show aggregations attributes object
  
  breakdown object Required
  
  description string Required
  
  time_in_nanos
  
  type string Required
  
  debug object
  
  children array[object]
  
  cluster string Required
  
  dfs object
  
  Hide dfs attributes Show dfs attributes object
  
  statistics object
  
  Hide statistics attributes Show statistics attributes object
  
  type string Required
  
  description string Required
  
  time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  time_in_nanos
  
  breakdown object Required
  
  debug object
  
  children array[object]
  
  knn array[object]
  
  fetch object
  
  Hide fetch attributes Show fetch attributes object
  
  type string Required
  
  description string Required
  
  time_in_nanos number
  
  Time unit for nanoseconds
  
  breakdown object Required
  
  Hide breakdown attributes Show breakdown attributes object
  
  load_source number
  
  load_source_count number
  
  load_stored_fields number
  
  load_stored_fields_count number
  
  next_reader number
  
  next_reader_count number
  
  process_count number
  
  process number
  
  debug object
  
  Hide debug attributes Show debug attributes object
  
  stored_fields array[string]
  
  fast_path number
  
  children array[object]
  
  id string Required
  
  index string Required
  
  node_id string Required
  
  searches array[object] Required
  
  Hide searches attributes Show searches attributes object
  
  collector array[object] Required
  
  query array[object] Required
  
  rewrite_time number Required
  
  shard_id number Required
- pit_id string
- _scroll_id string
- suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  One of:
  CompletionSuggest object PhraseSuggest object TermSuggest object
  
  Hide attributes Show attributes
  
  length number Required
  
  offset number Required
  
  text string Required
  
  options
- terminated_early boolean

POST /{index}/_fleet/_fleet_search

curl \
 --request POST 'http://api.example.com/{index}/_fleet/_fleet_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"aggregations":{},"collapse":{},"explain":true,"ext":{"additionalProperty1":{},"additionalProperty2":{}},"from":42.0,"highlight":{"":"plain","boundary_chars":"string","boundary_max_scan":42.0,"boundary_scanner":"chars","boundary_scanner_locale":"string","force_source":true,"fragmenter":"simple","fragment_size":42.0,"highlight_filter":true,"highlight_query":{},"max_fragment_length":42.0,"max_analyzed_offset":42.0,"no_match_size":42.0,"number_of_fragments":42.0,"options":{"additionalProperty1":{},"additionalProperty2":{}},"order":"score","phrase_limit":42.0,"post_tags":["string"],"pre_tags":["string"],"require_field_match":true,"tags_schema":"styled","encoder":"default","fields":{}},"track_total_hits":true,"indices_boost":[{"additionalProperty1":42.0,"additionalProperty2":42.0}],"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"min_score":42.0,"post_filter":{},"profile":true,"query":{},"rescore":{"window_size":42.0,"query":{"rescore_query":{},"query_weight":42.0,"rescore_query_weight":42.0,"score_mode":"avg"},"learning_to_rank":{"model_id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}}}},"script_fields":{"additionalProperty1":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"search_after":[42.0],"size":42.0,"slice":{"field":"string","id":"string","max":42.0},"":true,"fields":[{"field":"string","format":"string","include_unmapped":true}],"suggest":{"text":"string"},"terminate_after":42.0,"timeout":"string","track_scores":true,"version":true,"seq_no_primary_term":true,"stored_fields":"string","pit":{"id":"string","keep_alive":"string"},"runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"stats":["string"]}'

Create or update an alias

POST /{index}/_alias/{name}

Api key auth Basic auth Bearer auth

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

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

application/json

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 and is_write_index isn’t set, the alias rejects write requests. If an index alias points to one index and is_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

Responses

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

POST /{index}/_alias/{name}

curl \
 --request POST 'http://api.example.com/{index}/_alias/{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}"'

Request example

{
  "actions": [
    {
      "add": {
        "index": "my-data-stream",
        "alias": "my-alias"
      }
    }
  ]
}

Get aliases

GET /_alias

Api key auth Basic auth Bearer auth

Retrieves information for one or more data stream or index aliases.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]
Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
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.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

GET /_alias

curl \
 --request GET 'http://api.example.com/_alias' \
 --header "Authorization: $API_KEY"

Split an index Added in 6.1.0

PUT /{index}/_split/{target}

Api key auth Basic auth Bearer auth

Split an index into a new index with more primary shards.

Before you can split an index:
The index must be read-only.
The cluster health status must be green.

You can do make an index read-only with the following request using the add index block API:

PUT /my_source_index/_block/write

The current write index on a data stream cannot be split. In order to split the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be split.

The number of times the index can be split (and the number of shards that each original shard can be split into) is determined by the index.number_of_routing_shards setting. The number of routing shards specifies the hashing space that is used internally to distribute documents across shards with consistent hashing. For instance, a 5 shard index with number_of_routing_shards set to 30 (5 x 2 x 3) could be split by a factor of 2 or 3.

A split operation:

Creates a new target index with the same definition as the source index, but with a larger number of primary shards.
Hard-links segments from the source index into the target index. If the file system doesn't support hard-linking, all segments are copied into the new index, which is a much more time consuming process.
Hashes all documents again, after low level files are created, to delete documents that belong to a different shard.
Recovers the target index as though it were a closed index which had just been re-opened.

IMPORTANT: Indices can only be split if they satisfy the following requirements:

The target index must not exist.
The source index must have fewer primary shards than the target index.
The number of primary shards in the target index must be a multiple of the number of primary shards in the source index.
The node handling the split process must have sufficient free disk space to accommodate a second copy of the existing index.

Path parameters

index string Required

Name of the source index to split.
target string Required

Name of the target index to create.

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

Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
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).

application/json

Body

aliases object

Aliases for the resulting index.
Hide aliases attribute Show aliases attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  search_routing string
settings object

Configuration options for the target index.
Hide settings attribute Show settings attribute object
- * object Additional properties

Responses

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

PUT /{index}/_split/{target}

curl \
 --request PUT 'http://api.example.com/{index}/_split/{target}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"settings\": {\n    \"index.number_of_shards\": 2\n  }\n}"'

Request example

Split an existing index into a new index with more primary shards.

{
  "settings": {
    "index.number_of_shards": 2
  }
}

Create an inference endpoint Added in 8.11.0

PUT /_inference/{inference_id}

Api key auth Basic auth Bearer auth

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.

IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Mistral, Azure OpenAI, 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.

Path parameters

inference_id string Required

The inference Id

application/json

Body Required

chunking_settings object
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
- strategy string
  
  The chunking strategy: sentence or word.
service string Required

The service type
service_settings object Required
task_settings object

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  strategy string
  
  The chunking strategy: sentence or word.
- service string Required
  
  The service type
- service_settings object Required
- task_settings object
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.

PUT /_inference/{inference_id}

curl \
 --request PUT 'http://api.example.com/_inference/{inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"chunking_settings":{"max_chunk_size":42.0,"overlap":42.0,"sentence_overlap":42.0,"strategy":"string"},"service":"string","service_settings":{},"task_settings":{}}'

Delete a filter Added in 5.4.0

DELETE /_ml/filters/{filter_id}

Api key auth Basic auth Bearer auth

If an anomaly detection job references the filter, you cannot delete the filter. You must update or delete the job before you can delete the filter.

Path parameters

filter_id string Required

A string that uniquely identifies a filter.

Responses

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

DELETE /_ml/filters/{filter_id}

curl \
 --request DELETE 'http://api.example.com/_ml/filters/{filter_id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response when deleting a filter.

{
  "acknowledged": true
}

Preview features used by data frame analytics Added in 7.13.0

POST /_ml/data_frame/analytics/{id}/_preview

Api key auth Basic auth Bearer auth

Preview the extracted features used by a data frame analytics config.

Path parameters

id string Required

Identifier for the data frame analytics job.

application/json

Body

config object
Hide config attributes Show config attributes object
- source object Required
  Hide source attributes Show source attributes object
  
  index string | array[string] Required
  
  runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string SearchRequestBody object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
  
  query object
  
  The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.
  
  Query DSL
- analysis object Required
  Hide analysis attributes Show analysis attributes object
  
  classification object
  
  Hide classification attributes Show classification attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  multi_encoding object
  
  n_gram_encoding object
  
  one_hot_encoding object
  
  target_mean_encoding object
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  class_assignment_objective string
  
  num_top_classes number
  
  Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.
  
  outlier_detection object
  
  Hide outlier_detection attributes Show outlier_detection attributes object
  
  compute_feature_influence boolean
  
  Specifies whether the feature influence calculation is enabled.
  
  feature_influence_threshold number
  
  The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.
  
  method string
  
  The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.
  
  n_neighbors number
  
  Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.
  
  outlier_fraction number
  
  The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.
  
  standardization_enabled boolean
  
  If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).
  
  regression object
  
  Hide regression attributes Show regression attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  multi_encoding object
  
  n_gram_encoding object
  
  one_hot_encoding object
  
  target_mean_encoding object
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  loss_function string
  
  The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).
  
  loss_function_parameter number
  
  A positive number that is used as a parameter to the loss_function.
- model_memory_limit string
- max_num_threads number
- analyzed_fields object
  Hide analyzed_fields attributes Show analyzed_fields attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.

Responses

200 application/json
Hide response attribute Show response attribute object
- feature_values array[object] Required
  
  An array of objects that contain feature name and value pairs. The features have been processed and indicate what will be sent to the model for training.
  
  Hide feature_values attribute Show feature_values attribute object
  
  * string Additional properties

POST /_ml/data_frame/analytics/{id}/_preview

curl \
 --request POST 'http://api.example.com/_ml/data_frame/analytics/{id}/_preview' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"config":{"source":{"index":"string","runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"_source":{"includes":["string"],"excludes":["string"]},"query":{}},"analysis":{"classification":{"alpha":42.0,"dependent_variable":"string","downsample_factor":42.0,"early_stopping_enabled":true,"eta":42.0,"eta_growth_rate_per_tree":42.0,"feature_bag_fraction":42.0,"feature_processors":[{"frequency_encoding":{},"multi_encoding":{},"n_gram_encoding":{},"one_hot_encoding":{},"target_mean_encoding":{}}],"gamma":42.0,"lambda":42.0,"max_optimization_rounds_per_hyperparameter":42.0,"max_trees":42.0,"num_top_feature_importance_values":42.0,"prediction_field_name":"string","randomize_seed":42.0,"soft_tree_depth_limit":42.0,"soft_tree_depth_tolerance":42.0,"":"string","class_assignment_objective":"string","num_top_classes":42.0},"outlier_detection":{"compute_feature_influence":true,"feature_influence_threshold":42.0,"method":"string","n_neighbors":42.0,"outlier_fraction":42.0,"standardization_enabled":true},"regression":{"alpha":42.0,"dependent_variable":"string","downsample_factor":42.0,"early_stopping_enabled":true,"eta":42.0,"eta_growth_rate_per_tree":42.0,"feature_bag_fraction":42.0,"feature_processors":[{"frequency_encoding":{},"multi_encoding":{},"n_gram_encoding":{},"one_hot_encoding":{},"target_mean_encoding":{}}],"gamma":42.0,"lambda":42.0,"max_optimization_rounds_per_hyperparameter":42.0,"max_trees":42.0,"num_top_feature_importance_values":42.0,"prediction_field_name":"string","randomize_seed":42.0,"soft_tree_depth_limit":42.0,"soft_tree_depth_tolerance":42.0,"":"string","loss_function":"string","loss_function_parameter":42.0}},"model_memory_limit":"string","max_num_threads":42.0,"analyzed_fields":{"includes":["string"],"excludes":["string"]}}}'

Get rollup job information Deprecated Technical preview

GET /_rollup/job/{id}

Api key auth Basic auth Bearer auth

Get the configuration, stats, and status of rollup jobs.

NOTE: This API returns only active (both STARTED and STOPPED) jobs. If a job was created, ran for a while, then was deleted, the API does not return any details about it. For details about a historical rollup job, the rollup capabilities API may be more useful.

Path parameters

id string Required

Identifier for the rollup job. If it is _all or omitted, the API returns all rollup jobs.

Responses

200 application/json
Hide response attribute Show response attribute object
- jobs array[object] Required
  
  Hide jobs attributes Show jobs attributes object
  
  config object Required
  
  Hide config attributes Show config attributes object
  
  cron string Required
  
  groups object Required
  
  Hide groups attributes Show groups attributes object
  
  date_histogram object
  
  Hide date_histogram attributes Show date_histogram attributes object
  
  delay string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  calendar_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  fixed_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  time_zone string
  
  histogram object
  
  Hide histogram attributes Show histogram attributes object
  
  fields string | array[string] Required
  
  interval number Required
  
  The interval of histogram buckets to be generated when rolling up. For example, a value of 5 creates buckets that are five units wide (0-5, 5-10, etc). Note that only one interval can be specified in the histogram group, meaning that all fields being grouped via the histogram must share the same interval.
  
  terms object
  
  Hide terms attribute Show terms attribute object
  
  fields string | array[string] Required
  
  id string Required
  
  index_pattern string Required
  
  metrics array[object] Required
  
  Hide metrics attributes Show metrics attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  metrics array[string] Required
  
  An array of metrics to collect for the field. At least one metric must be configured.
  
  Values are min, max, sum, avg, or value_count.
  
  page_size number Required
  
  rollup_index string Required
  
  timeout string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  stats object Required
  
  Hide stats attributes Show stats attributes object
  
  documents_processed number Required
  
  index_failures number Required
  
  index_time_in_ms number
  
  Time unit for milliseconds
  
  index_total number Required
  
  pages_processed number Required
  
  rollups_indexed number Required
  
  search_failures number Required
  
  search_time_in_ms number
  
  Time unit for milliseconds
  
  search_total number Required
  
  trigger_count number Required
  
  processing_time_in_ms number
  
  Time unit for milliseconds
  
  processing_total number Required
  
  status object Required
  
  Hide status attributes Show status attributes object
  
  current_position object
  
  Hide current_position attribute Show current_position attribute object
  
  * object Additional properties
  
  job_state string Required
  
  Values are started, indexing, stopping, stopped, or aborting.
  
  upgraded_doc_id boolean

GET /_rollup/job/{id}

curl \
 --request GET 'http://api.example.com/_rollup/job/{id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET _rollup/job/sensor`.

{
  "jobs": [
    {
      "config": {
        "id": "sensor",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped"
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    }
  ]
}

Run a script Technical preview

POST /_scripts/painless/_execute

Api key auth Basic auth Bearer auth

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.

application/json

Body

context string

Values are painless_test, filter, score, boolean_field, date_field, double_field, geo_point_field, ip_field, keyword_field, long_field, or composite_field.
context_setup object
Hide context_setup attributes Show context_setup attributes object
- document object Required
  
  Document that's temporarily indexed in-memory and accessible from the script.
- index string Required
- query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
script object
Hide script attributes Show script attributes object
- source string | object
 
 One of:
 ScriptSource string SearchRequestBody object
 
 Hide attributes Show attributes
 
 aggregations object
 
 Defines the aggregations that are run as part of the search request.
 
 External documentation
 
 collapse object
 External documentation
 
 explain boolean
 
 If true, the request returns detailed information about score computation as part of a hit.
 
 ext object
 
 Configuration of search extensions defined by Elasticsearch plugins.
 
 Hide ext attribute Show ext attribute object
 
 * object Additional properties
 
 from number
 
 The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 Hide options attribute Show options attribute object
 
 * object Additional properties
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 track_total_hits boolean | number
 
 Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
 
 indices_boost array[object]
 
 Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
 
 External documentation
 
 Hide indices_boost attribute Show indices_boost attribute object
 
 * number Additional properties
 
 docvalue_fields array[object]
 
 An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
 
 External documentation
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 knn object | array[object]
 
 The approximate kNN search to run.
 
 One of:
 KnnSearch object array-2 array[object]
 
 Hide attributes Show attributes
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 Hide query_vector_builder attribute Show query_vector_builder attribute object
 
 text_embedding object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter object | array[object]
 
 Filters for the kNN search query
 
 One of:
 QueryContainer object array-2 array[object]
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 Hide inner_hits attributes Show inner_hits attributes object
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 from number
 
 Inner hit starting document offset.
 
 collapse object
 
 docvalue_fields array[object]
 
 explain boolean
 
 highlight
 
 ignore_unmapped boolean
 
 script_fields object
 
 seq_no_primary_term boolean
 
 fields array[string]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 sort
 
 _source
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 version boolean
 
 rescore_vector object
 
 Hide rescore_vector attribute Show rescore_vector attribute object
 
 oversample number Required
 
 Applies the specified oversample factor to k on the approximate kNN search
 
 External documentation
 
 Hide attributes Show attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 rescore_vector object
 
 rank object
 
 Hide rank attribute Show rank attribute object
 
 rrf object
 
 Hide rrf attributes Show rrf attributes object
 
 rank_constant number
 
 How much influence documents in individual result sets per query have over the final ranked result set
 
 rank_window_size number
 
 Size of the individual result sets per query
 
 min_score number
 
 The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
 
 post_filter object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 profile boolean
 
 Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
 
 query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 rescore object | array[object]
 
 Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
 
 One of:
 Rescore object array-2 array[object]
 
 Hide attributes Show attributes
 
 window_size number
 
 query object
 
 learning_to_rank object
 
 retriever object
 
 Hide retriever attributes Show retriever attributes object
 
 standard object
 
 Hide standard attributes Show standard attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 terminate_after number
 
 Maximum number of documents to collect for each shard.
 
 sort
 
 collapse object
 
 knn object
 
 Hide knn attributes Show knn attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 field string Required
 
 The name of the vector field to search against.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number Required
 
 Number of nearest neighbors to return as top hits.
 
 num_candidates number Required
 
 Number of nearest neighbor candidates to consider per shard.
 
 similarity number
 
 The minimum similarity required for a document to be considered a match.
 
 rescore_vector object
 
 rrf object
 
 Hide rrf attributes Show rrf attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 retrievers array[object] Required
 
 A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
 
 rank_constant number
 
 This value determines how much influence documents in individual result sets per query have over the final ranked result set.
 
 rank_window_size number
 
 This value determines the size of the individual result sets per query.
 
 text_similarity_reranker object
 
 Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 retriever object Required
 
 rank_window_size number
 
 This value determines how many documents we will consider from the nested retriever.
 
 inference_id string
 
 Unique identifier of the inference endpoint created using the inference API.
 
 inference_text string
 
 The text snippet used as the basis for similarity comparison
 
 field string
 
 The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
 
 rule object
 
 Hide rule attributes Show rule attributes object
 
 filter
 
 min_score number
 
 Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
 
 ruleset_ids array[string] Required
 
 The ruleset IDs containing the rules this retriever is evaluating against.
 
 match_criteria object Required
 
 The match criteria that will determine if a rule in the provided rulesets should be applied.
 
 retriever object Required
 
 rank_window_size number
 
 This value determines the size of the individual result set.
 
 script_fields object
 
 Retrieve a script evaluation (based on different fields) for each hit.
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 ignore_failure boolean
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 size number
 
 The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
 
 slice object
 
 Hide slice attributes Show slice attributes object
 
 field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 id string Required
 
 max number Required
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 fields array[object]
 
 An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
 
 Hide fields attributes Show fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 suggest object
 
 Hide suggest attribute Show suggest attribute object
 
 text string
 
 Global suggest text, to avoid repetition when the same text is used in several suggesters
 
 terminate_after number
 
 The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
 
 IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
 
 If set to 0 (default), the query does not terminate early.
 
 timeout string
 
 The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
 
 track_scores boolean
 
 If true, calculate and return document scores, even if the scores are not used for sorting.
 
 version boolean
 
 If true, the request returns the document version as part of a hit.
 
 seq_no_primary_term boolean
 
 If true, the request returns sequence number and primary term of the last modification of each hit.
 
 External documentation
 
 stored_fields string | array[string]
 
 pit object
 
 Hide pit attributes Show pit attributes object
 
 id string Required
 
 keep_alive string
 
 A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
 
 runtime_mappings object
 
 Hide runtime_mappings attribute Show runtime_mappings attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 fields object
 
 For type composite
 
 Hide fields attribute Show fields attribute object
 
 * object Additional properties
 
 fetch_fields array[object]
 
 For type lookup
 
 format string
 
 A custom format for date type runtime fields.
 
 input_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_index string
 
 script object
 
 type string Required
 
 Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
 
 stats array[string]
 
 The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
- id string
- params object
 
 Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
 Hide params attribute Show params attribute object
 
 * object Additional properties
- lang string
 
 Any of:
 ScriptLanguage string ScriptLanguage string
 
 Values are painless, expression, mustache, or java.
- options object
 Hide options attribute Show options attribute object
 
 * string Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- result object Required

POST /_scripts/painless/_execute

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}"'

Request examples

Run `POST /_scripts/painless/_execute`. The `painless_test` context is the default context. It runs scripts without additional parameters. The only variable that is available is `params`, which can be used to access user defined values. The result of the script is always converted to a string.

{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}

Run `POST /_scripts/painless/_execute` with a `filter` context. It treats scripts as if they were run inside a script query. For testing purposes, a document must be provided so that it will be temporarily indexed in-memory and is accessible from the script. More precisely, the `_source`, stored fields, and doc values of such a document are available to the script being tested.

{
  "script": {
    "source": "doc['field'].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "field": "four"
    }
  }
}

Run `POST /_scripts/painless/_execute` with a `score` context. It treats scripts as if they were run inside a `script_score` function in a `function_score` query.

{
  "script": {
    "source": "doc['rank'].value / params.max_rank",
    "params": {
      "max_rank": 5.0
    }
  },
  "context": "score",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "rank": 4
    }
  }
}

Response examples (200)

A successful response from `POST /_scripts/painless/_execute` with a `painless_test` context.

{
  "result": "0.1"
}

A successful response from `POST /_scripts/painless/_execute` with a `filter` context.

{
  "result": true
}

A successful response from `POST /_scripts/painless/_execute` with a `score` context.

{
  "result": 0.8
}

Create or update a search application Beta

PUT /_application/search_application/{name}

Api key auth Basic auth Bearer auth

Path parameters

name string Required

The name of the search application to be created or updated.

Query parameters

create boolean

If true, this request cannot replace or update existing Search Applications.

application/json

Body Required

indices array[string] Required

Indices that are part of the Search Application.
analytics_collection_name string
template object
Hide template attribute Show template attribute object
- script object Required
 Hide script attributes Show script attributes object
 
 source string | object
 
 One of:
 ScriptSource string SearchRequestBody object
 
 Hide attributes Show attributes
 
 aggregations object
 
 Defines the aggregations that are run as part of the search request.
 
 External documentation
 
 collapse object
 External documentation
 
 explain boolean
 
 If true, the request returns detailed information about score computation as part of a hit.
 
 ext object
 
 Configuration of search extensions defined by Elasticsearch plugins.
 
 Hide ext attribute Show ext attribute object
 
 * object Additional properties
 
 from number
 
 The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 track_total_hits boolean | number
 
 Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
 
 indices_boost array[object]
 
 Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
 
 External documentation
 
 Hide indices_boost attribute Show indices_boost attribute object
 
 * number Additional properties
 
 docvalue_fields array[object]
 
 An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
 
 External documentation
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 knn object | array[object]
 
 The approximate kNN search to run.
 
 One of:
 KnnSearch object array-2 array[object]
 
 Hide attributes Show attributes
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 query_vector array[number]
 
 query_vector_builder object
 
 k number
 
 The final number of nearest neighbors to return as top hits
 
 num_candidates number
 
 The number of nearest neighbor candidates to consider per shard
 
 boost number
 
 Boost value to apply to kNN scores
 
 filter
 
 similarity number
 
 The minimum similarity for a vector to be considered a match
 
 inner_hits object
 
 rescore_vector object
 
 rank object
 
 Hide rank attribute Show rank attribute object
 
 rrf object
 
 min_score number
 
 The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
 
 post_filter object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 profile boolean
 
 Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
 
 query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 rescore object | array[object]
 
 Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
 
 One of:
 Rescore object array-2 array[object]
 
 retriever object
 
 Hide retriever attributes Show retriever attributes object
 
 standard object
 
 knn object
 
 rrf object
 
 text_similarity_reranker object
 
 rule object
 
 script_fields object
 
 Retrieve a script evaluation (based on different fields) for each hit.
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 ignore_failure boolean
 
 search_after array[number | string | boolean | null]
 
 A field value.
 
 size number
 
 The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
 
 slice object
 
 Hide slice attributes Show slice attributes object
 
 field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 id string Required
 
 max number Required
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 fields array[object]
 
 An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
 
 Hide fields attributes Show fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 suggest object
 
 Hide suggest attribute Show suggest attribute object
 
 text string
 
 Global suggest text, to avoid repetition when the same text is used in several suggesters
 
 terminate_after number
 
 The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
 
 IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
 
 If set to 0 (default), the query does not terminate early.
 
 timeout string
 
 The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
 
 track_scores boolean
 
 If true, calculate and return document scores, even if the scores are not used for sorting.
 
 version boolean
 
 If true, the request returns the document version as part of a hit.
 
 seq_no_primary_term boolean
 
 If true, the request returns sequence number and primary term of the last modification of each hit.
 
 External documentation
 
 stored_fields string | array[string]
 
 pit object
 
 Hide pit attributes Show pit attributes object
 
 id string Required
 
 keep_alive string
 
 A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
 
 runtime_mappings object
 
 Hide runtime_mappings attribute Show runtime_mappings attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 fields object
 
 For type composite
 
 fetch_fields array[object]
 
 For type lookup
 
 format string
 
 A custom format for date type runtime fields.
 
 input_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_field string
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 target_index string
 
 script object
 
 type string Required
 
 Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
 
 stats array[string]
 
 The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
 
 id string
 
 params object
 
 Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
 
 Hide params attribute Show params attribute object
 
 * object Additional properties
 
 lang string
 
 Any of:
 ScriptLanguage string ScriptLanguage string
 
 Values are painless, expression, mustache, or java.
 
 options object
 
 Hide options attribute Show options attribute object
 
 * string Additional properties

Responses

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

PUT /_application/search_application/{name}

curl \
 --request PUT 'http://api.example.com/_application/search_application/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"indices\": [ \"index1\", \"index2\" ],\n  \"template\": {\n    \"script\": {\n      \"source\": {\n        \"query\": {\n          \"query_string\": {\n            \"query\": \"{{query_string}}\",\n            \"default_field\": \"{{default_field}}\"\n          }\n        }\n      },\n      \"params\": {\n        \"query_string\": \"*\",\n        \"default_field\": \"*\"\n      }\n    },\n    \"dictionary\": {\n      \"properties\": {\n        \"query_string\": {\n          \"type\": \"string\"\n        },\n        \"default_field\": {\n          \"type\": \"string\",\n          \"enum\": [\n            \"title\",\n            \"description\"\n          ]\n        },\n        \"additionalProperties\": false\n      },\n      \"required\": [\n        \"query_string\"\n      ]\n    }\n  }\n}"'

Request example

Run `PUT _application/search_application/my-app` to create or update a search application called `my-app`. When the dictionary parameter is specified, the search application search API will perform the following parameter validation: it accepts only the `query_string` and `default_field` parameters; it verifies that `query_string` and `default_field` are both strings; it accepts `default_field` only if it takes the values title or description. If the parameters are not valid, the search application search API will return an error.

{
  "indices": [ "index1", "index2" ],
  "template": {
    "script": {
      "source": {
        "query": {
          "query_string": {
            "query": "{{query_string}}",
            "default_field": "{{default_field}}"
          }
        }
      },
      "params": {
        "query_string": "*",
        "default_field": "*"
      }
    },
    "dictionary": {
      "properties": {
        "query_string": {
          "type": "string"
        },
        "default_field": {
          "type": "string",
          "enum": [
            "title",
            "description"
          ]
        },
        "additionalProperties": false
      },
      "required": [
        "query_string"
      ]
    }
  }
}

Create or update application privileges Added in 6.4.0

POST /_security/privilege

Api key auth Basic auth Bearer auth

To use this API, you must have one of the following privileges:

The manage_security cluster privilege (or a greater privilege such as all).
The "Manage Application Privileges" global privilege for the application being referenced in the request.

Application names are formed from a prefix, with an optional suffix that conform to the following rules:

The prefix must begin with a lowercase ASCII letter.
The prefix must contain only ASCII letters or digits.
The prefix must be at least 3 characters long.
If the suffix exists, it must begin with either a dash - or _.
The suffix cannot contain any of the following characters: \, /, *, ?, ", <, >, |, ,, *.
No part of the name can contain whitespace.

Privilege names must begin with a lowercase ASCII letter and must contain only ASCII letters and digits along with the characters _, -, and ..

Action names can contain any number of printable ASCII characters and must contain at least one of the following characters: /, *, :.

External documentation

Query parameters

refresh string

If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

Values are true, false, or wait_for.

application/json

Body Required

* object Additional properties
Hide * attribute Show * attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  actions array[string] Required
  
  application string
  
  name string
  
  metadata object
  
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object
  
  Hide * attribute Show * attribute object
  
  created boolean Required

POST /_security/privilege

curl \
 --request POST 'http://api.example.com/_security/privilege' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"myapp\": {\n    \"read\": {\n      \"actions\": [ \n        \"data:read/*\" , \n        \"action:login\" ],\n        \"metadata\": { \n          \"description\": \"Read access to myapp\"\n        }\n      }\n    }\n}"'

Request examples

Run `PUT /_security/privilege` to add a single application privilege. The wildcard (`*`) means that this privilege grants access to all actions that start with `data:read/`. Elasticsearch does not assign any meaning to these actions. However, if the request includes an application privilege such as `data:read/users` or `data:read/settings`, the has privileges API respects the use of a wildcard and returns `true`.

{
  "myapp": {
    "read": {
      "actions": [ 
        "data:read/*" , 
        "action:login" ],
        "metadata": { 
          "description": "Read access to myapp"
        }
      }
    }
}

Run `PUT /_security/privilege` to add multiple application privileges.

{
  "app01": {
    "read": {
      "actions": [ "action:login", "data:read/*" ]
    },
    "write": {
      "actions": [ "action:login", "data:write/*" ]
    }
  },
  "app02": {
    "all": {
      "actions": [ "*" ]
    }
  }
}

Response examples (200)

A successful response from `PUT /_security/privilege`.

{
  "myapp": {
    "read": {
      "created": true 
    }
  }
}

A successful response from `PUT /_security/privilege`. The `created` property indicates whether the privileges have been created or updated.

{
  "app02": {
    "all": {
      "created": true
    }
  },
  "app01": {
    "read": {
      "created": true
    },
    "write": {
      "created": true
    }
  }
}

Get user privileges Added in 6.5.0

GET /_security/user/_privileges

Api key auth Basic auth Bearer auth

Get the security privileges for the logged in user. 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. To check whether a user has a specific list of privileges, use the has privileges API.

Query parameters

application string

The name of the application. Application privileges are always associated with exactly one application. If you do not specify this parameter, the API returns information about all privileges for all applications.
priviledge string

The name of the privilege. If you do not specify this parameter, the API returns information about all privileges for the requested application.
username string | null

Responses

200 application/json
Hide response attributes Show response attributes object
- applications array[object] Required
  
  Hide applications attributes Show applications attributes object
  
  application string Required
  
  The name of the application to which this entry applies.
  
  privileges array[string] Required
  
  A list of strings, where each element is the name of an application privilege or action.
  
  resources array[string] Required
  
  A list resources to which the privileges are applied.
- cluster array[string] Required
- remote_cluster array[object]
  
  Hide remote_cluster attributes Show remote_cluster attributes object
  
  clusters string | array[string] Required
  
  privileges array[string] Required
  
  The cluster level privileges that owners of the role have on the remote cluster.
  
  Values are monitor_enrich or monitor_stats.
- global array[object] Required
  
  Hide global attribute Show global attribute object
  
  application object Required
  
  Hide application attribute Show application attribute object
  
  manage object Required
  
  Hide manage attribute Show manage attribute object
  
  applications array[string] Required
- indices array[object] Required
  
  Hide indices attributes Show indices attributes object
  
  field_security array[object]
  
  The document fields that the owners of the role have read access to.
  
  External documentation
  
  Hide field_security attributes Show field_security attributes object
  
  except string | array[string]
  
  grant string | array[string]
  
  names string | array[string]
  
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  
  One of:
  IndexName string array-2 array[string]
  
  privileges array[string] Required
  
  The index level privileges that owners of the role have on the specified indices.
  
  query array[string | object]
  
  Search queries that define the documents the user has access to. A document within the specified indices must match these queries for it to be accessible by the owners of the role.
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  One of:
  IndicesPrivilegesQuery string QueryContainer object RoleTemplateQuery object
  
  allow_restricted_indices boolean Required
  
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
- remote_indices array[object]
  
  Hide remote_indices attributes Show remote_indices attributes object
  
  field_security array[object]
  
  The document fields that the owners of the role have read access to.
  
  External documentation
  
  Hide field_security attributes Show field_security attributes object
  
  except string | array[string]
  
  grant string | array[string]
  
  names string | array[string]
  
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  
  One of:
  IndexName string array-2 array[string]
  
  privileges array[string] Required
  
  The index level privileges that owners of the role have on the specified indices.
  
  query array[string | object]
  
  Search queries that define the documents the user has access to. A document within the specified indices must match these queries for it to be accessible by the owners of the role.
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  One of:
  IndicesPrivilegesQuery string QueryContainer object RoleTemplateQuery object
  
  allow_restricted_indices boolean Required
  
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  
  clusters array[string] Required
- run_as array[string] Required

GET /_security/user/_privileges

curl \
 --request GET 'http://api.example.com/_security/user/_privileges' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_security/user/_privileges`.

{
  "cluster" : [
    "all"
  ],
  "global" : [ ],
  "indices" : [
    {
      "names" : [
        "*"
      ],
      "privileges" : [
        "all"
      ],
      "allow_restricted_indices" : true
    }
  ],
  "applications" : [
    {
      "application" : "*",
      "privileges" : [
        "*"
      ],
      "resources" : [
        "*"
      ]
    }
  ],
  "run_as" : [
    "*"
  ]
}

Get an enrich policy Added in 7.5.0

Run multiple Fleet searches Technical preview

Body object Required

_source boolean | object

filter object | array[object]

filter object | array[object]

filter object | array[object]

filter object | array[object]

filter object | array[object]

source string | object

lang string

source string | object

lang string

Run a Fleet search Technical preview

type string

rescore object | array[object]

source string | object

lang string

sort string | object | array[string | object]

source string | object

lang string

_source boolean | object

source string | object

lang string

total object | number

_score number | string | null

matched_queries array[string] | object

max_score number | string | null

Split an index Added in 6.1.0

Create an inference endpoint Added in 8.11.0

Body Required

Delete a filter Added in 5.4.0

Preview features used by data frame analytics Added in 7.13.0

source string | object

lang string

training_percent string | number

training_percent string | number

Get rollup job information Deprecated Technical preview

Run a script Technical preview

source string | object

filter object | array[object]

lang string

Create or update a search application Beta

Body Required

source string | object

lang string

Create or update application privileges Added in 6.4.0

Body Required

Get user privileges Added in 6.5.0

names string | array[string]

names string | array[string]