228 lines
7.9 KiB
Plaintext
228 lines
7.9 KiB
Plaintext
[[query-dsl-simple-query-string-query]]
|
|
=== Simple Query String Query
|
|
|
|
A query that uses the SimpleQueryParser to parse its context. Unlike the
|
|
regular `query_string` query, the `simple_query_string` query will never
|
|
throw an exception, and discards invalid parts of the query. Here is
|
|
an example:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"simple_query_string" : {
|
|
"query": "\"fried eggs\" +(eggplant | potato) -frittata",
|
|
"fields": ["title^5", "body"],
|
|
"default_operator": "and"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The `simple_query_string` top level parameters include:
|
|
|
|
[cols="<,<",options="header",]
|
|
|=======================================================================
|
|
|Parameter |Description
|
|
|`query` |The actual query to be parsed. See below for syntax.
|
|
|
|
|`fields` |The fields to perform the parsed query against. Defaults to the
|
|
`index.query.default_field` index settings, which in turn defaults to `*`. `*`
|
|
extracts all fields in the mapping that are eligible to term queries and filters
|
|
the metadata fields.
|
|
|
|
WARNING: There is a limit on the number of fields that can be queried
|
|
at once. It is defined by the `indices.query.bool.max_clause_count` <<search-settings>>
|
|
which defaults to 1024.
|
|
|
|
|`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` |Force the analyzer to use to analyze each term of the query when
|
|
creating composite queries.
|
|
|
|
|`flags` |A set of <<supported-flags,flags>> specifying which features of the
|
|
`simple_query_string` to enable. Defaults to `ALL`.
|
|
|
|
|`analyze_wildcard` | Whether terms of prefix queries should be automatically
|
|
analyzed or not. If `true` a best effort will be made to analyze the prefix. However,
|
|
some analyzers will be not able to provide a meaningful results
|
|
based just on the prefix of a term. Defaults to `false`.
|
|
|
|
|`lenient` | If set to `true` will cause format based failures
|
|
(like providing text to a numeric field) to be ignored.
|
|
|
|
|`minimum_should_match` | The minimum number of clauses that must match for a
|
|
document to be returned. See the
|
|
<<query-dsl-minimum-should-match,`minimum_should_match`>> documentation for the
|
|
full list of options.
|
|
|
|
|`quote_field_suffix` | A suffix to append to fields for quoted parts of
|
|
the query string. This allows to use a field that has a different analysis chain
|
|
for exact matching. Look <<mixing-exact-search-with-stemming,here>> for a
|
|
comprehensive example.
|
|
|
|
|`auto_generate_synonyms_phrase_query` |Whether phrase queries should be automatically generated for multi terms synonyms.
|
|
Defaults to `true`.
|
|
|
|
|`all_fields` | deprecated[6.0.0, set `fields` to `*` instead]
|
|
Perform the query on all fields detected in the mapping that can
|
|
be queried.
|
|
|
|
|`fuzzy_prefix_length` |Set the prefix length for fuzzy queries. Default
|
|
is `0`.
|
|
|
|
|`fuzzy_max_expansions` |Controls the number of terms fuzzy queries will
|
|
expand to. Defaults to `50`
|
|
|
|
|`fuzzy_transpositions` |Set to `false` to disable fuzzy transpositions (`ab` -> `ba`).
|
|
Default is `true`.
|
|
|=======================================================================
|
|
|
|
[float]
|
|
===== Simple Query String Syntax
|
|
The `simple_query_string` supports the following special characters:
|
|
|
|
* `+` signifies AND operation
|
|
* `|` signifies OR operation
|
|
* `-` negates a single token
|
|
* `"` wraps a number of tokens to signify a phrase for searching
|
|
* `*` at the end of a term signifies a prefix query
|
|
* `(` and `)` signify precedence
|
|
* `~N` after a word signifies edit distance (fuzziness)
|
|
* `~N` after a phrase signifies slop amount
|
|
|
|
In order to search for any of these special characters, they will need to
|
|
be escaped with `\`.
|
|
|
|
Be aware that this syntax may have a different behavior depending on the
|
|
`default_operator` value. For example, consider the following query:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"simple_query_string" : {
|
|
"fields" : ["content"],
|
|
"query" : "foo bar -baz"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
You may expect that documents containing only "foo" or "bar" will be returned,
|
|
as long as they do not contain "baz", however, due to the `default_operator`
|
|
being OR, this really means "match documents that contain "foo" or documents
|
|
that contain "bar", or documents that don't contain "baz". If this is unintended
|
|
then the query can be switched to `"foo bar +-baz"` which will not return
|
|
documents that contain "baz".
|
|
|
|
[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 fields to search on. It defaults to `*` and the query will automatically
|
|
attempt to determine the existing fields in the index's mapping that are queryable,
|
|
and perform the search on those fields.
|
|
|
|
[float]
|
|
==== Multi Field
|
|
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]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"simple_query_string" : {
|
|
"fields" : ["content", "name.*^5"],
|
|
"query" : "foo bar baz"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
[float]
|
|
[[supported-flags]]
|
|
==== Flags
|
|
`simple_query_string` support multiple flags to specify which parsing features
|
|
should be enabled. It is specified as a `|`-delimited string with the
|
|
`flags` parameter:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
GET /_search
|
|
{
|
|
"query": {
|
|
"simple_query_string" : {
|
|
"query" : "foo | bar + baz*",
|
|
"flags" : "OR|AND|PREFIX"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
The available flags are:
|
|
|
|
[cols="<,<",options="header",]
|
|
|=======================================================================
|
|
|Flag |Description
|
|
|`ALL` |Enables all parsing features. This is the default.
|
|
|`NONE` |Switches off all parsing features.
|
|
|`AND` |Enables the `+` AND operator.
|
|
|`OR` |Enables the `\|` OR operator.
|
|
|`NOT` |Enables the `-` NOT operator.
|
|
|`PREFIX` |Enables the `*` Prefix operator.
|
|
|`PHRASE` |Enables the `"` quotes operator used to search for phrases.
|
|
|`PRECEDENCE` |Enables the `(` and `)` operators to control operator precedence.
|
|
|`ESCAPE` |Enables `\` as the escape character.
|
|
|`WHITESPACE` |Enables whitespaces as split characters.
|
|
|`FUZZY` |Enables the `~N` operator after a word where N is an integer denoting the allowed edit distance for matching (see <<fuzziness>>).
|
|
|`SLOP` |Enables the `~N` operator after a phrase where N is an integer denoting the slop amount.
|
|
|`NEAR` |Synonymous to `SLOP`.
|
|
|=======================================================================
|
|
|
|
[float]
|
|
==== Synonyms
|
|
|
|
The `simple_query_string` 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": {
|
|
"simple_query_string" : {
|
|
"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`.
|
|
|