Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 43 ยท Searching

Query DSL Basics

Learn the Elasticsearch Query DSL: query vs filter context, match_all, match, term, terms, range, exists, ids and the bool query, with a runnable evaluator.

Elasticsearch searches are written in the Query DSL, a JSON language where a query is a tree of small building blocks. You send it to GET /index/_search in the query field, and the result is a list of hits, each with a relevance _score. Once you know about ten building blocks and how they combine, you can read almost any query you meet.

This lesson covers the core ones: match_all, match, term, terms, range, exists, ids and bool, and the important difference between query context and filter context. The real requests are read-only; a JavaScript evaluator below runs a subset of the DSL so you can experiment.

HTTP
GET /products/_search
{
  "query": {
    "match": { "name": "trail shoe" }
  },
  "size": 10
}

A query clause is an object with one key (the query type), whose value holds the field and its parameters. The response contains hits.total (how many documents matched) and hits.hits, an array with _id, _score and _source for each hit, sorted by score by default.

Query context versus filter context

Every clause answers one of two questions:

  • Query context: "How well does this document match?" It produces a _score.
  • Filter context: "Does this document match, yes or no?" No score is computed, and results can be cached by Elasticsearch, so filters are usually faster.

Rule of thumb: use query context for the text a person typed ("trail shoe"), and filter context for exact conditions such as brand, price range, stock status or dates. Inside a bool query, must and should are query context, while filter and must_not are filter context.

The building blocks

match_all matches every document with the same score. It is the default when you send no query.

HTTP
{ "query": { "match_all": {} } }

match is the standard full-text query. It runs your text through the field's analyzer (see the lesson on analysis), then looks for any of the resulting terms. By default "trail shoe" means trail OR shoe, and documents with more matching (and rarer) terms score higher.

HTTP
{ "query": { "match": { "name": "trail shoe" } } }

term looks for one exact term, with no analysis. Use it on keyword, number, date and boolean fields, not on analyzed text.

HTTP
{ "query": { "term": { "brand": "Acme" } } }

terms matches if the field has any of several exact values (an "IN" list).

HTTP
{ "query": { "terms": { "brand": ["Acme", "Zeta"] } } }

range works on numbers, dates and keywords, with gt, gte, lt, lte.

HTTP
{ "query": { "range": { "price": { "gte": 20, "lt": 100 } } } }
{ "query": { "range": { "released": { "gte": "now-30d/d" } } } }

exists matches documents that have a non-null value for a field.

HTTP
{ "query": { "exists": { "field": "discount" } } }

ids fetches documents by _id.

HTTP
{ "query": { "ids": { "values": ["1", "4"] } } }

The bool query

bool combines other queries with four clause types:

Clause Meaning Context Affects score
must Must match (AND) Query Yes
filter Must match (AND) Filter No
should Should match (OR, boosts score) Query Yes
must_not Must not match (NOT) Filter No
HTTP
GET /products/_search
{
  "query": {
    "bool": {
      "must":     [ { "match": { "name": "shoe" } } ],
      "filter":   [ { "term": { "in_stock": true } },
                    { "range": { "price": { "lte": 100 } } } ],
      "should":   [ { "term": { "brand": "Acme" } } ],
      "must_not": [ { "term": { "category": "kids" } } ]
    }
  }
}

This reads: "shoes (scored by text relevance) that are in stock, cost at most 100, are not in the kids category, and rank higher if they are from Acme." If a bool has no must or filter, at least one should must match; otherwise should is optional and only boosts the score. The lesson on bool and compound queries goes much deeper.

Try a mini evaluator

This stand-in runs a subset of the DSL on an in-memory product list. The scoring is deliberately simple (the number of matched query terms), not real BM25, but the structure of the logic is the same: filters decide membership, queries add score.

JS A mini Query DSL evaluator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try changing the bool query: move { range: ... } from filter into must and notice the document order does not change, because in this model a range adds no score, but in the real engine it would add a small constant score in query context. Filters are the clearer way to express yes/no conditions.

Filter context in practice

In this second stand-in, a filter simply removes documents, while must clauses rank what remains. Note how a should clause reorders results without removing any.

JS Filters remove, should reorders

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • term on a text field. The index holds lowercase tokens, so term: "Acme" often finds nothing. Use match, or query a keyword sub-field such as brand.keyword.
  • Scoring when you do not need to. Put exact conditions in filter so they are cached and cheaper.
  • Forgetting size. A search returns 10 hits by default. Pagination is covered in Sorting and Pagination.
  • Misreading hits.total. By default it counts exactly only up to 10,000 hits; above that it reports a lower bound ("relation": "gte"). Set track_total_hits if you need the exact count.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main difference between query context and filter context?

    Query context answers how well a document matches. Filter context answers yes or no, skips scoring and is cacheable.
  2. 2. Which query should you use for an exact brand value stored as keyword?

    term matches one exact, un-analyzed value, which fits keyword fields.
  3. 3. Which bool clauses do NOT affect the score?

    filter and must_not run in filter context. must and should are scored.
  4. 4. What does the match query do with the text 'trail shoe' on an analyzed field?

    match applies the field's analyzer and combines the resulting terms with OR by default.

Summary

  • A search sends a JSON Query DSL tree in the query field and returns scored hits.
  • Query context scores; filter context only includes or excludes and is cacheable.
  • Core queries: match_all, match (analyzed text), term and terms (exact), range, exists, ids.
  • bool combines them: must and should score, filter and must_not do not.
  • Use match for text, term for keywords, and put exact conditions in filter.

Next: Full-Text Queries.