IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Point field type Rank feature field type »

› › ›

Range field types

edit

Range field types

edit

Range field types represent a continuous range of values between an upper and lower bound. For example, a range can represent any date in October or any integer from 0 to 9. They are defined using the operators gt or gte for the lower bound, and lt or lte for the upper bound. They can be used for querying, and have limited support for aggregations. The only supported aggregations are histogram, cardinality.

The following range types are supported:

`integer_range`	A range of signed 32-bit integers with a minimum value of `-2³¹` and maximum of `2³¹-1`.
`float_range`	A range of single-precision 32-bit IEEE 754 floating point values.
`long_range`	A range of signed 64-bit integers with a minimum value of `-2⁶³` and maximum of `2⁶³-1`.
`double_range`	A range of double-precision 64-bit IEEE 754 floating point values.
`date_range`	A range of `date` values. Date ranges support various date formats through the `format` mapping parameter. Regardless of the format used, date values are parsed into an unsigned 64-bit integer representing milliseconds since the Unix epoch in UTC. Values containing the `now` date math expression are not supported.
`ip_range`	A range of ip values supporting either IPv4 or IPv6 (or mixed) addresses.

Below is an example of configuring a mapping with various range fields followed by an example that indexes several range types.

response = client.indices.create(
  index: 'range_index',
  body: {
    settings: {
      number_of_shards: 2
    },
    mappings: {
      properties: {
        expected_attendees: {
          type: 'integer_range'
        },
        time_frame: {
          type: 'date_range',
          format: 'yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis'
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'range_index',
  id: 1,
  refresh: true,
  body: {
    expected_attendees: {
      gte: 10,
      lt: 20
    },
    time_frame: {
      gte: '2015-10-31 12:00:00',
      lte: '2015-11-01'
    }
  }
)
puts response

PUT range_index
{
  "settings": {
    "number_of_shards": 2
  },
  "mappings": {
    "properties": {
      "expected_attendees": {
        "type": "integer_range"
      },
      "time_frame": {
        "type": "date_range", 
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  }
}

PUT range_index/_doc/1?refresh
{
  "expected_attendees" : { 
    "gte" : 10,
    "lt" : 20
  },
  "time_frame" : {
    "gte" : "2015-10-31 12:00:00", 
    "lte" : "2015-11-01"
  }
}

	`date_range` types accept the same field parameters defined by the `date` type.
	Example indexing a meeting with 10 to 20 attendees, not including 20.
	Example date range using date time stamp.

The following is an example of a term query on the integer_range field named "expected_attendees". 12 is a value inside the range, so it will match.

response = client.search(
  index: 'range_index',
  body: {
    query: {
      term: {
        expected_attendees: {
          value: 12
        }
      }
    }
  }
)
puts response

GET range_index/_search
{
  "query" : {
    "term" : {
      "expected_attendees" : {
        "value": 12
      }
    }
  }
}

The result produced by the above query.

{
  "took": 13,
  "timed_out": false,
  "_shards" : {
    "total": 2,
    "successful": 2,
    "skipped" : 0,
    "failed": 0
  },
  "hits" : {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "range_index",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "expected_attendees" : {
            "gte" : 10, "lt" : 20
          },
          "time_frame" : {
            "gte" : "2015-10-31 12:00:00", "lte" : "2015-11-01"
          }
        }
      }
    ]
  }
}

The following is an example of a date_range query over the date_range field named "time_frame".

response = client.search(
  index: 'range_index',
  body: {
    query: {
      range: {
        time_frame: {
          gte: '2015-10-31',
          lte: '2015-11-01',
          relation: 'within'
        }
      }
    }
  }
)
puts response

GET range_index/_search
{
  "query" : {
    "range" : {
      "time_frame" : { 
        "gte" : "2015-10-31",
        "lte" : "2015-11-01",
        "relation" : "within" 
      }
    }
  }
}

	Range queries work the same as described in range query.
	Range queries over range fields support a `relation` parameter which can be one of `WITHIN`, `CONTAINS`, `INTERSECTS` (default).

This query produces a similar result:

{
  "took": 13,
  "timed_out": false,
  "_shards" : {
    "total": 2,
    "successful": 2,
    "skipped" : 0,
    "failed": 0
  },
  "hits" : {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "range_index",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "expected_attendees" : {
            "gte" : 10, "lt" : 20
          },
          "time_frame" : {
            "gte" : "2015-10-31 12:00:00", "lte" : "2015-11-01"
          }
        }
      }
    ]
  }
}

IP Range

edit

In addition to the range format above, IP ranges can be provided in CIDR notation:

response = client.indices.put_mapping(
  index: 'range_index',
  body: {
    properties: {
      ip_allowlist: {
        type: 'ip_range'
      }
    }
  }
)
puts response

response = client.index(
  index: 'range_index',
  id: 2,
  body: {
    ip_allowlist: '192.168.0.0/16'
  }
)
puts response

PUT range_index/_mapping
{
  "properties": {
    "ip_allowlist": {
      "type": "ip_range"
    }
  }
}

PUT range_index/_doc/2
{
  "ip_allowlist" : "192.168.0.0/16"
}

Parameters for range fields

edit

The following parameters are accepted by range types:

`coerce`	Try to convert strings to numbers and truncate fractions for integers. Accepts `true` (default) and `false`.
`index`	Should the field be searchable? Accepts `true` (default) and `false`.
`store`	Whether the field value should be stored and retrievable separately from the `_source` field. Accepts `true` or `false` (default).

« Point field type Rank feature field type »