OpenSearch/docs/reference/query-dsl/queries/query-string-query.asciidoc

[[query-dsl-query-string-query]]
=== Query String Query

A query that uses a query parser in order to parse its content. Here is
an example:

[source,js]
--------------------------------------------------
{
    "query_string" : {
        "default_field" : "content",
        "query" : "this AND that OR thus"
    }
}
--------------------------------------------------

The `query_string` top level parameters include:

[cols="<,<",options="header",]
|=======================================================================
|Parameter |Description
|`query` |The actual query to be parsed. See <<query-string-syntax>>.

|`default_field` |The default field for query terms if no prefix field
is specified. Defaults to the `index.query.default_field` index
settings, which in turn defaults to `_all`.

|`default_operator` |The default operator used if no explicit operator
is specified. For example, with a default operator of `OR`, the query
`capital of Hungary` is translated to `capital OR of OR Hungary`, and
with default operator of `AND`, the same query is translated to
`capital AND of AND Hungary`. The default value is `OR`.

|`analyzer` |The analyzer name used to analyze the query string.

|`allow_leading_wildcard` |When set, `*` or `?` are allowed as the first
character. Defaults to `true`.

|`lowercase_expanded_terms` |Whether terms of wildcard, prefix, fuzzy,
and range queries are to be automatically lower-cased or not (since they
are not analyzed). Default it `true`.

|`enable_position_increments` |Set to `true` to enable position
increments in result queries. Defaults to `true`.

|`fuzzy_max_expansions` |Controls the number of terms fuzzy queries will
expand to. Defaults to `50`

|`fuzziness` |Set the fuzziness for fuzzy queries. Defaults
to `AUTO`. See  <<fuzziness>> for allowed settings.

|`fuzzy_prefix_length` |Set the prefix length for fuzzy queries. Default
is `0`.

|`phrase_slop` |Sets the default slop for phrases. If zero, then exact
phrase matches are required. Default value is `0`.

|`boost` |Sets the boost value of the query. Defaults to `1.0`.

|`analyze_wildcard` |By default, wildcards terms in a query string are
not analyzed. By setting this value to `true`, a best effort will be
made to analyze those as well.

|`auto_generate_phrase_queries` |Default to `false`.

|`minimum_should_match` |A value controlling how many "should" clauses
in the resulting boolean query should match. It can be an absolute value
(`2`), a percentage (`30%`) or a
<<query-dsl-minimum-should-match,combination of
both>>.

|`lenient` |If set to `true` will cause format based failures (like
providing text to a numeric field) to be ignored.

|`locale` | added[1.1.0] Locale that should be used for string conversions.
Defaults to `ROOT`.
|=======================================================================

When a multi term query is being generated, one can control how it gets
rewritten using the
<<query-dsl-multi-term-rewrite,rewrite>>
parameter.

[float]
==== Default Field

When not explicitly specifying the field to search on in the query
string syntax, the `index.query.default_field` will be used to derive
which field to search on. It defaults to `_all` field.

So, if `_all` field is disabled, it might make sense to change it to set
a different default field.

[float]
==== Multi Field

The `query_string` query can also run against multiple fields. Fields can be
provided via the `"fields"` parameter (example below).

The idea of running the `query_string` query against multiple fields is to
expand each query term to an OR clause like this:

    field1:query_term OR field2:query_term | ...

For example, the following query

[source,js]
--------------------------------------------------
{
    "query_string" : {
        "fields" : ["content", "name"],
        "query" : "this AND that"
    }
}
--------------------------------------------------

matches the same words as


[source,js]
--------------------------------------------------
{
    "query_string": {
      "query": "(content:this OR content:thus) AND (name:this OR name:thus)"
    }
}
--------------------------------------------------

Since several queries are generated from the individual search terms,
combining them can be automatically done using either a `dis_max` query or a
simple `bool` query. For example (the `name` is boosted by 5 using `^5`
notation):

[source,js]
--------------------------------------------------
{
    "query_string" : {
        "fields" : ["content", "name^5"],
        "query" : "this AND that OR thus",
        "use_dis_max" : true
    }
}
--------------------------------------------------

Simple wildcard can also be used to search "within" specific inner
elements of the document. For example, if we have a `city` object with
several fields (or inner object with fields) in it, we can automatically
search on all "city" fields:

[source,js]
--------------------------------------------------
{
    "query_string" : {
        "fields" : ["city.*"],
        "query" : "this AND that OR thus",
        "use_dis_max" : true
    }
}
--------------------------------------------------

Another option is to provide the wildcard fields search in the query
string itself (properly escaping the `*` sign), for example:
`city.\*:something`.

When running the `query_string` query against multiple fields, the
following additional parameters are allowed:

[cols="<,<",options="header",]
|=======================================================================
|Parameter |Description
|`use_dis_max` |Should the queries be combined using `dis_max` (set it
to `true`), or a `bool` query (set it to `false`). Defaults to `true`.

|`tie_breaker` |When using `dis_max`, the disjunction max tie breaker.
Defaults to `0`.
|=======================================================================

The fields parameter can also include pattern based field names,
allowing to automatically expand to the relevant fields (dynamically
introduced fields included). For example:

[source,js]
--------------------------------------------------
{
    "query_string" : {
        "fields" : ["content", "name.*^5"],
        "query" : "this AND that OR thus",
        "use_dis_max" : true
    }
}
--------------------------------------------------

include::query-string-syntax.asciidoc[]