Range2Filter document (Data API 19.8)

Document representing a range compare with range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from_field" and "to_field") that specify the extent of a range, such as attributes "valid_from" and "valid_to".

The second range (R2) is defined by "from_value" and "to_value".

The filter mode specifies the method used to compare the two ranges:

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

Example: (valid dates overlap with the range January 1, 2007 through January 1, 2017)

 "query" : {
        "filtered_query": {
           "filter": {
                "range2_filter": {
                    "from_field": "valid_from",
                    "to_field": "valid_to",
                    "filter_mode":"overlap",
                    "from_value": "2007-01-01T00:00:00.000Z",
                    "to_value": "2017-01-01T00:00:00.000Z"
                }
           },
           "query": { "match_all_query": {} }
       }
   }
 
Property Type Constraints Description
filter_mode Enum {overlap, containing, contained}   Compare mode: overlap, containing, or contained. If not specified, the default is overlap.
from_field String mandatory=true, nullable=false The field name of the field that starts the first range.
from_inclusive Boolean   Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
from_value Object   The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
to_field String mandatory=true, nullable=false The field name of the field that ends the first range.
to_inclusive Boolean   Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
to_value Object   The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.