Term query #

Returns documents that contain an exact term in a provided field.

You can use the term query to find documents based on a precise value such as a price, a product ID, or a username. It is also the atom the rest of the term-level family resolves to: terms expands into a should of term clauses, and prefix / wildcard / regexp / fuzzy all resolve to term sets before execution.

Inside a nested query: supported — the value is matched per array element. On text fields prefer match; term targets exact keyword / numeric / date values.

How it works #

The value is looked up verbatim in the field’s index — no analyzer and no normalizer runs on it, so what you send must equal exactly what was indexed, including whitespace and capitalization.

Which index serves the lookup depends on the field type:

• keyword / text — a point lookup in the inverted index’s term dictionary, then the matching postings list. On text fields the stored terms are the analyzer’s output (the standard analyzer lowercases), so "value": "Error" finds nothing when every token was indexed as error. Prefer match for analyzed text — it runs the analyzer for you.
• numeric / date — the per-field BKD range index (or the column store’s value-sorted region on merged segments without a BKD index): the dispatcher routes numeric term queries there, because a text-dictionary lookup of a number would always miss. The bound is matched as a single point.
• boolean — the column store’s Bool column. String values normalize first ("true", "1", "yes", "ok" count as true; "false", "0", "no" as false).

Scoring. On keyword / text the hit is scored with BM25 like any postings match, so rare values rank higher. On numeric, date and boolean fields the hit gets a constant score — the boost (1.0 by default) — which makes those forms natural bool filter clauses: they constrain the result set without distorting relevance.

Examples #

The following search returns the log lines whose level is exactly error — 25 of the 150 documents in the logs dataset.

GET /_search
{
  "query": {
    "term": {
      "field": "org.id",
      "value": "infini"
    }
  }
}

Use cases #

• Enums and statuses. level, status, tier are keyword fields with a closed vocabulary — term on sales.status = "pending" returns 40 of the 120 sales, term on customers.tier = "gold" returns 4 of 20.
• Exact numeric points. A term on sales.price = 45 matches the 20 sales at that price through the BKD index — the one-value special case of a range query.
• ID lookups. Slugs, SKUs, hostnames (host = "web-01" → 50 of 150 log lines) — values you want whole, never tokenized or scored by frequency.
• Filter clauses. Inside bool.filter, a term’s BM25 input is ignored anyway, so exact-value filtering costs nothing in relevance quality.
• Tag membership. A term on the articles.tags keyword array ("search") matches the 2 articles carrying that tag — array fields index each value as a term.

Parameters for term #

• field
  (Required, string) Field you wish to search.
• value
  (Required, string, number or boolean) Term you wish to find in the provided field. To return a document, the term must exactly match the field value, including whitespace and capitalization.
• case_insensitive
  (Optional, boolean) Allows ASCII case insensitive matching of the value with the indexed field values when set to true. Default is false.
• boost
  (Optional, float, default: 1.0) Decrease or increase the relevance scores of the query.

Related #

• terms — any-of-a-set over exact values; expands to a bool should of term clauses.
• range — the interval generalization for numeric and date fields, served by the same BKD index.
• fuzzy — near-miss matching when the exact term is unknown or misspelled.
• keys — matching by document identity instead of by field value.
• match — the analyzed alternative for text fields.
• terms aggregation — the bucket view of the same keyword vocabulary a term query filters on.