mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
8ac3c2d371
* Adjustments to match Opster, readability https://opster.com/guides/elasticsearch/search-apis/elasticsearch-bool-queries/ * Edits * Spacing --------- Co-authored-by: Kofi B <23384471+thekofimensah@users.noreply.github.com>
211 lines
6.8 KiB
Text
211 lines
6.8 KiB
Text
[[query-dsl-bool-query]]
|
|
=== Boolean query
|
|
++++
|
|
<titleabbrev>Boolean</titleabbrev>
|
|
++++
|
|
|
|
A query that matches documents matching boolean combinations of other
|
|
queries. The bool query maps to Lucene `BooleanQuery`. It is built using
|
|
one or more boolean clauses, each clause with a typed occurrence. The
|
|
occurrence types are:
|
|
|
|
[cols="<,<",options="header",]
|
|
|=======================================================================
|
|
|Occur |Description
|
|
|`must` |The clause (query) must appear in matching documents and will
|
|
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. 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. 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.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST _search
|
|
{
|
|
"query": {
|
|
"bool" : {
|
|
"must" : {
|
|
"term" : { "user.id" : "kimchy" }
|
|
},
|
|
"filter": {
|
|
"term" : { "tags" : "production" }
|
|
},
|
|
"must_not" : {
|
|
"range" : {
|
|
"age" : { "gte" : 10, "lte" : 20 }
|
|
}
|
|
},
|
|
"should" : [
|
|
{ "term" : { "tags" : "env1" } },
|
|
{ "term" : { "tags" : "deployed" } }
|
|
],
|
|
"minimum_should_match" : 1,
|
|
"boost" : 1.0
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[bool-min-should-match]]
|
|
==== Using `minimum_should_match`
|
|
|
|
You can use the `minimum_should_match` parameter to specify the number or
|
|
percentage of `should` clauses returned documents _must_ match.
|
|
|
|
If the `bool` query includes at least one `should` clause and no `must` or
|
|
`filter` clauses, the default value is `1`.
|
|
Otherwise, the default value is `0`.
|
|
|
|
For other valid values, see the
|
|
<<query-dsl-minimum-should-match, `minimum_should_match` parameter>>.
|
|
|
|
[[score-bool-filter]]
|
|
==== Scoring with `bool.filter`
|
|
|
|
Queries specified under the `filter` element have no effect on scoring --
|
|
scores are returned as `0`. Scores are only affected by the query that has
|
|
been specified. For instance, all three of the following queries return
|
|
all documents where the `status` field contains the term `active`.
|
|
|
|
This first query assigns a score of `0` to all documents, as no scoring
|
|
query has been specified:
|
|
|
|
[source,console]
|
|
---------------------------------
|
|
GET _search
|
|
{
|
|
"query": {
|
|
"bool": {
|
|
"filter": {
|
|
"term": {
|
|
"status": "active"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------------------------
|
|
|
|
This `bool` query has a `match_all` query, which assigns a score of `1.0` to
|
|
all documents.
|
|
|
|
[source,console]
|
|
---------------------------------
|
|
GET _search
|
|
{
|
|
"query": {
|
|
"bool": {
|
|
"must": {
|
|
"match_all": {}
|
|
},
|
|
"filter": {
|
|
"term": {
|
|
"status": "active"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------------------------
|
|
|
|
This `constant_score` query behaves in exactly the same way as the second example above.
|
|
The `constant_score` query assigns a score of `1.0` to all documents matched
|
|
by the filter.
|
|
|
|
[source,console]
|
|
---------------------------------
|
|
GET _search
|
|
{
|
|
"query": {
|
|
"constant_score": {
|
|
"filter": {
|
|
"term": {
|
|
"status": "active"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------------------------
|
|
|
|
[[named-queries]]
|
|
==== Named queries
|
|
|
|
Each query accepts a `_name` in its top level definition. You can use named
|
|
queries to track which queries matched returned documents. If named queries are
|
|
used, the response includes a `matched_queries` property for each hit.
|
|
|
|
NOTE: Supplying duplicate `_name` values in the same request results in undefined behavior. Queries with duplicate names may overwrite
|
|
each other. Query names are assumed to be unique within a single request.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"bool": {
|
|
"should": [
|
|
{ "match": { "name.first": { "query": "shay", "_name": "first" } } },
|
|
{ "match": { "name.last": { "query": "banon", "_name": "last" } } }
|
|
],
|
|
"filter": {
|
|
"terms": {
|
|
"name.last": [ "banon", "kimchy" ],
|
|
"_name": "test"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
The request parameter named `include_named_queries_score` controls whether scores associated
|
|
with the matched queries are returned or not. When set, the response includes a `matched_queries`
|
|
map that contains the name of the query that matched as a key and its associated score as the value.
|
|
|
|
WARNING: Note that the score might not have contributed to the final score of the document, for instance named queries that appear
|
|
in a filter or must_not contexts, or inside a clause that ignores or modifies the score like `constant_score` or `function_score_query`.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_search?include_named_queries_score
|
|
{
|
|
"query": {
|
|
"bool": {
|
|
"should": [
|
|
{ "match": { "name.first": { "query": "shay", "_name": "first" } } },
|
|
{ "match": { "name.last": { "query": "banon", "_name": "last" } } }
|
|
],
|
|
"filter": {
|
|
"terms": {
|
|
"name.last": [ "banon", "kimchy" ],
|
|
"_name": "test"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
NOTE: This functionality reruns each named query on every hit in a search
|
|
response. Typically, this adds a small overhead to a request. However, using
|
|
computationally expensive named queries on a large number of hits may add
|
|
significant overhead. For example, named queries in combination with a
|
|
`top_hits` aggregation on many buckets may lead to longer response times.
|