Elasticsearch / Basic: document and query contracts / Lesson 4
Boolean queries and filter context
Separate required eligibility from relevance and state optional-clause requirements explicitly.
On this page
Lesson goals
- Read must, filter, must_not and should.
- Choose exact, full-text and range predicates from mappings.
Eligibility and ranking answer different questions
A visitor wants bronze navigation objects that are currently displayed. Display status is a yes-or-no eligibility rule; title similarity influences ordering among eligible artifacts. Put exact constraints into filter context and full-text relevance into query context. Filter context ignores scoring, but that does not promise every filter is automatically cached or free. Cache eligibility and actual benefit depend on query and workload behavior. Keep the product requirement in plain language beside the DSL so a reviewer can check whether the query allows the right population before debating boost numbers.
Use fields according to their mapping
The body below belongs to POST museum-artifacts-v1/_search. match analyzes the title query, term checks an exact keyword status, and range applies numeric boundaries to year. These clauses are not interchangeable string-matching shortcuts. A term query on an analyzed text field asks for an indexed term, while a match query on a keyword value does not create the same token model as a text field. Confirm field names and types in the actual mapping. The expected result is only the qualifying population; exact relevance scores require engine execution and are not fabricated here.
{"query":{"bool":{"must":[{"match":{"title":"bronze compass"}}],"filter":[{"term":{"status":"displayed"}},{"range":{"year":{"gte":1800,"lt":1900}}}]}}}Only matching titles with displayed status and a nineteenth-century year qualify. Match uses its documented default token-combination behavior unless configured.
Optional clauses can become unexpectedly optional
A bool containing should clauses alone normally requires at least one should match. When must or filter is also present, the default minimum_should_match becomes zero. Adding a status filter can therefore turn an apparent alternative-title requirement into optional score boosts. State minimum_should_match explicitly when one of the alternatives is required. Distinguish “prefer these materials” from “must be one of these materials.” A relevance change should not accidentally broaden access or inventory eligibility. Use a fixture containing an eligible status but none of the optional alternatives to expose this defect.
{"query":{"bool":{"filter":[{"term":{"status":"displayed"}}],"should":[{"term":{"material":"bronze"}},{"term":{"material":"brass"}}],"minimum_should_match":1}}}Assumes material is keyword. Displayed artifacts must also have bronze or brass material; the alternatives are not merely optional boosts.
Exclusion is not positive presence
must_not removes documents that match its clause. A document with no indexed status may survive must_not status=withdrawn because it does not match that forbidden value. If a known status is required, add the positive eligibility condition or a deliberate exists requirement. exists itself concerns indexed values, not simply a key visible in _source; NULL, empty arrays, ignored values and mapping behavior affect it. Keep source presence, indexed presence and business completeness distinct. A negative rule alone rarely expresses a complete catalog publication policy.
Validate the query shape before tuning scores
Keep a small relevance fixture with a good title match, a wrong status, a boundary year, a missing material and a document matching none of the alternatives. Predict eligibility by hand before examining ranking. User values should be encoded as JSON through the client library, not concatenated into JSON text. Field names and supported operators still need application allowlists. A general search API accepting arbitrary DSL can expose expensive or unauthorized capabilities even when JSON escaping is correct. Review pagination, result fields and access filters as part of the same request contract.
Common errors and fixes
A filter unexpectedly broadens the result set
- Why it happens
- Adding filter changed the default should requirement to zero.
- How to fix it
- Set the intended minimum_should_match explicitly.
- Prevent it next time
- Test a document satisfying filters but none of the alternatives.
Exact status matching fails
- Why it happens
- The value, case or field representation differs from the keyword contract.
- How to fix it
- Inspect mapping and canonical status values.
- Prevent it next time
- Normalize controlled vocabulary at ingestion and document its exact casing.
Missing-status documents pass an exclusion
- Why it happens
- A negative condition was mistaken for a required positive value.
- How to fix it
- Add the intended positive status or indexed-presence condition.
- Prevent it next time
- Include absent and ignored fields in publication-policy fixtures.
Check your understanding
1. A bool has a displayed filter and two should material terms. Without an explicit minimum, must either material match?
Show worked solution
No. With a filter present, the default minimum_should_match is zero. Set it to one if at least one material is mandatory. If materials are only preferences, zero can be correct, but document that intent and verify a displayed artifact outside both material categories.
2. Does must_not withdrawn guarantee a known publishable status?
Show worked solution
No. An artifact with no indexed status can pass that exclusion. Require the approved positive state or another explicit completeness rule. Inspect mapping when exists behaves unexpectedly, because a source key containing NULL does not necessarily create an indexed value.
Key takeaways
- Use scoring for relevance and positive filters for eligibility.
- Explicit optional-clause requirements prevent silent semantic changes.