Range field types

Introduced 1.0

The following table lists all range field types that OpenSearch supports.

Field data typeDescription
integer_rangeA range of integer values.
long_rangeA range of long values.
double_rangeA range of double values.
float_rangeA range of float values.
ip_rangeA range of IP addresses in IPv4 or IPv6 format. Start and end IP addresses may be in different formats.
date_rangeA range of date values. Start and end dates may be in different formats. Internally, all dates are stored as unsigned 64-bit integers representing milliseconds since the epoch.

Example

Create a mapping with a double range and a date range:

  1. PUT testindex 
  2. {
  3.   "mappings" : {
  4.     "properties" :  {
  5.       "gpa" : {
  6.         "type" : "double_range"
  7.       },
  8.       "graduation_date" : {
  9.         "type" : "date_range",
  10.         "format" : "strict_year_month||strict_year_month_day"
  11.       }
  12.     }
  13.   }
  14. }

copy

Index a document with a double range and a date range:

  1. PUT testindex/_doc/1
  2. {
  3.   "gpa" : {
  4.     "gte" : 1.0,
  5.     "lte" : 4.0
  6.   },
  7.   "graduation_date" : {
  8.     "gte" : "2019-05-01",
  9.     "lte" : "2019-05-15"
  10.   }
  11. }

copy

IP address ranges

You can specify IP address ranges in two formats: as a range and in CIDR notation.

Create a mapping with an IP address range:

  1. PUT testindex 
  2. {
  3.   "mappings" : {
  4.     "properties" :  {
  5.       "ip_address_range" : {
  6.         "type" : "ip_range" 
  7.       },
  8.       "ip_address_cidr" : {
  9.         "type" : "ip_range" 
  10.       }
  11.     }
  12.   }
  13. }

copy

Index a document with IP address ranges in both formats:

  1. PUT testindex/_doc/2
  2. {
  3.   "ip_address_range" : {
  4.     "gte" : "10.24.34.0",
  5.     "lte" : "10.24.35.255"
  6.   },
  7.   "ip_address_cidr" : "10.24.34.0/24"
  8. }

copy

Querying range fields

You can use a Term query or a Range query to search for values within range fields.

Term query

A term query takes a value and matches all range fields for which the value is within the range.

The following query will return document 1 because 3.5 is within the range [1.0, 4.0]:

  1. GET testindex/_search
  2. {
  3.   "query" : {
  4.     "term" : {
  5.       "gpa" : {
  6.         "value" : 3.5
  7.       }
  8.     }
  9.   }
  10. }

copy

Range query

A range query on a range field returns documents within that range.

Query for all graduation dates in 2019, providing the date range in a “MM/dd/yyyy” format:

  1. GET testindex1/_search
  2. {
  3.   "query": {
  4.     "range": {
  5.       "graduation_date": {
  6.         "gte": "01/01/2019",
  7.         "lte": "12/31/2019",
  8.         "format": "MM/dd/yyyy",
  9.         "relation" : "within"       
  10.       }
  11.     }
  12.   }
  13. }

copy

The preceding query will return document 1 for the within and intersects relations but will not return it for the contains relation. For more information about relation types, see range query parameters.

Parameters

The following table lists the parameters accepted by range field types. All parameters are optional.

ParameterDescription
boostA floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field’s relevance. Values between 0.0 and 1.0 decrease the field’s relevance. Default is 1.0.
coerceA Boolean value that signals to truncate decimals for integer values and to convert strings to numeric values. Default is true.
indexA Boolean value that specifies whether the field should be searchable. Default is true.
storeA Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is false.