239 lines
7.4 KiB
Plaintext
239 lines
7.4 KiB
Plaintext
[[query-dsl-match-query]]
|
|
=== Match Query
|
|
|
|
|
|
A family of `match` queries that accepts text/numerics/dates, analyzes
|
|
them, and constructs a query. For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match" : {
|
|
"message" : "this is a test"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Note, `message` is the name of a field, you can substitute the name of
|
|
any field (including `_all`) instead.
|
|
|
|
There are three types of `match` query: `boolean`, `phrase`, and `phrase_prefix`:
|
|
|
|
[[query-dsl-match-query-boolean]]
|
|
==== boolean
|
|
|
|
The default `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.
|
|
|
|
Here is an example when providing additional parameters (note the slight
|
|
change in structure, `message` is the field name):
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "this is a test",
|
|
"operator" : "and"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[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]
|
|
--------------------------------------------------
|
|
{
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "to be or not to be",
|
|
"operator" : "and",
|
|
"zero_terms_query": "all"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[query-dsl-match-query-cutoff]]
|
|
===== Cutoff frequency
|
|
|
|
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]
|
|
--------------------------------------------------
|
|
{
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "to be or not to be",
|
|
"cutoff_frequency" : 0.001
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
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-phrase]]
|
|
==== phrase
|
|
|
|
The `match_phrase` query analyzes the text and creates a `phrase` query
|
|
out of the analyzed text. For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match_phrase" : {
|
|
"message" : "this is a test"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Since `match_phrase` is only a `type` of a `match` query, it can also be
|
|
used in the following manner:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "this is a test",
|
|
"type" : "phrase"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
A phrase query matches terms up to a configurable `slop`
|
|
(which defaults to 0) in any order. Transposed terms have a slop of 2.
|
|
|
|
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, for example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match_phrase" : {
|
|
"message" : {
|
|
"query" : "this is a test",
|
|
"analyzer" : "my_analyzer"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[query-dsl-match-query-phrase-prefix]]
|
|
==== match_phrase_prefix
|
|
|
|
The `match_phrase_prefix` is the same as `match_phrase`, except that it
|
|
allows for prefix matches on the last term in the text. For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match_phrase_prefix" : {
|
|
"message" : "this is a test"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Or:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match" : {
|
|
"message" : {
|
|
"query" : "this is a test",
|
|
"type" : "phrase_prefix"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
It accepts the same parameters as the phrase type. In addition, it also
|
|
accepts a `max_expansions` parameter that can control to how many
|
|
prefixes the last term will be expanded. It is highly recommended to set
|
|
it to an acceptable value to control the execution time of the query.
|
|
For example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"match_phrase_prefix" : {
|
|
"message" : {
|
|
"query" : "this is a test",
|
|
"max_expansions" : 10
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
.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). Also, the `phrase_prefix` type can
|
|
provide a great "as you type" behavior to automatically load search
|
|
results.
|
|
|
|
**************************************************
|