Adjustments to match Opster, readability (elastic#119812)

* Adjustments to match Opster, readability https://opster.com/guides/elasticsearch/search-apis/elasticsearch-bool-queries/ * Edits Co-authored-by: George Wallace <[email protected]> * Spacing Co-authored-by: George Wallace <[email protected]> --------- Co-authored-by: George Wallace <[email protected]>
georgewallace · Jan 13, 2025 · 8b13cc2 · 8b13cc2
1 parent faf5665
commit 8b13cc2
Showing 1 changed file with 8 additions and 5 deletions.
diff --git a/docs/reference/query-dsl/bool-query.asciidoc b/docs/reference/query-dsl/bool-query.asciidoc
@@ -13,21 +13,24 @@ occurrence types are:
 |=======================================================================
 |Occur |Description
 |`must` |The clause (query) must appear in matching documents and will
-contribute to the score.
+contribute to the score. Each query defined under a `must` acts as a logical "AND", returning only documents that match _all_ the specified queries.
+
+|`should` |The clause (query) should appear in the matching document. Each query defined under a `should` acts as a logical "OR", returning documents that match _any_ of the specified queries.
 
 |`filter` |The clause (query) must appear in matching documents. However unlike
 `must` the score of the query will be ignored. Filter clauses are executed
 in <<query-filter-context,filter context>>, meaning that scoring is ignored
-and clauses are considered for caching.
-
-|`should` |The clause (query) should appear in the matching document.
+and clauses are considered for caching. Each query defined under a `filter` acts as a logical "AND", returning only documents that match _all_ the specified queries.
 
 |`must_not` |The clause (query) must not appear in the matching
 documents. Clauses are executed in <<query-filter-context,filter context>> meaning
 that scoring is ignored and clauses are considered for caching. Because scoring is
-ignored, a score of `0` for all documents is returned.
+ignored, a score of `0` for all documents is returned. Each query defined under a `must_not` acts as a logical "NOT", returning only documents that do not match any of the specified queries.
+
 |=======================================================================
 
+The `must` and `should` clauses function as logical AND, OR operators, contributing to the scoring of results. However, these results will not be cached for faster retrieval. In contrast, the `filter` and `must_not` clauses are used to include or exclude results without impacting the score, unless used within a `constant_score` query.
+
 The `bool` query takes a _more-matches-is-better_ approach, so the score from
 each matching `must` or `should` clause will be added together to provide the
 final `_score` for each document.