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

[[query-dsl-simple-query-string-query]]
=== Simple query string query
++++
<titleabbrev>Simple query string</titleabbrev>
++++

Returns documents based on a provided query string, using a parser with a
limited but fault-tolerant syntax.

This query uses a <<simple-query-string-syntax,simple syntax>> to parse and
split the provided query string into terms based on special operators. The query
then <<analysis,analyzes>> each term independently before returning matching
documents.

While its syntax is more limited than the
<<query-dsl-query-string-query,`query_string` query>>, 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 <<simple-query-string-syntax>>.

`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
<<simple-query-string-boost>> 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`
<<search-settings,search setting>>, 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) <<analysis,Analyzer>> used to convert text in the
query string into tokens. Defaults to the
<<specify-index-time-analyzer,index-time analyzer>> 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`, <<query-dsl-match-query-phrase,match phrase>>
queries are automatically created for multi-term synonyms. Defaults to `true`.
See <<simple-query-string-synonyms>> for an example.

`flags`::
(Optional, string) List of enabled operators for the
<<simple-query-string-syntax,simple query string syntax>>. Defaults to `ALL`
(all operators). See <<supported-flags>> 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 <<number,numeric>> 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 <<query-dsl-minimum-should-match, `minimum_should_match`
parameter>> 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 <<mixing-exact-search-with-stemming>>.
--


[[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 <<fuzziness>>.

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