Elasticsearch Elasticsearch Span_Near Query

By Opster Team

Updated: Aug 27, 2023

| 2 min read

Quick Links


The Elasticsearch span_near query is a crucial tool in the Elasticsearch query DSL (Domain Specific Language) that allows for more complex and precise text searching. It is a part of the span queries family, which are designed to handle more specialized cases, particularly when dealing with proximity or order of terms.

Understanding the span_near query

The span_near query is designed to match spans which are near one another. A span is a section of text in a document, and the span_near query allows you to find documents where specific spans are within a certain distance of each other. This is particularly useful when the order of terms matters, and you want to find documents where terms appear close together.

The span_near query is composed of a list of other span type queries and a parameter called “slop” which determines the maximum allowed distance between the spans. Another parameter, “in_order”, determines whether the spans should match in the order they are provided.

Here is a basic example of a span_near query:

  "span_near" : {
    "clauses" : [
      { "span_term" : { "field" : "value1" } },
      { "span_term" : { "field" : "value2" } },
      { "span_term" : { "field" : "value3" } }
    "slop" : 12,
    "in_order" : true

In this example, the query will match documents where the terms “value1”, “value2”, and “value3” appear within a distance of 12 terms from each other, and in the order specified.

Practical use cases of span_near query

One of the most common use cases for the span_near query is in full-text search applications where the proximity of terms can drastically affect the relevance of a document. For instance, in a legal document search application, finding documents where the terms “contract” and “breach” appear close together might be more relevant than documents where these terms are far apart.

Another use case is in natural language processing (NLP) applications. The span_near query can be used to find documents where certain phrases or combinations of words occur. This can be useful in sentiment analysis, where the proximity of certain words can change the sentiment of a sentence.

Optimizing the span_near query

While the span_near query is usefu, it can be resource-intensive, especially when dealing with large amounts of text. Here are a few tips to optimize your span_near queries:

1. Limit the slop: The larger the slop, the more processing power is required to find matching spans. If possible, try to keep the slop as small as possible.

2. Use filters: If you can limit the scope of your query using filters, do so. This can drastically reduce the number of documents that need to be processed.

3. Avoid overlapping spans: Overlapping spans can cause the same text to be processed multiple times. Try to structure your queries to avoid this.

4. Use the “in_order” parameter wisely: If the order of terms doesn’t matter, set “in_order” to false. This can improve performance as Elasticsearch won’t need to check the order of terms.