opensearch-docs-cn/_query-dsl/term/range.md

223 lines
7.0 KiB
Markdown

---
layout: default
title: Range
parent: Term-level queries
grand_parent: Query DSL
nav_order: 50
---
# Range query
You can search for a range of values in a field with the `range` query.
To search for documents in which the `line_id` value is >= 10 and <= 20, use the following request:
```json
GET shakespeare/_search
{
"query": {
"range": {
"line_id": {
"gte": 10,
"lte": 20
}
}
}
}
```
{% include copy-curl.html %}
## Operators
The field parameter in the range query accepts the following optional operator parameters:
- `gte`: Greater than or equal to
- `gt`: Greater than
- `lte`: Less than or equal to
- `lt`: Less than
## Date fields
You can use range queries on fields containing dates. For example, assume that you have a `products` index and you want to find all the products that were added in the year 2019:
```json
GET products/_search
{
"query": {
"range": {
"created": {
"gte": "2019/01/01",
"lte": "2019/12/31"
}
}
}
}
```
{% include copy-curl.html %}
For more information about supported date formats, see [Formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#formats).
### Format
To use a date format other than the field's mapped format in a query, specify it in the `format` field.
For example, if the `products` index maps the `created` field as `strict_date_optional_time`, you can specify a different format for a query date as follows:
```json
GET /products/_search
{
"query": {
"range": {
"created": {
"gte": "01/01/2022",
"lte": "31/12/2022",
"format":"dd/MM/yyyy"
}
}
}
}
```
{% include copy-curl.html %}
### Missing date components
OpenSearch populates missing date components with the following values:
- `MONTH_OF_YEAR`: `01`
- `DAY_OF_MONTH`: `01`
- `HOUR_OF_DAY`: `23`
- `MINUTE_OF_HOUR`: `59`
- `SECOND_OF_MINUTE`: `59`
- `NANO_OF_SECOND`: `999_999_999`
If the year is missing, it is not populated.
For example, consider the following request that specifies only the year in the start date:
```json
GET /products/_search
{
"query": {
"range": {
"created": {
"gte": "2022",
"lte": "2022-12-31"
}
}
}
}
```
{% include copy-curl.html %}
The start date is populated with the default values, so the `gte` parameter used is `2022-01-01T23:59:59.999999999Z`.
### Relative dates
You can specify relative dates by using [date math]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#date-math).
To subtract 1 year and 1 day from the specified date, use the following query:
```json
GET products/_search
{
"query": {
"range": {
"created": {
"gte": "2019/01/01||-1y-1d"
}
}
}
}
```
{% include copy-curl.html %}
In the preceding example, `2019/01/01` is the anchor date (the starting point) for the date math. After the two pipe characters (`||`), you are specifying a mathematical expression relative to the anchor date. In this example, you are subtracting 1 year (`-1y`) and 1 day (`-1d`).
You can also round off dates by adding a forward slash to the date or time unit.
To find products added within the last year, rounded off by month, use the following query:
```json
GET products/_search
{
"query": {
"range": {
"created": {
"gte": "now-1y/M"
}
}
}
}
```
{% include copy-curl.html %}
The keyword `now` refers to the current date and time.
{: .tip}
### Rounding relative dates
The following table specifies how relative dates are rounded.
Parameter | Rounding rule | Example: The value `2022-05-18||/M` is rounded to
:--- | :--- | :---
`gt` | Rounds up to the first millisecond that is not in the rounding interval. | `2022-06-01T00:00:00.000`
`gte` | Rounds down to the first millisecond. | `2022-05-01T00:00:00.000`
`lt` | Rounds down to the last millisecond before the rounded date. | `2022-04-30T23:59:59.999`
`lte` | Rounds up to the last millisecond in the rounding interval. | `2022-05-31T23:59:59.999`
### Time zone
By default, dates are assumed to be in [Coordinated Universal Time (UTC)](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). If you specify a `time_zone` parameter in the query, the provided date values are converted to UTC. You can specify the `time_zone` parameter as a [UTC offset](https://en.wikipedia.org/wiki/UTC_offset), such as `-04:00`, or an [IANA time zone ID](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), such as `America/New_York`. For example, the following query specifies that the `gte` date provided in the query is in the `-04:00` time zone:
```json
GET /products/_search
{
"query": {
"range": {
"created": {
"time_zone": "-04:00",
"gte": "2022-04-17T06:00:00"
}
}
}
}
```
{% include copy-curl.html %}
The `gte` parameter in the preceding query is converted to `2022-04-17T10:00:00 UTC`, which is the UTC equivalent of `2022-04-17T06:00:00-04:00`.
The `time_zone` parameter does not affect the `now` value because `now` always corresponds to the current system time in UTC.
{: .note}
## Parameters
The query accepts the name of the field (`<field>`) as a top-level parameter:
```json
GET _search
{
"query": {
"range": {
"<field>": {
"gt": 10,
...
}
}
}
}
```
{% include copy-curl.html %}
In addition to [operators](#operators), you can specify the following optional parameters for the `<field>`.
Parameter | Data type | Description
:--- | :--- | :---
`format` | String | A [format]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#formats) for dates in this query. Default is the field's mapped format.
`relation` | String | Indicates how the range query matches values for [`range`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/range/) fields. Valid values are:<br> - `INTERSECTS` (default): Matches documents whose `range` field value intersects the range provided in the query. <br> - `CONTAINS`: Matches documents whose `range` field value contains the entire range provided in the query. <br> - `WITHIN`: Matches documents whose `range` field value is entirely within the range provided in the query.
`boost` | Floating-point | Boosts the query by the given multiplier. Useful for searches that contain more than one query. Values in the [0, 1) range decrease relevance, and values greater than 1 increase relevance. Default is `1`.
`time_zone` | String | The time zone used to convert [`date`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/) values to UTC in the query. Valid values are ISO 8601 [UTC offsets](https://en.wikipedia.org/wiki/List_of_UTC_offsets) and [IANA time zone IDs](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). For more information, see [Time zone](#time-zone).
If [`search.allow_expensive_queries`]({{site.url}}{{site.baseurl}}/query-dsl/index/#expensive-queries) is set to `false`, range queries on [`text`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/text/) and [`keyword`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/keyword/) fields are not run.
{: .important}