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.
Loading article