Primitive data types

The terms "simple", "primitive", and "elementary" data types are used synonymously.

Numeric types

Type	Description	Notes
`Bool`	Boolean value.
`Int8`	A signed integer. Acceptable values: from -2⁷ to 2⁷–1.
`Int16`	A signed integer. Acceptable values: from –2¹⁵ to 2¹⁵–1.
`Int32`	A signed integer. Acceptable values: from –2³¹ to 2³¹–1.
`Int64`	A signed integer. Acceptable values: from –2⁶³ to 2⁶³–1.
`Uint8`	Unsigned integer. Permitted values: from 0 to 2⁸–1.
`Uint16`	Unsigned integer. Permitted values: from 0 to 2¹⁶–1.
`Uint32`	Unsigned integer. Permitted values: from 0 to 2³²–1.
`Uint64`	Unsigned integer. Permitted values: from 0 to 2⁶⁴–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×10¹²⁶–1, negative numbers from -1×10¹²⁶–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

Type	Description	Notes
`String`	A string that can contain any binary data
`Utf8`	UTF-8-coded text.
`Json`	JSON represented as text
`JsonDocument`	JSON in an indexed binary representation
`Yson`	YSON in textual or binary presentation
`Uuid`	UUID 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, 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.

Warning

Double type is used to store (JSON Number) numerical values in JsonDocument and perform arithmetic operations over them in JSON API. Precision might be lost when non-standard representations of numbers are used in the source JSON document.

Date and time

Type	Description	Notes
`Date`	Date, precision to the day	Range of values for all temporal types except `Interval`: From 00:00 01.01.1970 to 00:00 01.01.2106. Internal `Date` 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
`TzDatetime`	Date/time with time zone label, precision to the second
`TzTimestamp`	Date/time with time zone label, precision to the microsecond

Supporting types with a time zone label

Time zone label for the TzDate, TzDatetime, TzTimestamp types is an attribute that is used:

During (CAST, DateTime::Parse, DateTime::Format) converting into a string and from a string.
In DateTime::Split, the time zone component appears in Resource<TM>.

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:

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

Explicit casting

Explicit casting using CAST:

Casting to numeric types

Type	Bool	Int8	Int16	Int32	Int64	Uint8	Uint16	Uint32	Uint64	Float	Double	Decimal
Bool	—	Yes¹	Yes¹	Yes¹	Yes¹	Yes¹	Yes¹	Yes¹	Yes¹	Yes¹	Yes¹	No
Int8	Yes²	—	Yes	Yes	Yes	Yes³	Yes³	Yes³	Yes³	Yes	Yes	Yes
Int16	Yes²	Yes⁴	—	Yes	Yes	Yes^3,4	Yes³	Yes³	Yes³	Yes	Yes	Yes
Int32	Yes²	Yes⁴	Yes⁴	—	Yes	Yes^3,4	Yes^3,4	Yes³	Yes³	Yes	Yes	Yes
Int64	Yes²	Yes⁴	Yes⁴	Yes⁴	—	Yes^3,4	Yes^3,4	Yes^3,4	Yes³	Yes	Yes	Yes
Uint8	Yes²	Yes⁴	Yes	Yes	Yes	—	Yes	Yes	Yes	Yes	Yes	Yes
Uint16	Yes²	Yes⁴	Yes⁴	Yes	Yes	Yes⁴	—	Yes	Yes	Yes	Yes	Yes
Uint32	Yes²	Yes⁴	Yes⁴	Yes⁴	Yes	Yes⁴	Yes⁴	—	Yes	Yes	Yes	Yes
Uint64	Yes²	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes⁴	—	Yes	Yes	Yes
Float	Yes²	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes^3,4	Yes^3,4	Yes^3,4	Yes^3,4	—	Yes	No
Double	Yes²	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes^3,4	Yes^3,4	Yes^3,4	Yes^3,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	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	Yes⁵	No
Uuid	No	No	No	No	No	No	No	No	No	No	No	No
Date	No	Yes⁴	Yes⁴	Yes	Yes	Yes⁴	Yes	Yes	Yes	Yes	Yes	Yes
Datetime	No	Yes⁴	Yes⁴	Yes⁴	Yes	Yes⁴	Yes⁴	Yes	Yes	Yes	Yes	No
Timestamp	No	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes⁴	Yes	Yes	Yes	No
Interval	No	Yes⁴	Yes⁴	Yes⁴	Yes	Yes^3,4	Yes^3,4	Yes^3,4	Yes³	Yes	Yes	No

¹ True is converted to 1 and False to 0.
² Any value other than 0 is converted to True, 0 is converted to False.
³ Possible only in the case of a non-negative value.
⁴ Possible only in the case of a value falling within the allowed range.
⁵ Using the built-in function Yson::ConvertTo.

Converting to date and time data 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	—

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	Yes¹	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

¹ Using the built-in function Yson::ConvertTo.

Examples

    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<Uint8?>),             -- [null, 0, 1]
            --Optional item type: failed item to null.
        CAST(["3.14", "bad", "42"] AS List<Float>),   -- [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 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

Type	Date	Datetime	Timestamp	Interval	TzDate	TzDatetime	TzTimestamp
Date	—	—	—	`Date`	—	—	—
Datetime	—	—	—	`Datetime`	—	—	—
Timestamp	—	—	—	`Timestamp`	—	—	—
Interval	`Date`	`Datetime`	`Timestamp`	—	`TzDate`	`TzDatetime`	`TzTimestamp`
TzDate	—	—	—	`TzDate`	—	—	—
TzDatetime	—	—	—	`TzDatetime`	—	—	—
TzTimestamp	—	—	—	`TzTimestamp`	—	—	—

Overview

Optional