This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Range field types

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

Example

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

PUT testindex 
{
  "mappings" : {
    "properties" :  {
      "gpa" : {
        "type" : "double_range"
      },
      "graduation_date" : {
        "type" : "date_range",
        "format" : "strict_year_month||strict_year_month_day"
      }
    }
  }
}

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

PUT testindex/_doc/1
{
  "gpa" : {
    "gte" : 1.0,
    "lte" : 4.0
  },
  "graduation_date" : {
    "gte" : "2019-05-01",
    "lte" : "2019-05-15"
  }
}

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]:

GET testindex/_search
{
  "query" : {
    "term" : {
      "gpa" : {
        "value" : 3.5
      }
    }
  }
}

Range query optional parameters

A range query on a range field returns documents within that range. Along with the field to be matched, you can further specify a date format or relational operators with the following optional parameters:

To use a date format other than the field’s mapped format in a query, specify it in the format field.

For a full description of range query usage, including all range query parameters, see Range query.

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

GET testindex1/_search
{
  "query": {
    "range": {
      "graduation_date": {
        "gte": "01/01/2019",
        "lte": "12/31/2019",
        "format": "MM/dd/yyyy",
        "relation" : "within"       
      }
    }
  }
}

The above query will return document 1 for the within and intersects relations but will not return it for the contains relation.

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:

PUT testindex 
{
  "mappings" : {
    "properties" :  {
      "ip_address_range" : {
        "type" : "ip_range" 
      },
      "ip_address_cidr" : {
        "type" : "ip_range" 
      }
    }
  }
}

Index a document with IP address ranges in both formats:

PUT testindex/_doc/2
{
  "ip_address_range" : {
    "gte" : "10.24.34.0",
    "lte" : "10.24.35.255"
  },
  "ip_address_cidr" : "10.24.34.0/24"
}

Parameters

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