honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
OpenSearch/docs/reference/query-dsl/range-query.asciidoc

120 lines
3.3 KiB
Plaintext
Raw Normal View History

Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
[[query-dsl-range-query]]
Docs: Reorganised the Query DSL docs into families and explaing query vs filter context
2015-06-03 19:59:22 -04:00
=== Range Query
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
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`:
[source,js]
--------------------------------------------------
{
"range" : {
[DOCS] Deprecated the from/to/include_lower/include_upper params in the range query, range filter and numeric range filter. Better to use gt/gte/lt/lte as they are explicit.
2013-09-12 09:07:15 -04:00
"age" : {
"gte" : 10,
"lte" : 20,
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
"boost" : 2.0
}
}
}
--------------------------------------------------
[DOCS] Deprecated the from/to/include_lower/include_upper params in the range query, range filter and numeric range filter. Better to use gt/gte/lt/lte as they are explicit.
2013-09-12 09:07:15 -04:00
The `range` query accepts the following parameters:
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
[DOCS] Deprecated the from/to/include_lower/include_upper params in the range query, range filter and numeric range filter. Better to use gt/gte/lt/lte as they are explicit.
2013-09-12 09:07:15 -04:00
[horizontal]
`gte`:: Greater-than or equal to
`gt`:: Greater-than
`lte`:: Less-than or equal to
`lt`:: Less-than
[DOCS] fixed typo Closes #5272
2014-03-26 09:51:02 -04:00
`boost`:: Sets the boost value of the query, defaults to `1.0`
Migrated documentation into the main repo
2013-08-28 19:24:34 -04:00
Search: add `format` support for date range filter and queries When the date format is defined in mapping, you can not use another format when querying using range date query or filter. For example, this won't work: ``` DELETE /test PUT /test/t/1 { "date": "2014-01-01" } GET /test/_search { "query": { "filtered": { "filter": { "range": { "date": { "from": "01/01/2014" } } } } } } ``` It causes: ``` Caused by: org.elasticsearch.ElasticsearchParseException: failed to parse date field [01/01/2014], tried both date format [dateOptionalTime], and timestamp number ``` It could be nice if we can support at query time another date format just like we support `analyzer` at search time on String fields. Something like: ``` GET /test/_search { "query": { "filtered": { "filter": { "range": { "date": { "from": "01/01/2014", "format": "dd/MM/yyyy" } } } } } } ``` Same for queries: ``` GET /test/_search { "query": { "range": { "date": { "from": "01/01/2014", "format": "dd/MM/yyyy" } } } } ``` Closes #7189.
2014-09-22 13:40:16 -04:00
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
[[ranges-on-dates]]
==== Ranges on date fields
When running `range` queries on fields of type <<date,`date`>>, ranges can be
specified using <<date-math>>::
Search: add time zone setting for relative date math in range filter/query Filters and Queries now supports `time_zone` parameter which defines which time zone should be applied to the query or filter to convert it to UTC time based value. When applied on `date` fields the `range` filter and queries accept also a `time_zone` parameter. The `time_zone` parameter will be applied to your input lower and upper bounds and will move them to UTC time based date: [source,js] -------------------------------------------------- { "constant_score": { "filter": { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } } } { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } -------------------------------------------------- In the above examples, `gte` will be actually moved to `2011-12-31T23:00:00` UTC date. NOTE: if you give a date with a timezone explicitly defined and use the `time_zone` parameter, `time_zone` will be ignored. For example, setting `from` to `2012-01-01T00:00:00+01:00` with `"time_zone":"+10:00"` will still use `+01:00` time zone. Closes #3729.
2014-07-31 10:22:03 -04:00
[source,js]
--------------------------------------------------
{
"range" : {
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
"date" : {
"gte" : "now-1d/d",
"lt" : "now/d"
Search: add time zone setting for relative date math in range filter/query Filters and Queries now supports `time_zone` parameter which defines which time zone should be applied to the query or filter to convert it to UTC time based value. When applied on `date` fields the `range` filter and queries accept also a `time_zone` parameter. The `time_zone` parameter will be applied to your input lower and upper bounds and will move them to UTC time based date: [source,js] -------------------------------------------------- { "constant_score": { "filter": { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } } } { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } -------------------------------------------------- In the above examples, `gte` will be actually moved to `2011-12-31T23:00:00` UTC date. NOTE: if you give a date with a timezone explicitly defined and use the `time_zone` parameter, `time_zone` will be ignored. For example, setting `from` to `2012-01-01T00:00:00+01:00` with `"time_zone":"+10:00"` will still use `+01:00` time zone. Closes #3729.
2014-07-31 10:22:03 -04:00
}
}
}
--------------------------------------------------
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
===== Date math and rounding
When using <<date-math,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:
[horizontal]
`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.
Search: add time zone setting for relative date math in range filter/query Filters and Queries now supports `time_zone` parameter which defines which time zone should be applied to the query or filter to convert it to UTC time based value. When applied on `date` fields the `range` filter and queries accept also a `time_zone` parameter. The `time_zone` parameter will be applied to your input lower and upper bounds and will move them to UTC time based date: [source,js] -------------------------------------------------- { "constant_score": { "filter": { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } } } { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } -------------------------------------------------- In the above examples, `gte` will be actually moved to `2011-12-31T23:00:00` UTC date. NOTE: if you give a date with a timezone explicitly defined and use the `time_zone` parameter, `time_zone` will be ignored. For example, setting `from` to `2012-01-01T00:00:00+01:00` with `"time_zone":"+10:00"` will still use `+01:00` time zone. Closes #3729.
2014-07-31 10:22:03 -04:00
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
===== Date format in range queries
Search: add time zone setting for relative date math in range filter/query Filters and Queries now supports `time_zone` parameter which defines which time zone should be applied to the query or filter to convert it to UTC time based value. When applied on `date` fields the `range` filter and queries accept also a `time_zone` parameter. The `time_zone` parameter will be applied to your input lower and upper bounds and will move them to UTC time based date: [source,js] -------------------------------------------------- { "constant_score": { "filter": { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } } } { "range" : { "born" : { "gte": "2012-01-01", "lte": "now", "time_zone": "+1:00" } } } -------------------------------------------------- In the above examples, `gte` will be actually moved to `2011-12-31T23:00:00` UTC date. NOTE: if you give a date with a timezone explicitly defined and use the `time_zone` parameter, `time_zone` will be ignored. For example, setting `from` to `2012-01-01T00:00:00+01:00` with `"time_zone":"+10:00"` will still use `+01:00` time zone. Closes #3729.
2014-07-31 10:22:03 -04:00
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
Formatted dates will be parsed using the <<mapping-date-format,`format`>>
specified on the <<date,`date`>> field by default, but it can be overridden by
passing the `format` parameter to the `range` query:
Search: add `format` support for date range filter and queries When the date format is defined in mapping, you can not use another format when querying using range date query or filter. For example, this won't work: ``` DELETE /test PUT /test/t/1 { "date": "2014-01-01" } GET /test/_search { "query": { "filtered": { "filter": { "range": { "date": { "from": "01/01/2014" } } } } } } ``` It causes: ``` Caused by: org.elasticsearch.ElasticsearchParseException: failed to parse date field [01/01/2014], tried both date format [dateOptionalTime], and timestamp number ``` It could be nice if we can support at query time another date format just like we support `analyzer` at search time on String fields. Something like: ``` GET /test/_search { "query": { "filtered": { "filter": { "range": { "date": { "from": "01/01/2014", "format": "dd/MM/yyyy" } } } } } } ``` Same for queries: ``` GET /test/_search { "query": { "range": { "date": { "from": "01/01/2014", "format": "dd/MM/yyyy" } } } } ``` Closes #7189.
2014-09-22 13:40:16 -04:00
[source,js]
--------------------------------------------------
{
"range" : {
"born" : {
"gte": "01/01/2012",
"lte": "2013",
"format": "dd/MM/yyyy||yyyy"
}
}
}
--------------------------------------------------
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
===== 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 <<mapping-date-format, `format`>>
accepts it), or it can be specified as the `time_zone` parameter:
[source,js]
--------------------------------------------------
{
"range" : {
"timestamp" : {
"gte": "2015-01-01 00:00:00", <1>
Documents that now is not affected by time_zone in range queries
2015-09-23 21:00:49 -04:00
"lte": "now", <2>
Docs: Mapping docs completely rewritten for 2.0
2015-08-06 11:24:29 -04:00
"time_zone": "+01:00"
}
}
}
--------------------------------------------------
<1> This date will be converted to `2014-12-31T23:00:00 UTC`.
Gives more emphasys
2015-09-24 10:30:00 -04:00
<2> `now` is not affected by the `time_zone` parameter (dates must be stored as UTC).