Intervals query

The intervals query matches documents based on the proximity and order of matching terms. It applies a set of matching rules to terms contained in the specified field. The query generates sequences of minimal intervals that span terms in the text. You can combine the intervals and filter them by parent sources.

Consider an index containing the following documents:

PUT testindex/_doc/1 
{
  "title": "key-value pairs are efficiently stored in a hash table"
}

PUT /testindex/_doc/2
{
  "title": "store key-value pairs in a hash map"
}

For example, the following query searches for documents containing the phrase key-value pairs (with no gap separating the terms) followed by either hash table or hash map:

GET /testindex/_search
{
  "query": {
    "intervals": {
      "title": {
        "all_of": {
          "ordered": true,
          "intervals": [
            {
              "match": {
                "query": "key-value pairs",
                "max_gaps": 0,
                "ordered": true
              }
            },
            {
              "any_of": {
                "intervals": [
                  {
                    "match": {
                      "query": "hash table"
                    }
                  },
                  {
                    "match": {
                      "query": "hash map"
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  }
}

The query returns both documents:

{
  "took": 1011,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": 0.25,
    "hits": [
      {
        "_index": "testindex",
        "_id": "2",
        "_score": 0.25,
        "_source": {
          "title": "store key-value pairs in a hash map"
        }
      },
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.14285713,
        "_source": {
          "title": "key-value pairs are efficiently stored in a hash table"
        }
      }
    ]
  }
}

Parameters

The query accepts the name of the field (<field>) as a top-level parameter:

GET _search
{
  "query": {
    "intervals": {
      "<field>": {
        ... 
      }
    }
  }
}

The <field> accepts the following rule objects that are used to match documents based on terms, order, and proximity.

The match rule

The match rule matches analyzed text. The following table lists all parameters the match rule supports.

The prefix rule

The prefix rule matches terms that start with a specified set of characters (prefix). The prefix can expand to match at most 128 terms. If the prefix matches more than 128 terms, an error is returned. The following table lists all parameters the prefix rule supports.

The wildcard rule

The wildcard rule matches terms using a wildcard pattern. The wildcard pattern can expand to match at most 128 terms. If the pattern matches more than 128 terms, an error is returned. The following table lists all parameters the wildcard rule supports.

Specifying patterns that start with * or ? can hinder search performance because it increases the number of iterations required to match terms.

The regexp rule

The regexp rule matches terms using a regular expression. The regular expression must match an entire term. By default, the regular expression can expand to match at most 128 terms in each index segment. If it matches more terms than the limit in a segment, an error is returned. To change the limit, specify the max_expansions parameter. The following table lists all parameters the regexp rule supports.

The regexp rule does not accept an analyzer parameter, so the pattern is not analyzed or normalized. The pattern is matched exactly as written against the terms stored in the index. For example, a field that uses the standard analyzer stores lowercase terms, so the pattern Stor(e|ed) returns no results unless case_insensitive is set to true.

Example: Match word variants

The following query uses the documents indexed at the beginning of this page. It searches for documents in which a term matching the regular expression stor(e|ed) (either store or stored) and the term hash have at most three positions between them:

GET /testindex/_search
{
  "query": {
    "intervals": {
      "title": {
        "all_of": {
          "max_gaps": 3,
          "intervals": [
            {
              "regexp": {
                "pattern": "stor(e|ed)"
              }
            },
            {
              "match": {
                "query": "hash"
              }
            }
          ]
        }
      }
    }
  }
}

The response contains only document 1. In document 1, the terms stored and hash have two terms between them (in and a). In document 2, the terms store and hash have five terms between them (key, value, pairs, in, and a), which exceeds the max_gaps value of 3:

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.25,
    "hits": [
      {
        "_index": "testindex",
        "_id": "1",
        "_score": 0.25,
        "_source": {
          "title": "key-value pairs are efficiently stored in a hash table"
        }
      }
    ]
  }
}

The fuzzy rule

The fuzzy rule matches terms that are similar to the provided term within a specified edit distance. The fuzzy pattern can expand to match at most 128 terms. If the pattern matches more than 128 terms, an error is returned. The following table lists all parameters the fuzzy rule supports.

The all_of rule

The all_of rule combines multiple rules using a conjunction (AND). The following table lists all parameters the all_of rule supports.

The any_of rule

The any_of rule combines multiple rules using a disjunction (OR). The following table lists all parameters the any_of rule supports.

The filter rule

The filter rule is used to restrict the results. The following table lists all parameters the filter rule supports.

Example: Filters

The following query searches for documents containing the words pairs and hash that are within five positions of each other and don’t contain the word efficiently between them:

POST /testindex/_search
{
  "query": {
    "intervals" : {
      "title" : {
        "match" : {
          "query" : "pairs hash",
          "max_gaps" : 5,
          "filter" : {
            "not_containing" : {
              "match" : {
                "query" : "efficiently"
              }
            }
          }
        }
      }
    }
  }
}

The response contains only document 2:

{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.25,
    "hits": [
      {
        "_index": "testindex",
        "_id": "2",
        "_score": 0.25,
        "_source": {
          "title": "store key-value pairs in a hash map"
        }
      }
    ]
  }
}

Example: Script filters

Alternatively, you can write your own script filter to include with the intervals query using the following variables:

• interval.start: The position (term number) where the interval starts.
• interval.end: The position (term number) where the interval ends.
• interval.gap: The number of words between the terms.

For example, the following query searches for the words map and hash that are next to each other within the specified interval. Terms are numbered starting with 0, so in the text store key-value pairs in a hash map, store is at position 0, keyis at position 1, and so on. The specified interval should start after a and end before the end of string:

POST /testindex/_search
{
  "query": {
    "intervals" : {
      "title" : {
        "match" : {
          "query" : "map hash",
          "filter" : {
            "script" : {
              "source" : "interval.start > 5 && interval.end < 8 && interval.gaps == 0"
            }
          }
        }
      }
    }
  }
}

The response contains document 2:

{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.5,
    "hits": [
      {
        "_index": "testindex",
        "_id": "2",
        "_score": 0.5,
        "_source": {
          "title": "store key-value pairs in a hash map"
        }
      }
    ]
  }
}

Interval minimization

To ensure that queries run in linear time, the intervals query minimizes the intervals. For example, consider a document containing the text a b c d c. You can use the following query to search for d that is contained by a and c:

POST /testindex/_search
{
  "query": {
    "intervals" : {
      "my_text" : {
        "match" : {
          "query" : "d",
          "filter" : {
            "contained_by" : {
              "match" : {
                "query" : "a c"
              }
            }
          }
        }
      }
    }
  }
}

The query returns no results because it matches the first two terms a c and finds no d between these terms.