200 lines
6.7 KiB
Plaintext
200 lines
6.7 KiB
Plaintext
[[query-dsl-match-query]]
|
|
=== Match query
|
|
++++
|
|
<titleabbrev>Match</titleabbrev>
|
|
++++
|
|
|
|
|
|
`match` queries accept text/numerics/dates, analyzes
|
|
them, and constructs a query. For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"match" : {
|
|
"message" : "this is a test"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Note, `message` is the name of a field, you can substitute the name of
|
|
any field instead.
|
|
|
|
[[query-dsl-match-query-boolean]]
|
|
==== match
|
|
|
|
The `match` query is of type `boolean`. It means that the text
|
|
provided is analyzed and the analysis process constructs a boolean query
|
|
from the provided text. The `operator` flag can be set to `or` or `and`
|
|
to control the boolean clauses (defaults to `or`). The minimum number of
|
|
optional `should` clauses to match can be set using the
|
|
<<query-dsl-minimum-should-match,`minimum_should_match`>>
|
|
parameter.
|
|
|
|
The `analyzer` can be set to control which analyzer will perform the
|
|
analysis process on the text. It defaults to the field explicit mapping
|
|
definition, or the default search analyzer.
|
|
|
|
The `lenient` parameter can be set to `true` to ignore exceptions caused by
|
|
data-type mismatches, such as trying to query a numeric field with a text
|
|
query string. Defaults to `false`.
|
|
|
|
[[query-dsl-match-query-fuzziness]]
|
|
===== Fuzziness
|
|
|
|
`fuzziness` allows _fuzzy matching_ based on the type of field being queried.
|
|
See <<fuzziness>> for allowed settings.
|
|
|
|
The `prefix_length` and
|
|
`max_expansions` can be set in this case to control the fuzzy process.
|
|
If the fuzzy option is set the query will use `top_terms_blended_freqs_${max_expansions}`
|
|
as its <<query-dsl-multi-term-rewrite,rewrite
|
|
method>> the `fuzzy_rewrite` parameter allows to control how the query will get
|
|
rewritten.
|
|
|
|
Fuzzy transpositions (`ab` -> `ba`) are allowed by default but can be disabled
|
|
by setting `fuzzy_transpositions` to `false`.
|
|
|
|
NOTE: Fuzzy matching is not applied to terms with synonyms or in cases where the
|
|
analysis process produces multiple tokens at the same position. Under the hood
|
|
these terms are expanded to a special synonym query that blends term frequencies,
|
|
which does not support fuzzy expansion.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "this is a test",
|
|
"operator" : "and"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[[query-dsl-match-query-zero]]
|
|
===== Zero terms query
|
|
If the analyzer used removes all tokens in a query like a `stop` filter
|
|
does, the default behavior is to match no documents at all. In order to
|
|
change that the `zero_terms_query` option can be used, which accepts
|
|
`none` (default) and `all` which corresponds to a `match_all` query.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "to be or not to be",
|
|
"operator" : "and",
|
|
"zero_terms_query": "all"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[[query-dsl-match-query-cutoff]]
|
|
===== Cutoff frequency
|
|
|
|
deprecated[7.3.0,"This option can be omitted as the <<query-dsl-match-query>> can skip block of documents efficiently, without any configuration, provided that the total number of hits is not tracked."]
|
|
|
|
The match query supports a `cutoff_frequency` that allows
|
|
specifying an absolute or relative document frequency where high
|
|
frequency terms are moved into an optional subquery and are only scored
|
|
if one of the low frequency (below the cutoff) terms in the case of an
|
|
`or` operator or all of the low frequency terms in the case of an `and`
|
|
operator match.
|
|
|
|
This query allows handling `stopwords` dynamically at runtime, is domain
|
|
independent and doesn't require a stopword file. It prevents scoring /
|
|
iterating high frequency terms and only takes the terms into account if a
|
|
more significant / lower frequency term matches a document. Yet, if all
|
|
of the query terms are above the given `cutoff_frequency` the query is
|
|
automatically transformed into a pure conjunction (`and`) query to
|
|
ensure fast execution.
|
|
|
|
The `cutoff_frequency` can either be relative to the total number of
|
|
documents if in the range `[0..1)` or absolute if greater or equal to
|
|
`1.0`.
|
|
|
|
Here is an example showing a query composed of stopwords exclusively:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "to be or not to be",
|
|
"cutoff_frequency" : 0.001
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[warning:Deprecated field [cutoff_frequency] used, replaced by [you can omit this option, the [match] query can skip block of documents efficiently if the total number of hits is not tracked]]
|
|
|
|
IMPORTANT: The `cutoff_frequency` option operates on a per-shard-level. This means
|
|
that when trying it out on test indexes with low document numbers you
|
|
should follow the advice in {defguide}/relevance-is-broken.html[Relevance is broken].
|
|
|
|
[[query-dsl-match-query-synonyms]]
|
|
===== Synonyms
|
|
|
|
The `match` query supports multi-terms synonym expansion with the <<analysis-synonym-graph-tokenfilter,
|
|
synonym_graph>> token filter. When this filter is used, the parser creates a phrase query for each multi-terms synonyms.
|
|
For example, the following synonym: `"ny, new york" would produce:`
|
|
|
|
`(ny OR ("new york"))`
|
|
|
|
It is also possible to match multi terms synonyms with conjunctions instead:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"match" : {
|
|
"message": {
|
|
"query" : "ny city",
|
|
"auto_generate_synonyms_phrase_query" : false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The example above creates a boolean query:
|
|
|
|
`(ny OR (new AND york)) city`
|
|
|
|
that matches documents with the term `ny` or the conjunction `new AND york`.
|
|
By default the parameter `auto_generate_synonyms_phrase_query` is set to `true`.
|
|
|
|
|
|
.Comparison to query_string / field
|
|
**************************************************
|
|
|
|
The match family of queries does not go through a "query parsing"
|
|
process. It does not support field name prefixes, wildcard characters,
|
|
or other "advanced" features. For this reason, chances of it failing are
|
|
very small / non existent, and it provides an excellent behavior when it
|
|
comes to just analyze and run that text as a query behavior (which is
|
|
usually what a text search box does).
|
|
|
|
**************************************************
|