Query string query

A query_string query parses the query string based on the query string syntax. It provides for creating powerful yet concise queries that can incorporate wildcards and search multiple fields.

Searches with query_string queries do not return nested documents. To search nested fields, use the nested query.

Query string query has a strict syntax and returns an error in case of invalid syntax. Therefore, it does not work well for search box applications. For a less strict alternative, consider using simple_query_string query. If you don’t need query syntax support, use the match query.

Query string syntax

Query string syntax is based on Apache Lucene query syntax.

You can use query string syntax in the following cases:

1. In a query_string query, for example:

    GET _search
    {
      "query": {
        "query_string": {
          "query": "the wind AND (rises OR rising)"
        }
      }
    }

   copy

2. In the OpenSearch Dashboards Discover or Dashboard apps, if you turn off DQL, as shown in the following image.

DQL and Query string query (Lucene) language are the two search bar language options in Discover and Dashboards. To compare these language options, see Discover and Dashboard search bar.

1. If you search using the HTTP request query parameters, for example:

    GET _search?q=wind

A query string consists of terms and operators. A term is a single word (for example, in the query wind rises, the terms are wind and rises). If several terms are surrounded by quotation marks, they are treated as one phrase where words are matched in the order they appear (for example, "wind rises"). Operators (such as OR, AND, and NOT) specify the Boolean logic used to interpret text in the query string.

The examples in this section use an index containing the following mapping and documents:

PUT /testindex
{
  "mappings": {
    "properties": {
      "title": { 
        "type": "text",
        "fields": {
          "english": { 
            "type": "text",
            "analyzer": "english"
          }
        }
      }
    }
  }
}

copy

PUT /testindex/_doc/1
{
  "title": "The wind rises"
}

copy

PUT /testindex/_doc/2
{
  "title": "Gone with the wind",
  "description": "A 1939 American epic historical film"
}

copy

PUT /testindex/_doc/3
{
  "title": "Windy city"
}

copy

PUT /testindex/_doc/4
{
  "article title": "Wind turbines"
}

copy

Reserved characters

The following is a list of reserved characters for the query string query:

+, -, =, &&, ||, >, <, !, (, ),{, }, [, ], ^, ", ~, *, ?, :, \, /

Escape reserved characters with a backslash (\). When sending a JSON request, use a double backslash (\\) to escape reserved characters (because the backslash character is itself reserved, you must escape the backslash with another backslash).

For example, to search for an expression 2*3, specify the query string: 2\\*3:

GET /testindex/_search
{
 "query": {
    "query_string": {
      "query": "title: 2\\*3"
    }
  }
}

copy

The > and < signs cannot be escaped. They are interpreted as a range query.

White space characters and empty queries

White space characters are not considered operators. If a query string is empty or only contains white space characters, the query does not return results.

Field names

Specify the field name before the colon. The following table contains example queries with field names.

Wildcard expressions

You can specify wildcard expressions using special characters: ? replaces a single character and * replaces zero or more characters.

Example

The following query searches for the title containing the word gone and a description that contains a word starting with hist:

GET /testindex/_search
{
 "query": {
    "query_string": {
      "query": "title: gone AND description: hist*"
    }
  }
}

copy

Wildcard queries can use a significant amount of memory, which can degrade performance. Wildcards at the beginning of a word (for example, *cal) are the most expensive because matching documents on such wildcards requires examining all terms in the index. To disable leading wildcards, set allow_leading_wildcard to false.

For efficiency, pure wildcards such as * are rewritten as exists queries. Therefore, the description: * wildcard will match documents containing an empty value in the description field but will not match documents in which the description field is either missing or has a null value.

If you set analyze_wildcard to true, OpenSearch will analyze queries that end with a * (such as hist*). Consequently, OpenSearch will build a Boolean query comprising the resulting tokens by taking exact matches on the first n-1 tokens and a prefix match on the last token.

Regular expressions

To specify regular expression patterns in a query string, surround them with forward slashes (/), for example title: /w[a-z]nd/.

The allow_leading_wildcard parameter does not apply to regular expressions. For example, a query string such as /.*d/ will examine all terms in the index.

Fuzziness

You can run fuzzy queries using the ~ operator, for example title: rise~.

The query searches for documents containing terms that are similar to the search term within the maximum allowed edit distance. The edit distance is defined as the Damerau-Levenshtein distance, which measures the number of one-character changes (insertions, deletions, substitutions, or transpositions) needed to change one term to another term.

The default edit distance of 2 should catch 80% of misspellings. To change the default edit distance, specify the new edit distance after the ~ operator. For example, to set the edit distance to 1, use the query title: rise~1.

Do not mix fuzzy and wildcard operators. If you specify both fuzzy and wildcard operators, one of the operators will not be applied. For example, if you can search for wnid*~1, the wildcard operator * will be applied but the fuzzy operator ~1 will not be applied.

Proximity queries

A proximity query does not require the search phrase to be in the specified order. It allows the words in the phrase to be in a different order or separated by other words. A proximity query specifies a maximum edit distance of words in a phrase. For example, the following query allows an edit distance of 4 when matching the words in the specified phrase:

GET /testindex/_search
{
 "query": {
    "query_string": {
      "query": "title: \"wind gone\"~4"
    }
  }
}

copy

When OpenSearch matches documents, the closer the words in the document to the word order specified in the query (the less the edit distance), the higher the document’s relevance score.

Ranges

To specify a range for a numeric, string, or date field, use square brackets ([min TO max]) for an inclusive range and curly braces ({min TO max}) for an exclusive range. You can also mix square brackets and curly braces to include or exclude the lower and upper bound (for example, {min TO max]).

The dates for a date range must be provided in the format that you used when mapping the field containing the date. For more information about supported date formats, see Formats.

The following table provides range syntax examples.

As an alternative to specifying a range in a query string, you can use a range query, which provides a more reliable syntax.

Boosting

Use the caret (^) boost operator to boost the relevance score of documents by a multiplier. Values in the [0, 1) range decrease relevance, and values greater than 1 increase relevance. Default is 1.

The following table provides boost examples.

Boolean operators

When you provide search terms in the query, by default, the query returns documents containing at least one of the provided terms. You can use the default_operator parameter to specify an operator for all terms. Thus, if you set the default_operator to AND, all terms will be required, whereas if you set it to OR, all terms will be optional.

+ and - operators

If you want more granular control over the required and optional terms, you can use the + and - operators. The + operator makes the term following it required, while the - operator excludes the term following it.

For example, in the query string title: (gone +wind -turbines) specifies that the term gone is optional, the term wind must be present and the term turbines must not be present in the title of the matching documents:

GET /testindex/_search
{
 "query": {
    "query_string": {
      "query": "title: (gone +wind -turbines)"
    }
  }
}

copy

The query returns two matching documents:

{
  "_index": "testindex",
  "_id": "2",
  "_score": 1.3159468,
  "_source": {
    "title": "Gone with the wind",
    "description": "A 1939 American epic historical film"
  }
},
{
  "_index": "testindex",
  "_id": "1",
  "_score": 0.3438858,
  "_source": {
    "title": "The wind rises"
  }
}

The preceding query is equivalent to the following Boolean query:

GET testindex/_search
{
  "query": {
    "bool": {
      "must": {
        "match": {
          "title": "wind"
        }
      },
      "should": {
        "match": {
          "title": "gone"
        }
      },
      "must_not": {
        "match": {
          "title": "turbines"
        }
      }
    }
  }
}

Conventional Boolean operators

Alternatively, you can use the following Boolean operators: AND, &&, OR, ||, NOT, !. However, these operators do not follow the precedence rules, so you must use parentheses to specify precedence when using multiple Boolean operators. For example, the query string title: (gone +wind -turbines) can be rewritten as follows using Boolean operators:

title: ((gone AND wind) OR wind) AND NOT turbines

Run the following query that contains the rewritten query string:

GET testindex/_search
{
 "query": {
    "query_string": {
      "query": "title: ((gone AND wind) OR wind) AND NOT turbines"
    }
  }
}

copy

The query returns the same results as the query that uses the + and - operators. However, note that the relevance scores of the matching documents are not the same as in the previous results:

{
  "_index": "testindex",
  "_id": "2",
  "_score": 1.6166971,
  "_source": {
    "title": "Gone with the wind",
    "description": "A 1939 American epic historical film"
  }
},
{
  "_index": "testindex",
  "_id": "1",
  "_score": 0.3438858,
  "_source": {
    "title": "The wind rises"
  }
}

copy

Grouping

Group multiple clauses or terms into subqueries using parentheses. For example, the following query searches for documents containing the words gone or rises that must contain the word wind in the title:

GET testindex/_search
{
 "query": {
    "query_string": {
      "query": "title: (gone OR rises) AND wind"
    }
  }
}

The results contain the two matching documents:

{
  "_index": "testindex",
  "_id": "1",
  "_score": 1.5046883,
  "_source": {
    "title": "The wind rises"
  }
},
{
  "_index": "testindex",
  "_id": "2",
  "_score": 1.3159468,
  "_source": {
    "title": "Gone with the wind",
    "description": "A 1939 American epic historical film"
  }
}

You can also use grouping to boost subquery results or to target the specified field, for example title:(gone AND wind) description:(historical film)^2.

Searching multiple fields

To search multiple fields, use the fields parameter. When you provide the fields parameter, the query is rewritten as field_1: query OR field_2: query ....

For example, the following query searches for the terms wind or film in the title and description fields:

GET testindex/_search
{
  "query": {
    "query_string": {
      "fields": [ "title", "description" ],
      "query": "wind AND film"
    }
  }
}

copy

The preceding query is equivalent to the following query that does not provide the fields parameter:

GET testindex/_search
{
  "query": {
    "query_string": {
      "query": "(title:wind OR description:wind) AND (title:film OR description:film)"
    }
  }
}

Searching multiple subfields of a field

To search all inner fields of a field, you can use a wildcard. For example, to search all subfields within the address field, use the following query:

GET /testindex/_search
{
  "query": {
    "query_string" : {
      "fields" : ["address.*"],
      "query" : "New AND (York OR Jersey)"
    }
  }
}

copy

The preceding query is equivalent to the following query that does not provide the fields parameter (note that the * is escaped with \\):

GET /testindex/_search
{
  "query": {
    "query_string" : {
      "query" : "address.\\*: New AND (York OR Jersey)"
    }
  }
}

Boosting

The subqueries that are generated from each search term are combined using a dis_max query with a tie_breaker. To boost individual fields, use the ^ operator. For example, the following query boosts the title field by a factor of 2:

GET testindex/_search
{
  "query": {
    "query_string": {
      "fields": [ "title^2", "description" ],
      "query": "wind AND film"
    }
  }
}

copy

To boost all subfields of a field, specify the boost operator after the wildcard:

GET /testindex/_search
{
  "query": {
    "query_string" : {
      "fields" : ["work_address", "address.*^2"],
      "query" : "New AND (York OR Jersey)"
    }
  }
}

Parameters for multiple field searches

When searching multiple fields, you can pass the additional optional type parameter to the query_string query.

Synonyms in the query_string query

The query_string query supports multi-term synonym expansion with the synonym_graph token filter. If you use the synonym_graph token filter, OpenSearch creates a match phrase query for each synonym.

The auto_generate_synonyms_phrase_query parameter specifies whether to create a match phrase query automatically for multi-term synonyms. By default, auto_generate_synonyms_phrase_query is true, so if you specify ml, machine learning as synonyms and search for ml, OpenSearch searches for ml OR "machine learning".

Alternatively, you can match multi-term synonyms using conjunctions. If you set auto_generate_synonyms_phrase_query to false, OpenSearch searches for ml OR (machine AND learning).

For example, the following query searches for the text ml models and specifies not to auto-generate a match phrase query for each synonym:

GET /testindex/_search
{
  "query": {
    "query_string": {
      "default_field": "title",
      "query": "ml models",
      "auto_generate_synonyms_phrase_query": false
    }
  }
}

copy

For this query, OpenSearch creates the following Boolean query: (ml OR (machine AND learning)) models.

Minimum should match

The query_string query splits the query around each operator and creates a Boolean query for the entire input. The minimum_should_match parameter specifies the minimum number of terms a document must match to be returned in search results. For example, the following query specifies that the description field must match at least two terms for each search result:

GET /testindex/_search
{
  "query": {
    "query_string": {
      "fields": [
        "description"
      ],
      "query": "historical epic film",
      "minimum_should_match": 2
    }
  }
}

copy

For this query, OpenSearch creates the following Boolean query: (description:historical description:epic description:film)~2.

Minimum should match with multiple fields

If you specify multiple fields in a query_string query, OpenSearch creates a dis_max query for the specified fields. If you don’t explicitly specify an operator for the query terms, the whole query text is treated as one clause. OpenSearch builds a query for each field using this single clause. The final Boolean query contains a single clause that corresponds to the dis_max query for all fields, therefore the minimum_should_match parameter is not applied.

For example, in the following query, historical epic heroic is treated as a single clause:

GET /testindex/_search
{
  "query": {
    "query_string": {
      "fields": [
        "title",
        "description"
      ],
      "query": "historical epic heroic",
      "minimum_should_match": 2
    }
  }
}

copy

For this query, OpenSearch creates the following Boolean query: ((title:historical title:epic title:heroic) | (description:historical description:epic description:heroic)).

If you add explicit operators (AND or OR) to the query terms, each term is considered a separate clause, to which the minimum_should_match parameter can be applied. For example, in the following query, historical, epic, and heroic are considered separate clauses:

GET /testindex/_search
{
  "query": {
    "query_string": {
      "fields": [
        "title",
        "description"
      ],
      "query": "historical OR epic OR heroic",
      "minimum_should_match": 2
    }
  }
}

copy

For this query, OpenSearch creates the following Boolean query: ((title:historical | description:historical) (description:epic | title:epic) (description:heroic | title:heroic))~2. The query matches at least two of the three clauses. Each clause represents a dis_max query on both the title and description fields for each term.

Alternatively, to ensure that minimum_should_match can be applied, you can set the type parameter to cross_fields. This indicates that the fields with the same analyzer should be grouped together when the input text is analyzed:

GET /testindex/_search
{
  "query": {
    "query_string": {
      "fields": [
        "title",
        "description"
      ],
      "query": "historical epic heroic",
      "type": "cross_fields",
      "minimum_should_match": 2
    }
  }
}

copy

For this query, OpenSearch creates the following Boolean query: ((title:historical | description:historical) (description:epic | title:epic) (description:heroic | title:heroic))~2.

However, if you use different analyzers, you must use explicit operators in the query to ensure that the minimum_should_match parameter is applied to each term.

Parameters

The following table lists the parameters that query_string query supports. All parameters except query are optional.

Query string queries may be internally converted into prefix queries. If search.allow_expensive_queries is set to false, prefix queries are not executed. If index_prefixes is enabled, the search.allow_expensive_queries setting is ignored and an optimized query is built and executed.