197 lines
6.3 KiB
Plaintext
197 lines
6.3 KiB
Plaintext
[[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` | Locale that should be used for string conversions.
|
|
Defaults to `ROOT`.
|
|
|
|
|`time_zone` | Time Zone to be applied to any range query related to dates. See also
|
|
http://joda-time.sourceforge.net/api-release/org/joda/time/DateTimeZone.html[JODA timezone].
|
|
|=======================================================================
|
|
|
|
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:that) AND (name:this OR name:that)"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
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[]
|