AWS Builder Center
From keyword box to Query DSL: match and bool

From keyword box to Query DSL: match and bool

In this article, you turn a plain keyword search into a real OpenSearch query, then combine conditions with bool so you can require, prefer, and exclude terms.

Series: Search on OpenSearch (8 articles)

  1. 2
    From keyword box to Query DSL: match and bool This article
OpenSearch Specialist Solutions Architect at AWS
In  Part 1  you indexed a few books and ran a single match  query. That is enough to return results, but real search is rarely one condition. You want "these words in the title, in this genre, published after 2000, and not out of print." This article shows you how to express that with Query DSL, the JSON query language OpenSearch uses, starting with  match  and building up to the  bool  query.
This is Part 2 of a beginner series on search with  Amazon OpenSearch Service . Use the same  books  index and OpenSearch Dashboards Dev Tools from Part 1. If you deleted the index, recreate it and add a few documents with  title ,  author ,  genre , and  year  fields before you continue.

The match query, briefly

The  match  query is the standard choice for searching text. It analyzes your search string the same way the field was analyzed at index time, then looks for the resulting terms. Analysis is why "darkness" finds "Darkness": the text is lowercased and split into terms before comparison.
GET books/_search
{
"query": {
"match": { "title": "wizard" }
}
}
A  match  query answers one question about one field. To combine questions, you need  bool .

The bool query: must, should, filter, must_not

The  bool  query wraps other queries in four clauses, each with a distinct job:
  • must — the clause must match, and it contributes to the relevance score. Multiple  must  clauses behave like AND.
  • should — the clause is preferred. A matching  should  clause raises the relevance score, so documents that match more  should  clauses rank higher.
  • filter — the clause must match, but it does not affect the score. Filters answer a yes/no question and are the subject of Part 3.
  • must_not — the clause must not match, and it does not affect the score. Use it to exclude documents.
Here is a query that requires "wizard" in the title, prefers the fantasy genre, and excludes books published before 1900.
GET books/_search
{
"query": {
"bool": {
"must": [
{ "match": { "title": "wizard" } }
],
"should": [
{ "match": { "genre": "fantasy" } }
],
"must_not": [
{ "range": { "year": { "lt": 1900 } } }
]
}
}
}
Every returned document contains "wizard" in the title and was published in 1900 or later. Among those, the fantasy titles score higher because they also match the  should  clause, so they rise to the top of  hits.hits .

Controlling how many should clauses must match

By default, if a  bool  query has no  must  clause, at least one  should  clause has to match. When you do have a  must  clause,  should  clauses are purely a scoring boost and none of them are required. You can change this with  minimum_should_match , which sets how many  should  clauses a document must satisfy.
GET books/_search
{
"query": {
"bool": {
"should": [
{ "match": { "genre": "fantasy" } },
{ "match": { "genre": "adventure" } },
{ "match": { "author": "le guin" } }
],
"minimum_should_match": 2
}
}
}
This returns books that match at least two of the three preferences.

A cheat-sheet for the four clauses

Keep this mapping in mind when you translate a search requirement into a  bool  query:
  • "Must contain X" that should also influence ranking, use must.
  • "Prefer X, rank it higher" use should.
  • "Must contain X, but I do not care about ranking" use filter.
  • "Exclude X" use must_not.

Series: Search on OpenSearch (8 articles)

  1. 2
    From keyword box to Query DSL: match and bool 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