elasticsearch/docs/reference/search/terms-enum.asciidoc

[[search-terms-enum]]
=== Terms enum API
++++
<titleabbrev>Terms enum</titleabbrev>
++++

The terms enum API can be used to discover terms in the index that match
a partial string. Supported field types are <<keyword-field-type,`keyword`>>,
<<constant-keyword-field-type,`constant_keyword`>>, <<flattened,`flattened`>>,
<<version, `version`>> and <<ip, `ip`>>. This is used for auto-complete:

[source,console]
--------------------------------------------------
POST stackoverflow/_terms_enum
{
    "field" : "tags",
    "string" : "kiba"
}
--------------------------------------------------
// TEST[setup:stackoverflow]


The API returns the following response:

[source,console-result]
--------------------------------------------------
{
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "terms": [
    "kibana"
  ],
  "complete" : true
}
--------------------------------------------------

If the `complete` flag is `false`, the returned `terms` set may be incomplete
and should be treated as approximate. This can occur due to a few reasons, such
as a request timeout or a node error.

NOTE: The terms enum API may return terms from deleted documents. Deleted
documents are initially only marked as deleted. It is not until their segments
are <<index-modules-merge,merged>> that documents are actually deleted. Until
that happens, the terms enum API will return terms from these documents.

[[search-terms-enum-api-request]]
==== {api-request-title}

`GET /<target>/_terms_enum`


[[search-terms-enum-api-desc]]
==== {api-description-title}

The terms_enum API  can be used to discover terms in the index that begin with the provided
string. It is designed for low-latency look-ups used in auto-complete scenarios.


[[search-terms-enum-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Required, string) Comma-separated list of data streams, indices, and aliases
to search. Supports wildcards (`*`). To search all data streams or indices, omit
this parameter or use `*` or `_all`.

[[search-terms-enum-api-request-body]]
==== {api-request-body-title}

[[terms-enum-field-param]]
`field`::
(Mandatory, string)
Which field to match

[[terms-enum-string-param]]
`string`::
(Optional, string)
The string to match at the start of indexed terms. If not provided, all terms in the field
are considered.

[[terms-enum-size-param]]
`size`::
(Optional, integer)
How many matching terms to return. Defaults to 10

[[terms-enum-timeout-param]]
`timeout`::
(Optional, <<time-units,time value>>)
The maximum length of time to spend collecting results. Defaults to "1s" (one second).
If the timeout is exceeded the `complete` flag set to false in the response and the results may
be partial or empty.

[[terms-enum-case_insensitive-param]]
`case_insensitive`::
(Optional, boolean)
When true the provided search string is matched against index terms without case sensitivity.
Defaults to false.

[[terms-enum-index_filter-param]]
`index_filter`::
(Optional,  <<query-dsl,query object>> Allows to filter an index shard if the provided
query rewrites to `match_none`.

[[terms-enum-search_after-param]]
`search_after`::
(Optional, string)
The string after which terms in the index should be returned. Allows for a form of
pagination if the last result from one request is passed as the `search_after`
parameter for a subsequent request.