Wildcard query #

Returns documents that contain terms matching a wildcard pattern. The pattern supports * (any sequence of characters, including none) and ? (any single character).

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

How it works #

The pattern is expanded against the inverted index’s term dictionary: the engine walks the field’s terms, keeps those matching the pattern, and unions their postings lists — the same result as a should of term queries over the surviving terms. Matching is anchored at both ends: web-1 is the whole term, so web-* matches web-10 and web-1 itself, but *web-1* is required for anything with text on both sides.

• Cost follows the anchors. A pattern starting with a literal (web-*) can skip most of the dictionary; a pattern starting with * or ? (a leading wildcard) cannot, and degenerates to a full dictionary walk — the same cost class as suffix. Prefer prefix when the pattern is a pure head.
• Matching is per term. On a keyword field the term is the whole value; on a text field each analyzed token is tested separately. No analysis runs on the pattern itself — on standard-analyzed fields the stored tokens are lowercase.
• Scoring. The expansion is rewritten with ES’s constant_score rule: every matching document scores exactly the boost (1.0 by default), regardless of how many terms matched. Inside a bool.filter the scores are discarded, leaving a pure set filter.
• rewrite is accepted on the wire for body compatibility (constant_score default); the engine scores expansions as described above regardless of the setting.

Examples #

The pattern below puts the * mid-term — w*b-01 reads “w, anything, then b-01” and matches the host web-01 (50 documents). The SQL twin translates * to % and ? to _.

POST /my-collection/_search
{
  "query": {
    "wildcard": {
      "field": "user.id",
      "value": "ki*y"
    }
  }
}

Use cases #

• Mid-string holes. Values with a known head and tail but a variable middle (w*b-01 over logs.host → 50 of 150) — the shape neither prefix nor suffix can express.
• Single-character variation. ? covers ordinal or single-char variation without a full pattern language: web-0? for web-01 to web-03 (all 150 lines).
• Glob-style file paths. url.path patterns like /api/* (the 50 /api/v1/... lines) or *.js (25 lines) read naturally as globs.
• Partial IDs from user input. A search box feeding *<input>* over keyword identifiers — convenient, but remember leading wildcards are the expensive case; anchor when the input allows it.

Parameters for wildcard #

• field
  (Required, string) Field you wish to search.
• value
  (Required, string) Wildcard pattern to match terms in the provided field against. Note: leading wildcards (*foo) are expensive — prefer the prefix query when possible.
• case_insensitive
  (Optional, boolean, default: false) ASCII case-insensitive matching of the value with the indexed field values.
• boost
  (Optional, float, default: 1.0) Multiplier for the clause’s score — with the constant-score rewrite this is the score itself.
• rewrite
  (Optional, string) Method used to rewrite the expanded terms (constant_score, scoring_boolean, …).

Related #

• prefix — the cheap special case for head-anchored patterns.
• suffix — tail-anchored matching, same cost class as a leading wildcard.
• regexp — when */? are not expressive enough.
• term — the atom every expansion resolves to.