diff --git a/_field-types/flat-object.md b/_field-types/supported-field-types/flat-object.md similarity index 99% rename from _field-types/flat-object.md rename to _field-types/supported-field-types/flat-object.md index 1f76f6d1..84cf0749 100644 --- a/_field-types/flat-object.md +++ b/_field-types/supported-field-types/flat-object.md @@ -5,6 +5,8 @@ nav_order: 43 has_children: false parent: Object field types grand_parent: Supported field types +redirect_from: + - /field-types/flat-object/ --- # Flat object field type diff --git a/_field-types/supported-field-types/index.md b/_field-types/supported-field-types/index.md index 230f6351..38b45860 100644 --- a/_field-types/supported-field-types/index.md +++ b/_field-types/supported-field-types/index.md @@ -17,7 +17,7 @@ Field data type | Description :--- | :--- [`alias`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/alias/) | An additional name for an existing field. [`binary`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/binary/) | A binary value in Base64 encoding. -[Numeric]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) | `byte`, `double`, `float`, `half_float`, `integer`, `long`, `scaled_float`, `short`. +[Numeric]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/) | `byte`, `double`, `float`, `half_float`, `integer`, `long`, `unsigned_long`, `scaled_float`, `short`. [`boolean`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/boolean/) | A Boolean value. [`date`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/) | A date value as a formatted string, a long value, or an integer. [`ip`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/ip/) | An IP address in IPv4 or IPv6 format. diff --git a/_field-types/supported-field-types/numeric.md b/_field-types/supported-field-types/numeric.md index d31cad8f..b887b8be 100644 --- a/_field-types/supported-field-types/numeric.md +++ b/_field-types/supported-field-types/numeric.md @@ -3,7 +3,7 @@ layout: default title: Numeric field types parent: Supported field types nav_order: 15 -has_children: false +has_children: true redirect_from: - /opensearch/supported-field-types/numeric/ - /field-types/numeric/ @@ -15,15 +15,14 @@ The following table lists all numeric field types that OpenSearch supports. Field data type | Description :--- | :--- -`byte` | A signed 8-bit integer. Minimum is -128. Maximum is 127. -`double` | A double-precision 64-bit IEEE 754 floating-point value. Minimum magnitude is 2-1074 . Maximum magnitude is (2 − 2-52) · 21023. The number of significant bits is 53. The number of significant digits is 15.95. -`float` | A single-precision 32-bit IEEE 754 floating-point value. Minimum magnitude is 2-149 . Maximum magnitude is (2 − 2-23) · 2127. The number of significant bits is 24. The number of significant digits is 7.22. -`half_float` | A half-precision 16-bit IEEE 754 floating-point value. Minimum magnitude is 2-24 . Maximum magnitude is 65504. The number of significant bits is 11. The number of significant digits is 3.31. -`integer` | A signed 32-bit integer. Minimum is -231. Maximum is 231 − 1. -`long` | A signed 64-bit integer. Minimum is -263. Maximum is 263 − 1. -`short` | A signed 16-bit integer. Minimum is -215. Maximum is 215 − 1. - -:--- | :--- +`byte` | A signed 8-bit integer. Minimum is −128. Maximum is 127. +`double` | A double-precision 64-bit IEEE 754 floating-point value. Minimum magnitude is 2−1074 . Maximum magnitude is (2 − 2−52) · 21023. The number of significant bits is 53. The number of significant digits is 15.95. +`float` | A single-precision 32-bit IEEE 754 floating-point value. Minimum magnitude is 2−149 . Maximum magnitude is (2 − 2−23) · 2127. The number of significant bits is 24. The number of significant digits is 7.22. +`half_float` | A half-precision 16-bit IEEE 754 floating-point value. Minimum magnitude is 2−24 . Maximum magnitude is 65504. The number of significant bits is 11. The number of significant digits is 3.31. +`integer` | A signed 32-bit integer. Minimum is −231. Maximum is 231 − 1. +`long` | A signed 64-bit integer. Minimum is −263. Maximum is 263 − 1. +[`unsigned_long`]({{site.url}}{{site.baseurl}}/field-types/supported-field-types/unsigned-long/) | An unsigned 64-bit integer. Minimum is 0. Maximum is 264 − 1. +`short` | A signed 16-bit integer. Minimum is −215. Maximum is 215 − 1. [`scaled_float`](#scaled-float-field-type) | A floating-point value that is multiplied by the double scale factor and stored as a long value. Integer, long, float, and double field types have corresponding [range field types]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/range/). diff --git a/_field-types/supported-field-types/unsigned-long.md b/_field-types/supported-field-types/unsigned-long.md new file mode 100644 index 00000000..dde8d25d --- /dev/null +++ b/_field-types/supported-field-types/unsigned-long.md @@ -0,0 +1,164 @@ +--- +layout: default +title: Unsigned long +parent: Numeric field types +grand_parent: Supported field types +nav_order: 15 +has_children: false +--- + +# Unsigned long field type + +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: + + +```json +PUT testindex +{ + "mappings" : { + "properties" : { + "counter" : { + "type" : "unsigned_long" + } + } + } +} +``` +{% include copy-curl.html %} + +## Indexing + +To index a document with an `unsigned_long` value, use the following request: + +```json +PUT testindex/_doc/1 +{ + "counter" : 10223372036854775807 +} +``` +{% include copy-curl.html %} + +Alternatively, you can use the [Bulk API]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/) as follows: + +```json +POST _bulk +{ "index": { "_index": "testindex", "_id": "1" } } +{ "counter": 10223372036854775807 } +``` +{% include copy-curl.html %} + +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. +{: .note} + +## 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: + +```json +POST _search +{ + "query": { + "term": { + "counter": { + "value": 10223372036854775807 + } + } + } +} +``` +{% include copy-curl.html %} + +You can also use a range query: + +```json +POST _search +{ + "query": { + "range": { + "counter": { + "gte": 10223372036854775807 + } + } + } +} +``` +{% include copy-curl.html %} + +## Sorting + +You can use `sort` values with `unsigned_long` fields to order the search results, for example: + +```json +POST _search +{ + "sort" : [ + { + "counter" : { + "order" : "asc" + } + } + ], + "query": { + "range": { + "counter": { + "gte": 10223372036854775807 + } + } + } +} +``` +{% include copy-curl.html %} + + +An `unsigned_long` field cannot be used as an index sort field (in the `sort.field` index setting). +{: .warning} + +## 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: + +```json +POST _search +{ + "query": { + "match_all": {} + }, + "aggs": { + "counters": { + "terms": { + "field": "counter" + } + } + } +} +``` +{% include copy-curl.html %} + +## Scripting + +In scripts, `unsigned_long` fields are returned as instances of the `BigInteger` class: + +```json +POST _search +{ + "query": { + "bool": { + "filter": { + "script": { + "script": "BigInteger amount = doc['counter'].value; return amount.compareTo(BigInteger.ZERO) > 0;" + } + } + } + } +} +``` +{% include copy-curl.html %} + + +## 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. \ No newline at end of file