You're viewing version 3.0 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Span multi-term query

The span_multi query allows you to wrap a multi-term query (like wildcard, fuzzy, prefix, range, or regexp) as a span query. This enables you to use these more flexible matching queries within other span queries.

For example, you can use the span_multi query to:

• Find words with common prefixes near other terms.
• Match fuzzy variations of words within spans.
• Use regular expressions in span queries.

span_multi queries can potentially match many terms. To avoid excessive memory usage, you can:

• Set the rewrite parameter for the multi-term query.
• Use the top_terms_* rewrite method.
• Consider enabling the index_prefixes option for the text field if you use span_multi only for a prefix query. This automatically rewrites any prefix query on the field into a single-term query that matches the indexed prefix.

Example

To try the examples in this section, complete the setup steps.

The span_multi query uses the following syntax to wrap the prefix query:

"span_multi": {
  "match": {
    "prefix": {
      "description": {
        "value": "flutter"
      }
    }
  }
}

The following query searches for words starting with “dress” near any form of “sleeve” within at most 5 words of each other:

GET /clothing/_search
{
  "query": {
    "span_near": {
      "clauses": [
        {
          "span_multi": {
            "match": {
              "prefix": {
                "description": {
                  "value": "dress"
                }
              }
            }
          }
        },
        {
          "field_masking_span": {
            "query": {
              "span_term": {
                "description.stemmed": "sleev"
              }
            },
            "field": "description"
          }
        }
      ],
      "slop": 5,
      "in_order": false
    }
  }
}

The query matches documents 1 (“Long-sleeved dress…”) and 4 (“…dresses with long fluttered sleeves…”) because “dress” and “long” occur within the maximum distance in both documents.

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 1.7590723,
    "hits": [
      {
        "_index": "clothing",
        "_id": "1",
        "_score": 1.7590723,
        "_source": {
          "description": "Long-sleeved dress shirt with a formal collar and button cuffs. "
        }
      },
      {
        "_index": "clothing",
        "_id": "4",
        "_score": 0.84792376,
        "_source": {
          "description": "A set of two midi silk shirt dresses with long fluttered sleeves in black. "
        }
      }
    ]
  }
}

Parameters

The following table lists all top-level parameters supported by span_multi queries. All parameters are required.