Unsigned long field type

Introduced 2.8

The unsigned_long field type is a numeric field type that represents an unsigned 64-bit integer with a minimum value of 0 and a maximum value of 264 − 1. In the following example, counter is mapped as an unsigned_long field:

  1. PUT testindex 
  2. {
  3.   "mappings" : {
  4.     "properties" :  {
  5.       "counter" : {
  6.         "type" : "unsigned_long"
  7.       }
  8.     }
  9.   }
  10. }

copy

Indexing

To index a document with an unsigned_long value, use the following request:

  1. PUT testindex/_doc/1 
  2. {
  3.   "counter" : 10223372036854775807
  4. }

copy

Alternatively, you can use the Bulk API as follows:

  1. POST _bulk
  2. { "index": { "_index": "testindex", "_id": "1" } }
  3. { "counter": 10223372036854775807 }

copy

If a field of type unsigned_long has the store parameter set to true (that is, the field is a stored field), it will be stored and returned as a string. unsigned_long values do not support the decimal part, so, if supplied, the decimal part is truncated.

Querying

unsigned_long fields support most of the queries that other numeric types support. For example, you can use a term query on unsigned_long fields:

  1. POST _search
  2. {
  3.   "query": {
  4.     "term": {
  5.       "counter": {
  6.         "value": 10223372036854775807
  7.       }
  8.     }
  9.   }
  10. }

copy

You can also use a range query:

  1. POST _search
  2. {
  3.   "query": {
  4.     "range": {
  5.       "counter": {
  6.         "gte": 10223372036854775807
  7.       }
  8.     }
  9.   }
  10. }

copy

Sorting

You can use sort values with unsigned_long fields to order the search results, for example:

  1. POST _search
  2. {
  3.   "sort" : [
  4.     { 
  5.       "counter" : { 
  6.         "order" : "asc" 
  7.       } 
  8.     }
  9.   ],
  10.   "query": {
  11.     "range": {
  12.       "counter": {
  13.         "gte": 10223372036854775807
  14.       }
  15.     }
  16.   }
  17. }

copy

An unsigned_long field cannot be used as an index sort field (in the sort.field index setting).

Aggregations

Like other numeric fields, unsigned_long fields support aggregations. For terms and multi_terms aggregations, unsigned_long values are used as is, but for other aggregation types, the values are converted to the double type (with possible loss of precision). The following is an example of the terms aggregation:

  1. POST _search
  2. {
  3.   "query": {
  4.     "match_all": {}
  5.   },
  6.   "aggs": {
  7.     "counters": {
  8.       "terms": { 
  9.          "field": "counter" 
  10.       }
  11.     }
  12.   }
  13. }

copy

Scripting

In scripts, unsigned_long fields are returned as instances of the BigInteger class:

  1. POST _search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "filter": {
  6.         "script": {
  7.           "script": "BigInteger amount = doc['counter'].value; return amount.compareTo(BigInteger.ZERO) > 0;"
  8.         }
  9.       }
  10.     }
  11.   }
  12. }

copy

Limitations

Note the following limitations of the unsigned_long field type:

  • When aggregations are performed across different numeric types and one of the types is unsigned_long, the values are converted to the double type and double arithmetic is used, with high likelihood of precision loss.

  • An unsigned_long field cannot be used as an index sort field (in the sort.field index setting). This limitation also applies when a search is performed on multiple indexes and the results are sorted by the field that has the unsigned_long type in at least one of the indexes but a different numeric type or types in others.