Span queries #

Span queries are low-level positional queries that expose and control the positions of terms — the building blocks for phrase-adjacent logic that match_phrase does not express directly. Most use cases are better served by match_phrase (or its slop); the span family exists for the remaining ones.

Inside a nested query: not supported yet — span clauses are rejected with an HTTP 400 naming the offending clause. Use match_phrase with slop for positional logic.

span_term #

Matches documents containing an exact term at any position — the positional unit the other span queries compose.

POST /my-collection/_search
{
  "query": {
    "span_term": {
      "field": "message",
      "value": "search"
    }
  }
}

Parameters: field (required, string), value (required, string), boost (optional, default 1.0).

span_near #

Matches documents where the given span clauses occur within slop positions of each other, optionally in order — the span form of a proximity match — get within three positions of search, in order (25 log lines in the dataset):

POST /my-collection/_search
{
  "query": {
    "span_near": {
      "clauses": [
        { "span_term": { "field": "message", "value": "get" } },
        { "span_term": { "field": "message", "value": "search" } }
      ],
      "slop": 3,
      "in_order": true
    }
  }
}

• clauses — (Required, array of span queries) The spans to relate.
• slop — (Optional, integer, default: 0) Maximum positions between the clauses.
• in_order — (Optional, boolean, default: false) Whether the clauses must appear in the given order.

span_or #

Matches documents matching any of the given span clauses — the union of spans.

{
  "span_or": {
    "clauses": [
      { "span_term": { "field": "message", "value": "get" } },
      { "span_term": { "field": "message", "value": "post" } }
    ]
  }
}

• clauses — (Required, array of span queries).

span_multi #

Wraps a multi-term query (such as prefix, wildcard, fuzzy, regexp, term) so it can be used as a span clause inside span_near / span_or.

{
  "span_multi": {
    "matcher": {
      "prefix": { "field": "user", "value": "ki" }
    }
  }
}

• matcher — (Required, query) The multi-term query to wrap.