Docs
-->
Elasticsearch Reference [7.0] » Query DSL » Term level queries » Range Query
«  Terms Set Query     Exists Query  »

Range Query

Matches documents with fields that have terms within a certain range. The type of the Lucene query depends on the field type, for string fields, the TermRangeQuery, while for number/date fields, the query is a NumericRangeQuery. The following example returns all documents where age is between 10 and 20:

GET _search
{
    "query": {
        "range" : {
            "age" : {
                "gte" : 10,
                "lte" : 20,
                "boost" : 2.0
            }
        }
    }
}

The range query accepts the following parameters:

gte

Greater-than or equal to

gt

Greater-than

lte

Less-than or equal to

lt

Less-than

boost

Sets the boost value of the query, defaults to 1.0

Ranges on date fields

When running range queries on fields of type date, ranges can be specified using Date Math:

GET _search
{
    "query": {
        "range" : {
            "date" : {
                "gte" : "now-1d/d",
                "lt" :  "now/d"
            }
        }
    }
}

Date math and rounding

When using date math to round dates to the nearest day, month, hour, etc, the rounded dates depend on whether the ends of the ranges are inclusive or exclusive.

Rounding up moves to the last millisecond of the rounding scope, and rounding down to the first millisecond of the rounding scope. For example:

gt

Greater than the date rounded up: 2014-11-18||/M becomes 2014-11-30T23:59:59.999, ie excluding the entire month.

gte

Greater than or equal to the date rounded down: 2014-11-18||/M becomes 2014-11-01, ie including the entire month.

lt

Less than the date rounded down: 2014-11-18||/M becomes 2014-11-01, ie excluding the entire month.

lte

Less than or equal to the date rounded up: 2014-11-18||/M becomes 2014-11-30T23:59:59.999, ie including the entire month.

Date format in range queries

Formatted dates will be parsed using the format specified on the date field by default, but it can be overridden by passing the format parameter to the range query:

GET _search
{
    "query": {
        "range" : {
            "born" : {
                "gte": "01/01/2012",
                "lte": "2013",
                "format": "dd/MM/yyyy||yyyy"
            }
        }
    }
}

Note that if the date misses some of the year, month and day coordinates, the missing parts are filled with the start of unix time, which is January 1st, 1970. This means, that when e.g. specifying dd as the format, a value like "gte" : 10 will translate to 1970-01-10T00:00:00.000Z.

Time zone in range queries

Dates can be converted from another timezone to UTC either by specifying the time zone in the date value itself (if the format accepts it), or it can be specified as the time_zone parameter:

GET _search
{
    "query": {
        "range" : {
            "timestamp" : {
                "gte": "2015-01-01 00:00:00", 
                "lte": "now", 
                "time_zone": "+01:00"
            }
        }
    }
}

This date will be converted to 2014-12-31T23:00:00 UTC.

now is not affected by the time_zone parameter, its always the current system time (in UTC). However, when using date math rounding (e.g. down to the nearest day using now/d), the provided time_zone will be considered.

Querying range fields

range queries can be used on fields of type range, allowing to match a range specified in the query with a range field value in the document. The relation parameter controls how these two ranges are matched:

WITHIN

Matches documents who’s range field is entirely within the query’s range.

CONTAINS

Matches documents who’s range field entirely contains the query’s range.

INTERSECTS

Matches documents who’s range field intersects the query’s range. This is the default value when querying range fields.

For examples, see range mapping type.

«  Terms Set Query     Exists Query  »