elasticsearch/docs/reference/query-dsl/match-query.asciidoc

[[query-dsl-match-query]]
=== Match Query


`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.

Here is an example when providing additional parameters (note the slight
change in structure, `message` is the field name):

[source,js]
--------------------------------------------------
GET /_search
{
    "query": {
        "match" : {
            "message" : {
                "query" : "this is a test",
                "operator" : "and"
            }
        }
    }
}
--------------------------------------------------
// CONSOLE

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 that fuzzy matching is not applied to terms with synonyms, as 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 testt",
                "fuzziness": "AUTO"
            }
        }
    }
}
--------------------------------------------------
// 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-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).

**************************************************