New

The executive guide to generative AI

Read more

Simple Query String Query

edit

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:

GET /_search
{
  "query": {
    "simple_query_string" : {
        "query": "\"fried eggs\" +(eggplant | potato) -frittata",
        "fields": ["title^5", "body"],
        "default_operator": "and"
    }
  }
}

The simple_query_string top level parameters include:

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: In future versions (starting in 7.0), there will be a limit on the number of fields that can be queried at once. This limit will be determined by the indices.query.bool.max_clause_count setting which defaults to 1024. Currently this will be raised and logged as a Warning only.

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 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 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 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

[6.0.0] Deprecated in 6.0.0. set default_field to * instead Perform the query on all fields detected in the mapping that can be queried. Will be used by default when the _all field is disabled and no default_field is specified (either in the index settings or in the request body) and no fields are specified.

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 (abba). Default is true.

Simple Query String Syntax

edit

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:

GET /_search
{
    "query": {
        "simple_query_string" : {
            "fields" : ["content"],
            "query" : "foo bar -baz"
        }
    }
}

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".

Default Field

edit

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.

Multi Field

edit

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

GET /_search
{
    "query": {
        "simple_query_string" : {
            "fields" : ["content", "name.*^5"],
            "query" : "foo bar baz"
        }
    }
}

Flags

edit

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:

GET /_search
{
    "query": {
        "simple_query_string" : {
            "query" : "foo | bar + baz*",
            "flags" : "OR|AND|PREFIX"
        }
    }
}

The available flags are:

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.

Synonyms

edit

The simple_query_string query supports multi-terms synonym expansion with the 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:

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.

Was this helpful?
Feedback