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

layout	title	parent	grand_parent	nav_order
default	Range	Term-level queries	Query DSL	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:

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:

GET products/_search
{
  "query": {
    "range": {
      "created": {
        "gte": "2019/01/01",
        "lte": "2019/12/31"
      }
    }
  }
}

{% include copy-curl.html %}

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:

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:

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.

To subtract 1 year and 1 day from the specified date, use the following query:

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:

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

To convert date values to Coordinated Universal Time (UTC) using a UTC offset, use the time_zone parameter:

GET /products/_search
{
  "query": {
    "range": {
      "created": {
        "time_zone": "-04:00",        
        "gte": "2022-04-17T06:00:00" 
      }
    }
  }
}

{% include copy-curl.html %}

The preceding query specifies the -04:00 offset, so the gte parameter is converted to 2022-04-17T10:00:00 UTC.

The time_zone parameter does not affect the now value. {: .note}

Parameters

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

GET _search
{
  "query": {
    "range": {
      "<field>": {
        "gt": 10,
        ... 
      }
    }
  }
}

{% include copy-curl.html %}

In addition to operators, you can specify the following optional parameters for the <field>.

Parameter	Data type	Description
format	String	A format for dates in this query. Default is the field's mapped format.
relation	String	Indicates how the range query matches values for range fields. Valid values are: - INTERSECTS (default): Matches documents whose range field value intersects the range provided in the query. - CONTAINS: Matches documents whose range field value contains the entire range provided in the query. - 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 values to UTC in the query. Valid values are ISO 8601 UTC offsets and IANA time zone IDs. For more information, see Time zone.

If search.allow_expensive_queries is set to false, range queries on text and keyword fields are not run. {: .important}