[[query-dsl-simple-query-string-query]] === Simple query string query ++++ Simple query string ++++ Returns documents based on a provided query string, using a parser with a limited but fault-tolerant syntax. This query uses a <> to parse and split the provided query string into terms based on special operators. The query then <> each term independently before returning matching documents. While its syntax is more limited than the <>, the `simple_query_string` query does not return errors for invalid syntax. Instead, it ignores any invalid parts of the query string. [[simple-query-string-query-ex-request]] ==== Example request [source,console] -------------------------------------------------- GET /_search { "query": { "simple_query_string" : { "query": "\"fried eggs\" +(eggplant | potato) -frittata", "fields": ["title^5", "body"], "default_operator": "and" } } } -------------------------------------------------- [[simple-query-string-top-level-params]] ==== Top-level parameters for `simple_query_string` `query`:: (Required, string) Query string you wish to parse and use for search. See <>. `fields`:: + -- (Optional, array of strings) Array of fields you wish to search. This field accepts wildcard expressions. You also can boost relevance scores for matches to particular fields using a caret (`^`) notation. See <> for examples. Defaults to the `index.query.default_field` index setting, which has a default value of `*`. The `*` value extracts all fields that are eligible to term queries and filters the metadata fields. All extracted fields are then combined to build a query if no `prefix` is specified. 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` <>, which defaults to `1024`. -- `default_operator`:: + -- (Optional, string) Default boolean logic used to interpret text in the query string if no operators are specified. Valid values are: `OR` (Default):: For example, a query string of `capital of Hungary` is interpreted as `capital OR of OR Hungary`. `AND`:: For example, a query string of `capital of Hungary` is interpreted as `capital AND of AND Hungary`. -- `all_fields`:: deprecated:[6.0.0, set `fields` to `*` instead](Optional, boolean) If `true`, search all searchable fields in the index's field mapping. `analyze_wildcard`:: (Optional, boolean) If `true`, the query attempts to analyze wildcard terms in the query string. Defaults to `false`. `analyzer`:: (Optional, string) <> used to convert text in the query string into tokens. Defaults to the <> mapped for the `default_field`. If no analyzer is mapped, the index's default analyzer is used. `auto_generate_synonyms_phrase_query`:: (Optional, boolean) If `true`, <> queries are automatically created for multi-term synonyms. Defaults to `true`. See <> for an example. `flags`:: (Optional, string) List of enabled operators for the <>. Defaults to `ALL` (all operators). See <> for valid values. `fuzzy_max_expansions`:: (Optional, integer) Maximum number of terms to which the query expands for fuzzy matching. Defaults to `50`. `fuzzy_prefix_length`:: (Optional, integer) Number of beginning characters left unchanged for fuzzy matching. Defaults to `0`. `fuzzy_transpositions`:: (Optional, boolean) If `true`, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to `true`. `lenient`:: (Optional, boolean) If `true`, format-based errors, such as providing a text value for a <> field, are ignored. Defaults to `false`. `minimum_should_match`:: (Optional, string) Minimum number of clauses that must match for a document to be returned. See the <> for valid values and more information. `quote_field_suffix`:: + -- (Optional, string) Suffix appended to quoted text in the query string. You can use this suffix to use a different analysis method for exact matches. See <>. -- [[simple-query-string-query-notes]] ==== Notes [[simple-query-string-syntax]] ===== Simple query string syntax The `simple_query_string` query supports the following operators: * `+` 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 To use one of these characters literally, escape it with a preceding backslash (`\`). The behavior of these operators may differ depending on the `default_operator` value. For example: [source,console] -------------------------------------------------- GET /_search { "query": { "simple_query_string": { "fields": [ "content" ], "query": "foo bar -baz" } } } -------------------------------------------------- This search is intended to only return documents containing `foo` or `bar` that also do **not** contain `baz`. However because of a `default_operator` of `OR`, this search actually returns documents that contain `foo` or `bar` and any documents that don't contain `baz`. To return documents as intended, change the query string to `foo bar +-baz`. [[supported-flags]] ===== Limit operators You can use the `flags` parameter to limit the supported operators for the simple query string syntax. To explicitly enable only specific operators, use a `|` separator. For example, a `flags` value of `OR|AND|PREFIX` disables all operators except `OR`, `AND`, and `PREFIX`. [source,console] -------------------------------------------------- GET /_search { "query": { "simple_query_string": { "query": "foo | bar + baz*", "flags": "OR|AND|PREFIX" } } } -------------------------------------------------- [[supported-flags-values]] ====== Valid values The available flags are: `ALL` (Default):: Enables all optional operators. `AND`:: Enables the `+` AND operator. `ESCAPE`:: Enables `\` as an escape character. `FUZZY`:: Enables the `~N` operator after a word, where `N` is an integer denoting the allowed edit distance for matching. See <>. `NEAR`:: Enables the `~N` operator, after a phrase where `N` is the maximum number of positions allowed between matching tokens. Synonymous to `SLOP`. `NONE`:: Disables all operators. `NOT`:: Enables the `-` NOT operator. `OR`:: Enables the `\|` OR operator. `PHRASE`:: Enables the `"` quotes operator used to search for phrases. `PRECEDENCE`:: Enables the `(` and `)` operators to control operator precedence. `PREFIX`:: Enables the `*` prefix operator. `SLOP`:: Enables the `~N` operator, after a phrase where `N` is maximum number of positions allowed between matching tokens. Synonymous to `NEAR`. `WHITESPACE`:: Enables whitespace as split characters. [[simple-query-string-boost]] ===== Wildcards and per-field boosts in the `fields` parameter Fields can be specified with wildcards, eg: [source,console] -------------------------------------------------- GET /_search { "query": { "simple_query_string" : { "query": "Will Smith", "fields": [ "title", "*_name" ] <1> } } } -------------------------------------------------- <1> Query the `title`, `first_name` and `last_name` fields. Individual fields can be boosted with the caret (`^`) notation: [source,console] -------------------------------------------------- GET /_search { "query": { "simple_query_string" : { "query" : "this is a test", "fields" : [ "subject^3", "message" ] <1> } } } -------------------------------------------------- <1> The `subject` field is three times as important as the `message` field. [[simple-query-string-synonyms]] ===== Synonyms The `simple_query_string` query supports multi-terms synonym expansion with the <> 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,console] -------------------------------------------------- GET /_search { "query": { "simple_query_string" : { "query" : "ny city", "auto_generate_synonyms_phrase_query" : false } } } -------------------------------------------------- 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`.