Query string query #

Returns documents that match a compact query-syntax string, e.g. status:active AND title:search. The same parser powers the URI search parameter ?q=.

Inside a nested query: not supported yet — the clause is rejected with an HTTP 400 naming the offending clause.

How it works #

The query string is parsed with the classic query-string grammar and converted to native queries: bare and field-qualified terms become analyzed match queries, quoted phrases become phrase queries, and the boolean operators become bool clauses. Terms without a field: prefix go to default_field (or, when fields is set, the query fans out into a bool.should across those fields with their field^boost weights). The operator subset:

Caveats verified against the engine: the per-clause boost field:term^3 binds to that clause and scales its score exactly (3× on term, match, fuzzy, prefix, range and wildcard/regexp expansions alike); the group boost (a b)^2 (also field:(a b)^2) multiplies every scored clause inside the group exactly; a quoted phrase carries no boost slot, so "a b"^N drops the multiplier instead of failing. Also: NOT as an infix keyword does not exclude correctly inside an AND (a AND NOT b) — write a AND -b. Bracketed groups parse, but combining a bracketed group with AND does not constrain correctly for keyword-field groups — flat combinations are the tested path. A query string that fails to parse matches nothing (a warning is logged, never a request failure).

URI search #

?q= on the search and count endpoints feeds the same parser: df becomes default_field, default_operator passes through, and lenient: true turns format errors (a text value against a numeric field) into zero hits instead of a 400. GET /logs/_search?q=level:error is the Kibana-style one-liner form of the example below.

Examples #

POST /my-collection/_search
{
  "query": {
    "query_string": {
      "query": "status:active AND title:search"
    }
  }
}

Across several fields with per-field boosts:

POST /my-collection/_search
{
  "query": {
    "query_string": {
      "query": "search engine",
      "fields": ["title^3", "description"]
    }
  }
}

Use cases #

• One-line triage. level:error AND message:search — the playground above — narrows 150 log lines to the 25 error lines that mention search, without assembling a bool.
• Ops URL panes. ?q=host:web-01 (50 of 150 log lines) drives dashboards and curl checks where a JSON body is friction.
• Exploration by prefix. message:s* widens to every term starting with s (50 lines), the same expansion prefix does — but inline in one string.
• Typo tolerance, inline. message:serch~2 still finds the 25 search lines; ~1 tightens, a bare ~ disables fuzziness.
• Keyword sweeps. level:[error TO warn] walks the dictionary between two terms — all 150 lines, since error < info < warn.

Parameters for query_string #

• query
  (Required, string) The query-syntax string.
• default_field
  (Optional, string, default: *) Field used for bare terms when fields is empty.
• default_operator
  (Optional, string, default: or) Default boolean operator between terms: or or and.
• fields
  (Optional, array of strings) Multiple fields with optional boost (e.g. ["title^3", "description"]). When non-empty, the query is expanded into a bool.should across these fields; each entry supports the field^boost syntax.
• type
  (Optional, string) Multi-field scoring strategy: best_fields (max/dis_max) or most_fields (sum — the default, for backward compatibility).
• tie_breaker
  (Optional, float, default: 0) Tie-breaker for best_fields mode: max_score + tie_breaker * sum(other_scores). Range [0, 1].
• combination_strategy
  (Optional, string) Multi-field score combination for fields: best_fields (max/dis_max) or most_fields (sum). Defaults to most_fields.

Related #

• match — what each bare term becomes: one analyzed field query; reach for it when there is no syntax to parse.
• multi_match — the structured alternative to the fields + type + tie_breaker fan-out.
• phrase — what a quoted "a b" becomes; it documents the slop semantics the ~N suffix reuses.
• fuzzy, wildcard, regexp — the standalone forms of the ~, * and /re/ syntax.