---
metadata:
- name: generator
content: Diplodoc Platform v5.50.6
alternate:
- https://ytsaurus.tech/docs/en/yql/types/primitive.md
- https://ytsaurus.tech/docs/ru/yql/types/primitive.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ytsaurus.tech/docs/en/llms.txt
# Primitive data types
The terms "simple", "primitive", and "elementary" data types are used synonymously.
## Numeric types {#numeric}
| Type | Description | Notes |
----- | ----- | -----
| `Bool` | Boolean value. |
| `Int8` | A signed integer.
Acceptable values: from -27 to 27–1. |
| `Int16` | A signed integer.
Acceptable values: from –215 to 215–1. |
| `Int32` | A signed integer.
Acceptable values: from –231 to 231–1. |
| `Int64` | A signed integer.
Acceptable values: from –263 to 263–1. |
| `Uint8` | Unsigned integer.
Permitted values: from 0 to 28–1. |
| `Uint16` | Unsigned integer.
Permitted values: from 0 to 216–1. |
| `Uint32` | Unsigned integer.
Permitted values: from 0 to 232–1. |
| `Uint64` | Unsigned integer.
Permitted values: from 0 to 264–1. |
| `Float` | A real number with variable precision, 4 bytes in size. |
| `Double` | A real number with variable precision, 8 bytes in size. |
| `Decimal` | A real number with the specified precision, up to 35 decimal digits |
| `DyNumber` | Binary representation of a real number with a precision of 38 characters.
Allowed values: positive numbers from 1×10-130 to 1×10126–1, negative numbers from -1×10126–1 to -1×10-130, and 0.
Compatible with the AWS DynamoDB `Number` type. Not recommended for use in apps native to YTsaurus. |
## String types {#string}
| Type | Description | Notes |
----- | ----- | -----
| `String` | A string that can contain any binary data |
| `Utf8` | [UTF-8](https://en.wikipedia.org/wiki/UTF-8)-coded text. |
| `Json` | [JSON](https://en.wikipedia.org/wiki/JSON) represented as text |
| `JsonDocument` | [JSON](https://en.wikipedia.org/wiki/JSON) in an indexed binary representation |
| `Yson` | [YSON](https://ytsaurus.tech/docs/en/user-guide/storage/formats#yson) in textual or binary presentation |
| `Uuid` | [UUID](https://tools.ietf.org/html/rfc4122) universal identifier |
Unlike the `JSON` data type that stores the original text representation passed by the user, `JsonDocument` uses an indexed binary representation. An important difference from the point of view of semantics is that `JsonDocument` doesn't preserve formatting, the order of keys in objects, or their duplicates.
Thanks to the indexed view, `JsonDocument` lets you bypass the document model using `JsonPath` without the need to parse the full content. This helps efficiently perform operations from the [JSON API](https://ytsaurus.tech/docs/en/yql/builtins/json.md), reducing delays and the cost of user queries. Execution of `JsonDocument` queries can be up to several times more efficient depending on the type of load.
Due to the added redundancy, `JsonDocument` is less effective in storage. The additional storage overhead depends on the specific content, but is 20-30% of the original volume on average. Saving data in `JsonDocument` format requires additional conversion from the textual representation, which makes writing it less efficient. However, for most read-intensive scenarios that involve processing data from JSON, this data type is preferred and recommended.
{% note warning %}
[Double](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) type is used to store (JSON Number) numerical values in `JsonDocument` and perform arithmetic operations over them in [JSON API](https://ytsaurus.tech/docs/en/yql/builtins/json.md). Precision might be lost when non-standard representations of numbers are used in the source JSON document.
{% endnote %}
## Date and time {#datetime}
### Basic types {#datetime-basic}
The value range for all basic temporal types is from midnight1 on 01.01.1970 to midnight1 on 01.01.2106.
The value range for the basic interval type is from -136 years to +136 years.
| Type | Description | Notes |
----- | ----- | -----
| `Date` | Date, precision to the day | Internal representation: Unsigned 16-bit integer |
| `Datetime` | Date/time, precision to the second | Internal representation: Unsigned 32-bit integer |
| `Timestamp` | Date/time, precision to the microsecond | Internal representation: Unsigned 64-bit integer |
| `Interval` | Time interval (signed), precision to microseconds | Value range: From -136 years to +136 years. Internal representation: Signed 64-bit integer. |
| `TzDate` | Date with time zone label, precision to the day | Internal representation: Unsigned 16-bit integer and time zone label |
| `TzDatetime` | Date/time with time zone label, precision to the second | Internal representation: Unsigned 32-bit integer and time zone label |
| `TzTimestamp` | Date/time with time zone label, precision to the microsecond | Internal representation: Unsigned 64-bit integer and time zone label |
1 Midnight means a point in time where all _time_ components are zero.
### Extended types {#datetime-extended}
The value range for all extended temporal types is from midnight1 on 01.01.144169 BC to midnight1 on 01.01.148107.
The value range for the extended interval type is from -292277 years to +292277 years.
| Type | Description | Notes |
----- | ----- | -----
| `Date32` | Point in time at which midnight1 occurs in UTC, precision to the day | Internal representation: Signed 32-bit integer |
| `Datetime64` | Point in time in UTC, precision to the second | Internal representation: Signed 64-bit integer |
| `Timestamp64` | Point in time in UTC, precision to the microsecond | Internal representation: Signed 64-bit integer |
| `Interval64` | Time interval, precision to the microsecond | Internal representation: Signed 64-bit integer |
| `TzDate32` | Point in time in UTC at which midnight occurs in the specified time zone | Internal representation: Signed 32-bit integer and time zone label |
| `TzDateTime64` | Point in time in UTC with a time zone label, precision to the second | Internal representation: Signed 64-bit integer and time zone label |
| `TzTimestamp64` | Point in time in UTC with a time zone label, precision to the microsecond | Internal representation: Signed 64-bit integer and time zone label |
1 Midnight means a point in time where all _time_ components are zero.
### Supporting types with a time zone label
Time zone label for the `TzDate`, `TzDatetime`, `TzTimestamp` types is an attribute that is used:
* During ([CAST](https://ytsaurus.tech/docs/en/yql/syntax/expressions.md#cast), [DateTime::Parse](https://ytsaurus.tech/docs/en/yql/udf/list/datetime.md#parse), [DateTime::Format](https://ytsaurus.tech/docs/en/yql/udf/list/datetime.md#format)) converting into a string and from a string.
* In [DateTime::Split](https://ytsaurus.tech/docs/en/yql/udf/list/datetime.md#split), the time zone component appears in `Resource`.
The point in time for these types is stored in UTC, and the timezone label doesn't participate in any other calculations in any way. For example:
```yql
SELECT --these expressions are always true for any timezones: the timezone doesn't affect the point in time.
AddTimezone(CurrentUtcDate(), "Europe/Moscow") ==
AddTimezone(CurrentUtcDate(), "America/New_York"),
AddTimezone(CurrentUtcDatetime(), "Europe/Moscow") ==
AddTimezone(CurrentUtcDatetime(), "America/New_York");
```
Keep in mind that when converting between `TzDate` and `TzDatetime`, or `TzTimestamp` the date's midnight doesn't follow the local time zone, but midnight in UTC for the date in UTC.
## Casting between data types {#cast}
### Explicit casting {#explicit-cast}
Explicit casting using [CAST](https://ytsaurus.tech/docs/en/yql/syntax/expressions.md#cast):
#### Casting to numeric types
| Type | Bool | Int8 | Int16 | Int32 | Int64 | Uint8 | Uint16 | Uint32 | Uint64 | Float | Double | Decimal |
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
| **Bool** | — | Yes1 | Yes1 | Yes1 | Yes1 | Yes1 | Yes1 | Yes1 | Yes1 | Yes1 | Yes1 | No |
| **Int8** | Yes2 | — | Yes | Yes | Yes | Yes3 | Yes3 | Yes3 | Yes3 | Yes | Yes | Yes |
| **Int16** | Yes2 | Yes4 | — | Yes | Yes | Yes3,4 | Yes3 | Yes3 | Yes3 | Yes | Yes | Yes |
| **Int32** | Yes2 | Yes4 | Yes4 | — | Yes | Yes3,4 | Yes3,4 | Yes3 | Yes3 | Yes | Yes | Yes |
| **Int64** | Yes2 | Yes4 | Yes4 | Yes4 | — | Yes3,4 | Yes3,4 | Yes3,4 | Yes3 | Yes | Yes | Yes |
| **Uint8** | Yes2 | Yes4 | Yes | Yes | Yes | — | Yes | Yes | Yes | Yes | Yes | Yes |
| **Uint16** | Yes2 | Yes4 | Yes4 | Yes | Yes | Yes4 | — | Yes | Yes | Yes | Yes | Yes |
| **Uint32** | Yes2 | Yes4 | Yes4 | Yes4 | Yes | Yes4 | Yes4 | — | Yes | Yes | Yes | Yes |
| **Uint64** | Yes2 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | — | Yes | Yes | Yes |
| **Float** | Yes2 | Yes4 | Yes4 | Yes4 | Yes4 | Yes3,4 | Yes3,4 | Yes3,4 | Yes3,4 | — | Yes | No |
| **Double** | Yes2 | Yes4 | Yes4 | Yes4 | Yes4 | Yes3,4 | Yes3,4 | Yes3,4 | Yes3,4 | Yes | — | No |
| **Decimal** | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | — |
| **String** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Utf8** | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| **Json** | No | No | No | No | No | No | No | No | No | No | No | No |
| **Yson** | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | Yes5 | No |
| **Uuid** | No | No | No | No | No | No | No | No | No | No | No | No |
| **Date** | No | Yes4 | Yes4 | Yes | Yes | Yes4 | Yes | Yes | Yes | Yes | Yes | Yes | No |
| **Datetime** | No | Yes4 | Yes4 | Yes4 | Yes | Yes4 | Yes4 | Yes | Yes | Yes | Yes | No |
| **Timestamp** | No | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes | Yes | Yes | No |
| **Interval** | No | Yes4 | Yes4 | Yes4 | Yes | Yes3,4 | Yes3,4 | Yes3,4 | Yes3 | Yes | Yes | No |
| **Date32** | No | Yes4 | Yes4 | Yes | Yes | Yes4 | Yes | Yes | Yes | Yes | Yes | No |
| **Datetime64** | No | Yes4 | Yes4 | Yes4 | Yes | Yes4 | Yes4 | Yes | Yes | Yes | Yes | No |
| **Timestamp64** | No | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes4 | Yes | Yes | Yes | No |
| **Interval64** | No | Yes4 | Yes4 | Yes4 | Yes | Yes3,4 | Yes3,4 | Yes3,4 | Yes3 | Yes | Yes | No |
1 `True` is converted to `1` and `False` to `0`.
2 Any value other than `0` is converted to `True`, `0` is converted to `False`.
3 Possible only in the case of a non-negative value.
4 Possible only in the case of a value falling within the allowed range.
5 Using the built-in function [Yson::ConvertTo](https://ytsaurus.tech/docs/en/yql/udf/list/yson.md#ysonconvertto).
#### Converting to date and time data types
##### Basic types
| Type | Date | Datetime | Timestamp | Interval |
--- | --- | --- | --- | ---
| **Bool** | No | No | No | No |
| **Int8** | Yes | Yes | Yes | Yes |
| **Int16** | Yes | Yes | Yes | Yes |
| **Int32** | Yes | Yes | Yes | Yes |
| **Int64** | Yes | Yes | Yes | Yes |
| **Uint8** | Yes | Yes | Yes | Yes |
| **Uint16** | Yes | Yes | Yes | Yes |
| **Uint32** | Yes | Yes | Yes | Yes |
| **Uint64** | Yes | Yes | Yes | Yes |
| **Float** | No | No | No | No |
| **Double** | No | No | No | No |
| **Decimal** | No | No | No | No |
| **String** | Yes | Yes | Yes | Yes |
| **Utf8** | Yes | Yes | Yes | Yes |
| **Json** | No | No | No | No |
| **Yson** | No | No | No | No |
| **Uuid** | No | No | No | No |
| **Date** | — | Yes | Yes | No |
| **Datetime** | Yes | — | Yes | No |
| **Timestamp** | Yes | Yes | — | No |
| **Interval** | No | No | No | — |
| **Date32** | Yes | Yes | Yes | No |
| **Datetime64** | Yes | Yes | Yes | No |
| **Timestamp64** | Yes | Yes | Yes | No |
| **Interval64** | No | No | No | Yes |
##### Extended types
| Type | Date32 | Datetime64 | Timestamp64 | Interval64 |
--- | --- | --- | --- | ---
| **Bool** | No | No | No | No |
| **Int8** | Yes | Yes | Yes | Yes |
| **Int16** | Yes | Yes | Yes | Yes |
| **Int32** | Yes | Yes | Yes | Yes |
| **Int64** | Yes | Yes | Yes | Yes |
| **Uint8** | Yes | Yes | Yes | Yes |
| **Uint16** | Yes | Yes | Yes | Yes |
| **Uint32** | Yes | Yes | Yes | Yes |
| **Uint64** | Yes | Yes | Yes | Yes |
| **Float** | No | No | No | No |
| **Double** | No | No | No | No |
| **Decimal** | No | No | No | No |
| **String** | Yes | Yes | Yes | Yes |
| **Utf8** | Yes | Yes | Yes | Yes |
| **Json** | No | No | No | No |
| **Yson** | No | No | No | No |
| **Uuid** | No | No | No | No |
| **Date** | Yes | Yes | Yes | No |
| **Datetime** | Yes | Yes | Yes | No |
| **Timestamp** | Yes | Yes | Yes | No |
| **Interval** | No | No | No | Yes |
| **Date32** | — | Yes | Yes | No |
| **Datetime64** | Yes | — | Yes | No |
| **Timestamp64** | Yes | Yes | — | No |
| **Interval64** | No | No | No | — |
#### Conversion to other data types
| Type | String | Utf8 | Json | Yson | Uuid |
--- | --- | --- | --- | --- | ---
| **Bool** | Yes | No | No | No | No |
| **Int8** | Yes | No | No | No | No |
| **Int16** | Yes | No | No | No | No |
| **Int32** | Yes | No | No | No | No |
| **Int64** | Yes | No | No | No | No |
| **Uint8** | Yes | No | No | No | No |
| **Uint16** | Yes | No | No | No | No |
| **Uint32** | Yes | No | No | No | No |
| **Uint64** | Yes | No | No | No | No |
| **Float** | Yes | No | No | No | No |
| **Double** | Yes | No | No | No | No |
| **Decimal** | Yes | No | No | No | No |
| **String** | — | Yes | Yes | Yes | Yes |
| **Utf8** | Yes | — | No | No | No |
| **Json** | Yes | Yes | — | No | No |
| **Yson** | Yes1 | No | No | No | No |
| **Uuid** | Yes | Yes | No | No | — |
| **Date** | Yes | Yes | No | No | No |
| **Datetime** | Yes | Yes | No | No | No |
| **Timestamp** | Yes | Yes | No | No | No |
| **Interval** | Yes | Yes | No | No | No |
| **Date32** | Yes | Yes | No | No | No |
| **Datetime64** | Yes | Yes | No | No | No |
| **Timestamp64** | Yes | Yes | No | No | No |
| **Interval64** | Yes | Yes | No | No | No |
1 Using the built-in function [Yson::ConvertTo](https://ytsaurus.tech/docs/en/yql/udf/list/yson.md#ysonconvertto).
#### Examples
```yql
SELECT
CAST("12345" AS Double), -- 12345.0
CAST(1.2345 AS Uint8), -- 1
CAST(12345 AS String), -- "12345"
CAST("1.2345" AS Decimal(5, 2)), -- 1.23
CAST("xyz" AS Uint64) IS NULL, -- true, because it failed
CAST(-1 AS Uint16) IS NULL, -- true, negative to unsigned
CAST([-1, 0, 1] AS List), -- [null, 0, 1]
--Optional item type: failed item to null.
CAST(["3.14", "bad", "42"] AS List), -- [3.14, 42]
--Non-optional item type: failed item deleted.
CAST(255 AS Uint8), -- 255
CAST(256 AS Uint8) IS NULL -- true, out of range
```
### Implicit casting {#implicit-cast}
Implicit type casting that occurs in basic operations (`+`, `-`, `*`, `/`, `%`) between different data types. The table cells specify the operation result type, if the operation is possible:
#### Numeric types
If the numeric types don't match, both arguments are BitCast to the result type before performing the operation.
| Type | Int8 | Int16 | Int32 | Int64 | Uint8 | Uint16 | Uint32 | Uint64 | Float | Double |
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
| **Int8** | — | `Int16` | `Int32` | `Int64` | `Int8` | `Uint16` | `Uint32` | `Uint64` | `Float` | `Double` |
| **Int16** | `Int16` | — | `Int32` | `Int64` | `Int16` | `Int16` | `Uint32` | `Uint64` | `Float` | `Double` |
| **Int32** | `Int32` | `Int32` | — | `Int64` | `Int32` | `Int32` | `Int32` | `Uint64` | `Float` | `Double` |
| **Int64** | `Int64` | `Int64` | `Int64` | — | `Int64` | `Int64` | `Int64` | `Int64` | `Float` | `Double` |
| **Uint8** | `Int8` | `Int16` | `Int32` | `Int64` | — | `Uint16` | `Uint32` | `Uint64` | `Float` | `Double` |
| **Uint16** | `Uint16` | `Int16` | `Int32` | `Int64` | `Uint16` | — | `Uint32` | `Uint64` | `Float` | `Double` |
| **Uint32** | `Uint32` | `Uint32` | `Int32` | `Int64` | `Uint32` | `Uint32` | — | `Uint64` | `Float` | `Double` |
| **Uint64** | `Uint64` | `Uint64` | `Uint64` | `Int64` | `Uint64` | `Uint64` | `Uint64` | — | `Float` | `Double` |
| **Float** | `Float` | `Float` | `Float` | `Float` | `Float` | `Float` | `Float` | `Float` | — | `Double` |
| **Double** | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | `Double` | — |
#### Date and time types
##### Basic types
| Type | Date | Datetime | Timestamp | Interval | TzDate | TzDatetime | TzTimestamp |
--- | --- | --- | --- | --- | --- | --- | ---
| **Date** | — | `DateTime` | `Timestamp` | — | `TzDate` | `TzDatetime` | `TzTimestamp` |
| **Datetime** | — | — | `Timestamp` | — | — | `TzDatetime` | `TzTimestamp` |
| **Timestamp** | — | — | — | — | — | — | `TzTimestamp` |
| **Interval** | — | — | — | — | — | — | — |
| **TzDate** | — | — | — | — | — | `TzDatetime` | `TzTimestamp` |
| **TzDatetime** | — | — | — | — | — | — | `TzTimestamp` |
| **TzTimestamp** | — | — | — | — | — | — | — |
| **Date32** | — | — | — | — | — | — | — |
| **Datetime64** | — | — | — | — | — | — | — |
| **Timestamp64** | — | — | — | — | — | — | — |
| **Interval64** | — | — | — | — | — | — | — |
| **TzDate32** | — | — | — | — | — | — | — |
| **TzDatetime64** | — | — | — | — | — | — | — |
| **TzTimestamp64** | — | — | — | — | — | — | — |
##### Extended types
| Type | Date32 | Datetime64 | Timestamp64 | Interval64 | TzDate32 | TzDatetime64 | TzTimestamp64 |
--- | --- | --- | --- | --- | --- | --- | ---
| **Date** | `Date32` | `DateTime64` | `Timestamp64` | — | `TzDate32` | `TzDatetime64` | `TzTimestamp64` |
| **Datetime** | — | `Datetime64` | `Timestamp64` | — | — | `TzDatetime64` | `TzTimestamp64` |
| **Timestamp** | — | — | `Timestamp64` | — | — | — | `TzTimestamp64` |
| **Interval** | — | — | — | — | — | — | — |
| **TzDate** | — | — | — | — | `TzDate32` | `TzDatetime64` | `TzTimestamp64` |
| **TzDatetime** | — | — | — | — | — | `TzDatetime64` | `TzTimestamp64` |
| **TzTimestamp** | — | — | — | — | — | — | `TzTimestamp64` |
| **Date32** | — | `DateTime64` | `Timestamp64` | — | `TzDate32` | `TzDatetime64` | `TzTimestamp64` |
| **Datetime64** | — | — | `Timestamp64` | — | — | `TzDatetime64` | `TzTimestamp64` |
| **Timestamp64** | — | — | — | — | — | — | `TzTimestamp64` |
| **Interval64** | — | — | — | — | — | — | — |
| **TzDate32** | — | — | — | — | — | `TzDatetime64` | `TzTimestamp64` |
| **TzDatetime64** | — | — | — | — | — | — | `TzTimestamp64` |
| **TzTimestamp64** | — | — | — | — | — | — | — |