AWS Builder Center
Filters vs. queries: make OpenSearch fast and correct

Filters vs. queries: make OpenSearch fast and correct

In this article, you learn when to use filter context instead of query context, why filters are faster, and how term and range queries differ from match.

Series: Search on OpenSearch (8 articles)

  1. …
  2. 3
    Filters vs. queries: make OpenSearch fast and correct This article
OpenSearch Specialist Solutions Architect at AWS
In  Part 2  you met the bool  query and its four clauses. Two of them,  must  and  filter , both require a document to match, so it is fair to ask why you would ever choose one over the other. The answer is scoring, and it affects both correctness and speed. This article explains query context and filter context and shows when each is the right tool.
This is Part 3 of a beginner series on search with  Amazon OpenSearch Service . Continue with the  books  index and Dev Tools from the earlier parts.

Query context asks "how well?"; filter context asks "yes or no?"

When a query clause runs in query context, OpenSearch computes a relevance score ( _score ) that measures how well each document matches. The  match  clauses in  must  and  should  run in query context, which is why a fantasy title ranked higher in Part 2.
When a clause runs in filter context, OpenSearch answers a simple yes/no: does the document match the criterion or not? No score is computed. Clauses inside the  bool  query's  filter  (and  must_not ) run in filter context. Because filter context does not score, OpenSearch can cache the result of a filter and reuse it across queries, which makes repeated filters fast.
The practical rule: use query context for full-text relevance, and filter context for exact, structured criteria where ranking does not matter.

term and range: the workhorses of filter context

Two query types show up constantly in filters:
  • term matches an exact value, with no analysis. Use it on  keyword  fields and other exact values such as an identifier, a status, or a category. Because  term  does not analyze the input, it is case- and format-sensitive.
  • range matches values in a numeric, date, or other ordered range, using  gte ,  lte ,  gt , and  lt .
Here is a search that finds books with "wizard" in the title (scored), filtered to the fantasy genre and to the years 2000 through 2020 (not scored).
GET books/_search
{
"query": {
"bool": {
"must": [
{ "match": { "title": "wizard" } }
],
"filter": [
{ "term": { "genre": "fantasy" } },
{ "range": { "year": { "gte": 2000, "lte": 2020 } } }
]
}
}
}
The  match  clause decides ranking. The  term  and  range  clauses only narrow the set, and OpenSearch can cache them.

Why term and match are not interchangeable

A common beginner surprise:  term  on an analyzed text field often returns nothing. If  genre  is a  text  field, its values were analyzed (for example, lowercased) at index time, so a  term  query for "Fantasy" will not match the stored term "fantasy". Two ways to avoid this:
  • Filter on a  keyword  field, which stores the value exactly as provided. In the default dynamic mapping, a string field is indexed both as  text  and as a  text.keyword  sub-field, so you can filter on  genre.keyword .
  • Use  match  if you genuinely want analyzed, full-text behavior.
Reach for  term  on fields you intend to match exactly, and map those fields as  keyword .

A decision table

Use this to decide where a condition belongs:
Your condition
Clause
Query type
Scored?
Full-text relevance ("about wizards")
must / should
match
Yes
Exact category, status, or ID
filter
term
No
Numeric or date range
filter
range
No
Exclude a value
must_not
term / range
No
If you are filtering and see no results, check whether you are running  term  against an analyzed  text  field. That single issue accounts for most "my filter returns nothing" reports.

Where this series goes next

You now know to reserve scoring for the parts of a query where ranking matters, and to push exact criteria into filter context for speed. In Part 4, you move from finding documents to summarizing them with aggregations and facets, including the setting that makes facet counts accurate on an index with more than one shard.

Series: Search on OpenSearch (8 articles)

  1. …
  2. 3
    Filters vs. queries: make OpenSearch fast and correct This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article