Type Conversion Functions

Common Issues with Data Conversion

ClickHouse generally uses the same behavior as C++ programs.

to<type> functions and cast behave differently in some cases, for example in case of LowCardinality: cast removes LowCardinality trait to<type> functions don't. The same with Nullable, this behaviour is not compatible with SQL standard, and it can be changed using cast_keep_nullable setting.

Note

Be aware of potential data loss if values of a datatype are converted to a smaller datatype (for example from Int64 to Int32) or between incompatible datatypes (for example from String to Int). Make sure to check carefully if the result is as expected.

Example:

toBool

Converts an input value to a value of type Bool. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string. Expression.

Supported arguments:

Values of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.
Strings true or false (case-insensitive).

Returned value

Returns true or false based on evaluation of the argument. Bool.

Example

Query:

Result:

toInt8

Converts an input value to a value of type Int8. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt8('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int8, overflow or underflow of the result occurs. This is not considered an error. For example: SELECT toInt8(128) == -128;.

Returned value

8-bit integer value. Int8.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt8OrZero.
toInt8OrNull.
toInt8OrDefault.

toInt8OrZero

Like toInt8, this function converts an input value to a value of type Int8 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of ordinary Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt8OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int8, overflow or underflow of the result occurs. This is not considered an error.

Returned value

8-bit integer value if successful, otherwise 0. Int8.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt8.
toInt8OrNull.
toInt8OrDefault.

toInt8OrNull

Like toInt8, this function converts an input value to a value of type Int8 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt8OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int8, overflow or underflow of the result occurs. This is not considered an error.

Returned value

8-bit integer value if successful, otherwise NULL. Int8 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt8.
toInt8OrZero.
toInt8OrDefault.

toInt8OrDefault

Like toInt8, this function converts an input value to a value of type Int8 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Int8 is unsuccessful. Int8.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt8OrDefault('0xc0fe', CAST('-1', 'Int8'));.

Note

If the input value cannot be represented within the bounds of Int8, overflow or underflow of the result occurs. This is not considered an error.

Returned value

8-bit integer value if successful, otherwise returns the default value if passed or 0 if not. Int8.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toInt8.
toInt8OrZero.
toInt8OrNull.

toInt16

Converts an input value to a value of type Int16. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt16('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int16, overflow or underflow of the result occurs. This is not considered an error. For example: SELECT toInt16(32768) == -32768;.

Returned value

16-bit integer value. Int16.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt16OrZero.
toInt16OrNull.
toInt16OrDefault.

toInt16OrZero

Like toInt16, this function converts an input value to a value of type Int16 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt16OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int16, overflow or underflow of the result occurs. This is not considered as an error.

Returned value

16-bit integer value if successful, otherwise 0. Int16.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt16.
toInt16OrNull.
toInt16OrDefault.

toInt16OrNull

Like toInt16, this function converts an input value to a value of type Int16 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt16OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int16, overflow or underflow of the result occurs. This is not considered an error.

Returned value

16-bit integer value if successful, otherwise NULL. Int16 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt16.
toInt16OrZero.
toInt16OrDefault.

toInt16OrDefault

Like toInt16, this function converts an input value to a value of type Int16 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Int16 is unsuccessful. Int16.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt16OrDefault('0xc0fe', CAST('-1', 'Int16'));.

Note

If the input value cannot be represented within the bounds of Int16, overflow or underflow of the result occurs. This is not considered an error.

Returned value

16-bit integer value if successful, otherwise returns the default value if passed or 0 if not. Int16.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toInt16.
toInt16OrZero.
toInt16OrNull.

toInt32

Converts an input value to a value of type Int32. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt32('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int32, the result over or under flows. This is not considered an error. For example: SELECT toInt32(2147483648) == -2147483648;

Returned value

32-bit integer value. Int32.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt32OrZero.
toInt32OrNull.
toInt32OrDefault.

toInt32OrZero

Like toInt32, this function converts an input value to a value of type Int32 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt32OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int32, overflow or underflow of the result occurs. This is not considered an error.

Returned value

32-bit integer value if successful, otherwise 0. Int32

Note

The function uses rounding towards zero, meaning it truncate fractional digits of numbers.

Example

Query:

Result:

See also

toInt32.
toInt32OrNull.
toInt32OrDefault.

toInt32OrNull

Like toInt32, this function converts an input value to a value of type Int32 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt32OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int32, overflow or underflow of the result occurs. This is not considered an error.

Returned value

32-bit integer value if successful, otherwise NULL. Int32 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt32.
toInt32OrZero.
toInt32OrDefault.

toInt32OrDefault

Like toInt32, this function converts an input value to a value of type Int32 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Int32 is unsuccessful. Int32.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt32OrDefault('0xc0fe', CAST('-1', 'Int32'));.

Note

If the input value cannot be represented within the bounds of Int32, overflow or underflow of the result occurs. This is not considered an error.

Returned value

32-bit integer value if successful, otherwise returns the default value if passed or 0 if not. Int32.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toInt32.
toInt32OrZero.
toInt32OrNull.

toInt64

Converts an input value to a value of type Int64. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported types:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt64('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int64, the result over or under flows. This is not considered an error. For example: SELECT toInt64(9223372036854775808) == -9223372036854775808;

Returned value

64-bit integer value. Int64.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt64OrZero.
toInt64OrNull.
toInt64OrDefault.

toInt64OrZero

Like toInt64, this function converts an input value to a value of type Int64 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt64OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int64, overflow or underflow of the result occurs. This is not considered an error.

Returned value

64-bit integer value if successful, otherwise 0. Int64.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt64.
toInt64OrNull.
toInt64OrDefault.

toInt64OrNull

Like toInt64, this function converts an input value to a value of type Int64 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. Expression / String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt64OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int64, overflow or underflow of the result occurs. This is not considered an error.

Returned value

64-bit integer value if successful, otherwise NULL. Int64 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt64.
toInt64OrZero.
toInt64OrDefault.

toInt64OrDefault

Like toInt64, this function converts an input value to a value of type Int64 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Int64 is unsuccessful. Int64.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt64OrDefault('0xc0fe', CAST('-1', 'Int64'));.

Note

If the input value cannot be represented within the bounds of Int64, overflow or underflow of the result occurs. This is not considered an error.

Returned value

64-bit integer value if successful, otherwise returns the default value if passed or 0 if not. Int64.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toInt64.
toInt64OrZero.
toInt64OrNull.

toInt128

Converts an input value to a value of type Int128. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt128('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int128, the result over or under flows. This is not considered an error.

Returned value

128-bit integer value. Int128.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt128OrZero.
toInt128OrNull.
toInt128OrDefault.

toInt128OrZero

Like toInt128, this function converts an input value to a value of type Int128 but returns 0 in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt128OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int128, overflow or underflow of the result occurs. This is not considered an error.

Returned value

128-bit integer value if successful, otherwise 0. Int128.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt128.
toInt128OrNull.
toInt128OrDefault.

toInt128OrNull

Like toInt128, this function converts an input value to a value of type Int128 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. Expression / String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt128OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int128, overflow or underflow of the result occurs. This is not considered an error.

Returned value

128-bit integer value if successful, otherwise NULL. Int128 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt128.
toInt128OrZero.
toInt128OrDefault.

toInt128OrDefault

Like toInt128, this function converts an input value to a value of type Int128 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Int128 is unsuccessful. Int128.

Supported arguments:

(U)Int8/16/32/64/128/256.
Float32/64.
String representations of (U)Int8/16/32/128/256.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt128OrDefault('0xc0fe', CAST('-1', 'Int128'));.

Note

If the input value cannot be represented within the bounds of Int128, overflow or underflow of the result occurs. This is not considered an error.

Returned value

128-bit integer value if successful, otherwise returns the default value if passed or 0 if not. Int128.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toInt128.
toInt128OrZero.
toInt128OrNull.

toInt256

Converts an input value to a value of type Int256. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt256('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int256, the result over or under flows. This is not considered an error.

Returned value

256-bit integer value. Int256.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt256OrZero.
toInt256OrNull.
toInt256OrDefault.

toInt256OrZero

Like toInt256, this function converts an input value to a value of type Int256 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt256OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int256, overflow or underflow of the result occurs. This is not considered an error.

Returned value

256-bit integer value if successful, otherwise 0. Int256.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt256.
toInt256OrNull.
toInt256OrDefault.

toInt256OrNull

Like toInt256, this function converts an input value to a value of type Int256 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toInt256OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of Int256, overflow or underflow of the result occurs. This is not considered an error.

Returned value

256-bit integer value if successful, otherwise NULL. Int256 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toInt256.
toInt256OrZero.
toInt256OrDefault.

toInt256OrDefault

Like toInt256, this function converts an input value to a value of type Int256 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Int256 is unsuccessful. Int256.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf
String representations of binary and hexadecimal values, e.g. SELECT toInt256OrDefault('0xc0fe', CAST('-1', 'Int256'));

Note

If the input value cannot be represented within the bounds of Int256, overflow or underflow of the result occurs. This is not considered an error.

Returned value

256-bit integer value if successful, otherwise returns the default value if passed or 0 if not. Int256.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toInt256.
toInt256OrZero.
toInt256OrNull.

toUInt8

Converts an input value to a value of type UInt8. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt8('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt8, overflow or underflow of the result occurs. This is not considered an error. For example: SELECT toUInt8(256) == 0;.

Returned value

8-bit unsigned integer value. UInt8.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt8OrZero.
toUInt8OrNull.
toUInt8OrDefault.

toUInt8OrZero

Like toUInt8, this function converts an input value to a value of type UInt8 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of ordinary Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt8OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt8, overflow or underflow of the result occurs. This is not considered an error.

Returned value

8-bit unsigned integer value if successful, otherwise 0. UInt8.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt8.
toUInt8OrNull.
toUInt8OrDefault.

toUInt8OrNull

Like toUInt8, this function converts an input value to a value of type UInt8 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt8OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt8, overflow or underflow of the result occurs. This is not considered an error.

Returned value

8-bit unsigned integer value if successful, otherwise NULL. UInt8 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt8.
toUInt8OrZero.
toUInt8OrDefault.

toUInt8OrDefault

Like toUInt8, this function converts an input value to a value of type UInt8 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type UInt8 is unsuccessful. UInt8.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt8OrDefault('0xc0fe', CAST('0', 'UInt8'));.

Note

If the input value cannot be represented within the bounds of UInt8, overflow or underflow of the result occurs. This is not considered an error.

Returned value

8-bit unsigned integer value if successful, otherwise returns the default value if passed or 0 if not. UInt8.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toUInt8.
toUInt8OrZero.
toUInt8OrNull.

toUInt16

Converts an input value to a value of type UInt16. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt16('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt16, overflow or underflow of the result occurs. This is not considered an error. For example: SELECT toUInt16(65536) == 0;.

Returned value

16-bit unsigned integer value. UInt16.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt16OrZero.
toUInt16OrNull.
toUInt16OrDefault.

toUInt16OrZero

Like toUInt16, this function converts an input value to a value of type UInt16 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt16OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt16, overflow or underflow of the result occurs. This is not considered as an error.

Returned value

16-bit unsigned integer value if successful, otherwise 0. UInt16.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt16.
toUInt16OrNull.
toUInt16OrDefault.

toUInt16OrNull

Like toUInt16, this function converts an input value to a value of type UInt16 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt16OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt16, overflow or underflow of the result occurs. This is not considered an error.

Returned value

16-bit unsigned integer value if successful, otherwise NULL. UInt16 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt16.
toUInt16OrZero.
toUInt16OrDefault.

toUInt16OrDefault

Like toUInt16, this function converts an input value to a value of type UInt16 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type UInt16 is unsuccessful. UInt16.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt16OrDefault('0xc0fe', CAST('0', 'UInt16'));.

Note

If the input value cannot be represented within the bounds of UInt16, overflow or underflow of the result occurs. This is not considered an error.

Returned value

16-bit unsigned integer value if successful, otherwise returns the default value if passed or 0 if not. UInt16.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toUInt16.
toUInt16OrZero.
toUInt16OrNull.

toUInt32

Converts an input value to a value of type UInt32. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt32('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt32, the result over or under flows. This is not considered an error. For example: SELECT toUInt32(4294967296) == 0;

Returned value

32-bit unsigned integer value. UInt32.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt32OrZero.
toUInt32OrNull.
toUInt32OrDefault.

toUInt32OrZero

Like toUInt32, this function converts an input value to a value of type UInt32 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt32OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt32, overflow or underflow of the result occurs. This is not considered an error.

Returned value

32-bit unsigned integer value if successful, otherwise 0. UInt32

Note

The function uses rounding towards zero , meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt32.
toUInt32OrNull.
toUInt32OrDefault.

toUInt32OrNull

Like toUInt32, this function converts an input value to a value of type UInt32 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt32OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt32, overflow or underflow of the result occurs. This is not considered an error.

Returned value

32-bit unsigned integer value if successful, otherwise NULL. UInt32 / NULL.

Note

The function uses rounding towards zero , meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt32.
toUInt32OrZero.
toUInt32OrDefault.

toUInt32OrDefault

Like toUInt32, this function converts an input value to a value of type UInt32 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type UInt32 is unsuccessful. UInt32.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt32OrDefault('0xc0fe', CAST('0', 'UInt32'));.

Note

If the input value cannot be represented within the bounds of UInt32, overflow or underflow of the result occurs. This is not considered an error.

Returned value

32-bit unsigned integer value if successful, otherwise returns the default value if passed or 0 if not. UInt32.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toUInt32.
toUInt32OrZero.
toUInt32OrNull.

toUInt64

Converts an input value to a value of type UInt64. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported types:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt64('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt64, the result over or under flows. This is not considered an error. For example: SELECT toUInt64(18446744073709551616) == 0;

Returned value

64-bit unsigned integer value. UInt64.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt64OrZero.
toUInt64OrNull.
toUInt64OrDefault.

toUInt64OrZero

Like toUInt64, this function converts an input value to a value of type UInt64 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt64OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt64, overflow or underflow of the result occurs. This is not considered an error.

Returned value

64-bit unsigned integer value if successful, otherwise 0. UInt64.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt64.
toUInt64OrNull.
toUInt64OrDefault.

toUInt64OrNull

Like toUInt64, this function converts an input value to a value of type UInt64 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. Expression / String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt64OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt64, overflow or underflow of the result occurs. This is not considered an error.

Returned value

64-bit unsigned integer value if successful, otherwise NULL. UInt64 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt64.
toUInt64OrZero.
toUInt64OrDefault.

toUInt64OrDefault

Like toUInt64, this function converts an input value to a value of type UInt64 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
defauult (optional) — The default value to return if parsing to type UInt64 is unsuccessful. UInt64.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt64OrDefault('0xc0fe', CAST('0', 'UInt64'));.

Note

If the input value cannot be represented within the bounds of UInt64, overflow or underflow of the result occurs. This is not considered an error.

Returned value

64-bit unsigned integer value if successful, otherwise returns the default value if passed or 0 if not. UInt64.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toUInt64.
toUInt64OrZero.
toUInt64OrNull.

toUInt128

Converts an input value to a value of type UInt128. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt128('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt128, the result over or under flows. This is not considered an error.

Returned value

128-bit unsigned integer value. UInt128.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt128OrZero.
toUInt128OrNull.
toUInt128OrDefault.

toUInt128OrZero

Like toUInt128, this function converts an input value to a value of type UInt128 but returns 0 in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt128OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt128, overflow or underflow of the result occurs. This is not considered an error.

Returned value

128-bit unsigned integer value if successful, otherwise 0. UInt128.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt128.
toUInt128OrNull.
toUInt128OrDefault.

toUInt128OrNull

Like toUInt128, this function converts an input value to a value of type UInt128 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. Expression / String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt128OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt128, overflow or underflow of the result occurs. This is not considered an error.

Returned value

128-bit unsigned integer value if successful, otherwise NULL. UInt128 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt128.
toUInt128OrZero.
toUInt128OrDefault.

toUInt128OrDefault

Like toUInt128, this function converts an input value to a value of type UInt128 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type UInt128 is unsuccessful. UInt128.

Supported arguments:

(U)Int8/16/32/64/128/256.
Float32/64.
String representations of (U)Int8/16/32/128/256.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt128OrDefault('0xc0fe', CAST('0', 'UInt128'));.

Note

If the input value cannot be represented within the bounds of UInt128, overflow or underflow of the result occurs. This is not considered an error.

Returned value

128-bit unsigned integer value if successful, otherwise returns the default value if passed or 0 if not. UInt128.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toUInt128.
toUInt128OrZero.
toUInt128OrNull.

toUInt256

Converts an input value to a value of type UInt256. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt256('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt256, the result over or under flows. This is not considered an error.

Returned value

256-bit unsigned integer value. Int256.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt256OrZero.
toUInt256OrNull.
toUInt256OrDefault.

toUInt256OrZero

Like toUInt256, this function converts an input value to a value of type UInt256 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return 0):

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt256OrZero('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt256, overflow or underflow of the result occurs. This is not considered an error.

Returned value

256-bit unsigned integer value if successful, otherwise 0. UInt256.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt256.
toUInt256OrNull.
toUInt256OrDefault.

toUInt256OrNull

Like toUInt256, this function converts an input value to a value of type UInt256 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return \N)

String representations of Float32/64 values, including NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toUInt256OrNull('0xc0fe');.

Note

If the input value cannot be represented within the bounds of UInt256, overflow or underflow of the result occurs. This is not considered an error.

Returned value

256-bit unsigned integer value if successful, otherwise NULL. UInt256 / NULL.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

Example

Query:

Result:

See also

toUInt256.
toUInt256OrZero.
toUInt256OrDefault.

toUInt256OrDefault

Like toUInt256, this function converts an input value to a value of type UInt256 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type UInt256 is unsuccessful. UInt256.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values of type Float32/64.

Arguments for which the default value is returned:

String representations of Float32/64 values, including NaN and Inf
String representations of binary and hexadecimal values, e.g. SELECT toUInt256OrDefault('0xc0fe', CAST('0', 'UInt256'));

Note

If the input value cannot be represented within the bounds of UInt256, overflow or underflow of the result occurs. This is not considered an error.

Returned value

256-bit unsigned integer value if successful, otherwise returns the default value if passed or 0 if not. UInt256.

Note

The function uses rounding towards zero, meaning it truncates fractional digits of numbers.
The default value type should be the same as the cast type.

Example

Query:

Result:

See also

toUInt256.
toUInt256OrZero.
toUInt256OrNull.

toFloat32

Converts an input value to a value of type Float32. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values of type (U)Int8/16/32/64/128/256.
String representations of (U)Int8/16/32/128/256.
Values of type Float32/64, including NaN and Inf.
String representations of Float32/64, including NaN and Inf (case-insensitive).

Unsupported arguments:

String representations of binary and hexadecimal values, e.g. SELECT toFloat32('0xc0fe');.

Returned value

32-bit floating point value. Float32.

Example

Query:

Result:

See also

toFloat32OrZero.
toFloat32OrNull.
toFloat32OrDefault.

toFloat32OrZero

Like toFloat32, this function converts an input value to a value of type Float32 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256, Float32/64.

Unsupported arguments (return 0):

String representations of binary and hexadecimal values, e.g. SELECT toFloat32OrZero('0xc0fe');.

Returned value

32-bit Float value if successful, otherwise 0. Float32.

Example

Query:

Result:

See also

toFloat32.
toFloat32OrNull.
toFloat32OrDefault.

toFloat32OrNull

Like toFloat32, this function converts an input value to a value of type Float32 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256, Float32/64.

Unsupported arguments (return \N):

String representations of binary and hexadecimal values, e.g. SELECT toFloat32OrNull('0xc0fe');.

Returned value

32-bit Float value if successful, otherwise \N. Float32.

Example

Query:

Result:

See also

toFloat32.
toFloat32OrZero.
toFloat32OrDefault.

toFloat32OrDefault

Like toFloat32, this function converts an input value to a value of type Float32 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Float32 is unsuccessful. Float32.

Supported arguments:

Values of type (U)Int8/16/32/64/128/256.
String representations of (U)Int8/16/32/128/256.
Values of type Float32/64, including NaN and Inf.
String representations of Float32/64, including NaN and Inf (case-insensitive).

Arguments for which the default value is returned:

String representations of binary and hexadecimal values, e.g. SELECT toFloat32OrDefault('0xc0fe', CAST('0', 'Float32'));.

Returned value

32-bit Float value if successful, otherwise returns the default value if passed or 0 if not. Float32.

Example

Query:

Result:

See also

toFloat32.
toFloat32OrZero.
toFloat32OrNull.

toFloat64

Converts an input value to a value of type Float64. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values of type (U)Int8/16/32/64/128/256.
String representations of (U)Int8/16/32/128/256.
Values of type Float32/64, including NaN and Inf.
String representations of type Float32/64, including NaN and Inf (case-insensitive).

Unsupported arguments:

String representations of binary and hexadecimal values, e.g. SELECT toFloat64('0xc0fe');.

Returned value

64-bit floating point value. Float64.

Example

Query:

Result:

See also

toFloat64OrZero.
toFloat64OrNull.
toFloat64OrDefault.

toFloat64OrZero

Like toFloat64, this function converts an input value to a value of type Float64 but returns 0 in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256, Float32/64.

Unsupported arguments (return 0):

String representations of binary and hexadecimal values, e.g. SELECT toFloat64OrZero('0xc0fe');.

Returned value

64-bit Float value if successful, otherwise 0. Float64.

Example

Query:

Result:

See also

toFloat64.
toFloat64OrNull.
toFloat64OrDefault.

toFloat64OrNull

Like toFloat64, this function converts an input value to a value of type Float64 but returns NULL in case of an error.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of (U)Int8/16/32/128/256, Float32/64.

Unsupported arguments (return \N):

String representations of binary and hexadecimal values, e.g. SELECT toFloat64OrNull('0xc0fe');.

Returned value

64-bit Float value if successful, otherwise \N. Float64.

Example

Query:

Result:

See also

toFloat64.
toFloat64OrZero.
toFloat64OrDefault.

toFloat64OrDefault

Like toFloat64, this function converts an input value to a value of type Float64 but returns the default value in case of an error. If no default value is passed then 0 is returned in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression / String.
default (optional) — The default value to return if parsing to type Float64 is unsuccessful. Float64.

Supported arguments:

Values of type (U)Int8/16/32/64/128/256.
String representations of (U)Int8/16/32/128/256.
Values of type Float32/64, including NaN and Inf.
String representations of Float32/64, including NaN and Inf (case-insensitive).

Arguments for which the default value is returned:

String representations of binary and hexadecimal values, e.g. SELECT toFloat64OrDefault('0xc0fe', CAST('0', 'Float64'));.

Returned value

64-bit Float value if successful, otherwise returns the default value if passed or 0 if not. Float64.

Example

Query:

Result:

See also

toFloat64.
toFloat64OrZero.
toFloat64OrNull.

toBFloat16

Converts an input value to a value of type BFloat16. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.

Supported arguments:

Values of type (U)Int8/16/32/64/128/256.
String representations of (U)Int8/16/32/128/256.
Values of type Float32/64, including NaN and Inf.
String representations of Float32/64, including NaN and Inf (case-insensitive).

Returned value

16-bit brain-float value. BFloat16.

Example

See also

toBFloat16OrZero.
toBFloat16OrNull.

toBFloat16OrZero

Converts a String input value to a value of type BFloat16. If the string does not represent a floating point value, the function returns zero.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of numeric values.

Unsupported arguments (return 0):

String representations of binary and hexadecimal values.
Numeric values.

Returned value

16-bit brain-float value, otherwise 0. BFloat16.

Note

The function allows a silent loss of precision while converting from the string representation.

Example

See also

toBFloat16.
toBFloat16OrNull.

toBFloat16OrNull

Converts a String input value to a value of type BFloat16 but if the string does not represent a floating point value, the function returns NULL.

Syntax

Arguments

x — A String representation of a number. String.

Supported arguments:

String representations of numeric values.

Unsupported arguments (return NULL):

String representations of binary and hexadecimal values.
Numeric values.

Returned value

16-bit brain-float value, otherwise NULL (\N). BFloat16.

Note

The function allows a silent loss of precision while converting from the string representation.

Example

See also

toBFloat16.
toBFloat16OrZero.

toDate

Converts the argument to Date data type.

If the argument is DateTime or DateTime64, it truncates it and leaves the date component of the DateTime:

If the argument is a String, it is parsed as Date or DateTime. If it was parsed as DateTime, the date component is being used:

If the argument is a number and looks like a UNIX timestamp (is greater than 65535), it is interpreted as a DateTime, then truncated to Date in the current timezone. The timezone argument can be specified as a second argument of the function. The truncation to Date depends on the timezone:

The example above demonstrates how the same UNIX timestamp can be interpreted as different dates in different time zones.

If the argument is a number and it is smaller than 65536, it is interpreted as the number of days since 1970-01-01 (the first UNIX day) and converted to Date. It corresponds to the internal numeric representation of the Date data type. Example:

This conversion does not depend on timezones.

If the argument does not fit in the range of the Date type, it results in an implementation-defined behavior, that can saturate to the maximum supported date or overflow:

The function toDate can be also written in alternative forms:

toDateOrZero

The same as toDate but returns lower boundary of Date if an invalid argument is received. Only String argument is supported.

Example

Query:

Result:

toDateOrNull

The same as toDate but returns NULL if an invalid argument is received. Only String argument is supported.

Example

Query:

Result:

toDateOrDefault

Like toDate but if unsuccessful, returns a default value which is either the second argument (if specified), or otherwise the lower boundary of Date.

Syntax

Example

Query:

Result:

toDateTime

Converts an input value to DateTime.

Syntax

Arguments

expr — The value. String, Int, Date or DateTime.
time_zone — Time zone. String.

Note

If expr is a number, it is interpreted as the number of seconds since the beginning of the Unix Epoch (as Unix timestamp). If expr is a String, it may be interpreted as a Unix timestamp or as a string representation of date / date with time. Thus, parsing of short numbers' string representations (up to 4 digits) is explicitly disabled due to ambiguity, e.g. a string '1999' may be both a year (an incomplete string representation of Date / DateTime) or a unix timestamp. Longer numeric strings are allowed.

Returned value

A date time. DateTime

Example

Query:

Result:

toDateTimeOrZero

The same as toDateTime but returns lower boundary of DateTime if an invalid argument is received. Only String argument is supported.

Example

Query:

Result:

toDateTimeOrNull

The same as toDateTime but returns NULL if an invalid argument is received. Only String argument is supported.

Example

Query:

Result:

toDateTimeOrDefault

Like toDateTime but if unsuccessful, returns a default value which is either the third argument (if specified), or otherwise the lower boundary of DateTime.

Syntax

Example

Query:

Result:

toDate32

Converts the argument to the Date32 data type. If the value is outside the range, toDate32 returns the border values supported by Date32. If the argument has Date type, it's borders are taken into account.

Syntax

Arguments

expr — The value. String, UInt32 or Date.

Returned value

A calendar date. Type Date32.

Example

The value is within the range:

The value is outside the range:

With Date argument:

toDate32OrZero

The same as toDate32 but returns the min value of Date32 if an invalid argument is received.

Example

Query:

Result:

toDate32OrNull

The same as toDate32 but returns NULL if an invalid argument is received.

Example

Query:

Result:

toDate32OrDefault

Converts the argument to the Date32 data type. If the value is outside the range, toDate32OrDefault returns the lower border value supported by Date32. If the argument has Date type, it's borders are taken into account. Returns default value if an invalid argument is received.

Example

Query:

Result:

toDateTime64

Converts an input value to a value of type DateTime64.

Syntax

Arguments

expr — The value. String, UInt32, Float or DateTime.
scale - Tick size (precision): 10^-precision seconds. Valid range: [ 0 : 9 ].
timezone (optional) - Time zone of the specified datetime64 object.

Returned value

A calendar date and time of day, with sub-second precision. DateTime64.

Example

The value is within the range:

As decimal with precision:

Without the decimal point the value is still treated as Unix Timestamp in seconds:

With timezone:

toDateTime64OrZero

Like toDateTime64, this function converts an input value to a value of type DateTime64 but returns the min value of DateTime64 if an invalid argument is received.

Syntax

Arguments

expr — The value. String, UInt32, Float or DateTime.
scale - Tick size (precision): 10^-precision seconds. Valid range: [ 0 : 9 ].
timezone (optional) - Time zone of the specified DateTime64 object.

Returned value

A calendar date and time of day, with sub-second precision, otherwise the minimum value of DateTime64: 1970-01-01 01:00:00.000. DateTime64.

Example

Query:

Result:

See also

toDateTime64.
toDateTime64OrNull.
toDateTime64OrDefault.

toDateTime64OrNull

Like toDateTime64, this function converts an input value to a value of type DateTime64 but returns NULL if an invalid argument is received.

Syntax

Arguments

expr — The value. String, UInt32, Float or DateTime.
scale - Tick size (precision): 10^-precision seconds. Valid range: [ 0 : 9 ].
timezone (optional) - Time zone of the specified DateTime64 object.

Returned value

A calendar date and time of day, with sub-second precision, otherwise NULL. DateTime64/NULL.

Example

Query:

Result:

See also

toDateTime64.
toDateTime64OrZero.
toDateTime64OrDefault.

toDateTime64OrDefault

Like toDateTime64, this function converts an input value to a value of type DateTime64, but returns either the default value of DateTime64 or the provided default if an invalid argument is received.

Syntax

Arguments

expr — The value. String, UInt32, Float or DateTime.
scale - Tick size (precision): 10^-precision seconds. Valid range: [ 0 : 9 ].
timezone (optional) - Time zone of the specified DateTime64 object.
default (optional) - Default value to return if an invalid argument is received. DateTime64.

Returned value

A calendar date and time of day, with sub-second precision, otherwise the minimum value of DateTime64 or the default value if provided. DateTime64.

Example

Query:

Result:

See also

toDateTime64.
toDateTime64OrZero.
toDateTime64OrNull.

toDecimal32

Converts an input value to a value of type Decimal(9, S) with scale of S. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.
S — Scale parameter between 0 and 9, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values or string representations of type Float32/64.

Unsupported arguments:

Values or string representations of Float32/64 values NaN and Inf (case-insensitive).
String representations of binary and hexadecimal values, e.g. SELECT toDecimal32('0xc0fe', 1);.

Note

An overflow can occur if the value of expr exceeds the bounds of Decimal32: ( -1 * 10^(9 - S), 1 * 10^(9 - S) ). Excessive digits in a fraction are discarded (not rounded). Excessive digits in the integer part will lead to an exception.

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal32(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal32('1.15', 2) = 1.15

Returned value

Value of type Decimal(9, S). Decimal32(S).

Example

Query:

Result:

See also

toDecimal32OrZero.
toDecimal32OrNull.
toDecimal32OrDefault.

toDecimal32OrZero

Like toDecimal32, this function converts an input value to a value of type Decimal(9, S) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 9, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal32OrZero('0xc0fe', 1);.

Note

Returned value

Value of type Decimal(9, S) if successful, otherwise 0 with S decimal places. Decimal32(S).

Example

Query:

Result:

See also

toDecimal32.
toDecimal32OrNull.
toDecimal32OrDefault.

toDecimal32OrNull

Like toDecimal32, this function converts an input value to a value of type Nullable(Decimal(9, S)) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 9, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal32OrNull('0xc0fe', 1);.

Note

Returned value

Value of type Nullable(Decimal(9, S)) if successful, otherwise value NULL of the same type. Decimal32(S).

Examples

Query:

Result:

See also

toDecimal32.
toDecimal32OrZero.
toDecimal32OrDefault.

toDecimal32OrDefault

Like toDecimal32, this function converts an input value to a value of type Decimal(9, S) but returns the default value in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 9, specifying how many digits the fractional part of a number can have. UInt8.
default (optional) — The default value to return if parsing to type Decimal32(S) is unsuccessful. Decimal32(S).

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal32OrDefault('0xc0fe', 1);.

Note

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal32OrDefault(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal32OrDefault('1.15', 2) = 1.15

Returned value

Value of type Decimal(9, S) if successful, otherwise returns the default value if passed or 0 if not. Decimal32(S).

Examples

Query:

Result:

See also

toDecimal32.
toDecimal32OrZero.
toDecimal32OrNull.

toDecimal64

Converts an input value to a value of type Decimal(18, S) with scale of S. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.
S — Scale parameter between 0 and 18, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values or string representations of type Float32/64.

Unsupported arguments:

Values or string representations of Float32/64 values NaN and Inf (case-insensitive).
String representations of binary and hexadecimal values, e.g. SELECT toDecimal64('0xc0fe', 1);.

Note

An overflow can occur if the value of expr exceeds the bounds of Decimal64: ( -1 * 10^(18 - S), 1 * 10^(18 - S) ). Excessive digits in a fraction are discarded (not rounded). Excessive digits in the integer part will lead to an exception.

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal64(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal64('1.15', 2) = 1.15

Returned value

Value of type Decimal(18, S). Decimal64(S).

Example

Query:

Result:

See also

toDecimal64OrZero.
toDecimal64OrNull.
toDecimal64OrDefault.

toDecimal64OrZero

Like toDecimal64, this function converts an input value to a value of type Decimal(18, S) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 18, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal64OrZero('0xc0fe', 1);.

Note

Returned value

Value of type Decimal(18, S) if successful, otherwise 0 with S decimal places. Decimal64(S).

Example

Query:

Result:

See also

toDecimal64.
toDecimal64OrNull.
toDecimal64OrDefault.

toDecimal64OrNull

Like toDecimal64, this function converts an input value to a value of type Nullable(Decimal(18, S)) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 18, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal64OrNull('0xc0fe', 1);.

Note

Returned value

Value of type Nullable(Decimal(18, S)) if successful, otherwise value NULL of the same type. Decimal64(S).

Examples

Query:

Result:

See also

toDecimal64.
toDecimal64OrZero.
toDecimal64OrDefault.

toDecimal64OrDefault

Like toDecimal64, this function converts an input value to a value of type Decimal(18, S) but returns the default value in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 18, specifying how many digits the fractional part of a number can have. UInt8.
default (optional) — The default value to return if parsing to type Decimal64(S) is unsuccessful. Decimal64(S).

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal64OrDefault('0xc0fe', 1);.

Note

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal64OrDefault(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal64OrDefault('1.15', 2) = 1.15

Returned value

Value of type Decimal(18, S) if successful, otherwise returns the default value if passed or 0 if not. Decimal64(S).

Examples

Query:

Result:

See also

toDecimal64.
toDecimal64OrZero.
toDecimal64OrNull.

toDecimal128

Converts an input value to a value of type Decimal(38, S) with scale of S. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.
S — Scale parameter between 0 and 38, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values or string representations of type Float32/64.

Unsupported arguments:

Values or string representations of Float32/64 values NaN and Inf (case-insensitive).
String representations of binary and hexadecimal values, e.g. SELECT toDecimal128('0xc0fe', 1);.

Note

An overflow can occur if the value of expr exceeds the bounds of Decimal128: ( -1 * 10^(38 - S), 1 * 10^(38 - S) ). Excessive digits in a fraction are discarded (not rounded). Excessive digits in the integer part will lead to an exception.

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal128(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal128('1.15', 2) = 1.15

Returned value

Value of type Decimal(38, S). Decimal128(S).

Example

Query:

Result:

See also

toDecimal128OrZero.
toDecimal128OrNull.
toDecimal128OrDefault.

toDecimal128OrZero

Like toDecimal128, this function converts an input value to a value of type Decimal(38, S) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 38, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal128OrZero('0xc0fe', 1);.

Note

Returned value

Value of type Decimal(38, S) if successful, otherwise 0 with S decimal places. Decimal128(S).

Example

Query:

Result:

See also

toDecimal128.
toDecimal128OrNull.
toDecimal128OrDefault.

toDecimal128OrNull

Like toDecimal128, this function converts an input value to a value of type Nullable(Decimal(38, S)) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 38, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal128OrNull('0xc0fe', 1);.

Note

Returned value

Value of type Nullable(Decimal(38, S)) if successful, otherwise value NULL of the same type. Decimal128(S).

Examples

Query:

Result:

See also

toDecimal128.
toDecimal128OrZero.
toDecimal128OrDefault.

toDecimal128OrDefault

Like toDecimal128, this function converts an input value to a value of type Decimal(38, S) but returns the default value in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 38, specifying how many digits the fractional part of a number can have. UInt8.
default (optional) — The default value to return if parsing to type Decimal128(S) is unsuccessful. Decimal128(S).

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal128OrDefault('0xc0fe', 1);.

Note

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal128OrDefault(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal128OrDefault('1.15', 2) = 1.15

Returned value

Value of type Decimal(38, S) if successful, otherwise returns the default value if passed or 0 if not. Decimal128(S).

Examples

Query:

Result:

See also

toDecimal128.
toDecimal128OrZero.
toDecimal128OrNull.

toDecimal256

Converts an input value to a value of type Decimal(76, S) with scale of S. Throws an exception in case of an error.

Syntax

Arguments

expr — Expression returning a number or a string representation of a number. Expression.
S — Scale parameter between 0 and 76, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

Values or string representations of type (U)Int8/16/32/64/128/256.
Values or string representations of type Float32/64.

Unsupported arguments:

Values or string representations of Float32/64 values NaN and Inf (case-insensitive).
String representations of binary and hexadecimal values, e.g. SELECT toDecimal256('0xc0fe', 1);.

Note

An overflow can occur if the value of expr exceeds the bounds of Decimal256: ( -1 * 10^(76 - S), 1 * 10^(76 - S) ). Excessive digits in a fraction are discarded (not rounded). Excessive digits in the integer part will lead to an exception.

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal256(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal256('1.15', 2) = 1.15

Returned value

Value of type Decimal(76, S). Decimal256(S).

Example

Query:

Result:

See also

toDecimal256OrZero.
toDecimal256OrNull.
toDecimal256OrDefault.

toDecimal256OrZero

Like toDecimal256, this function converts an input value to a value of type Decimal(76, S) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 76, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal256OrZero('0xc0fe', 1);.

Note

Returned value

Value of type Decimal(76, S) if successful, otherwise 0 with S decimal places. Decimal256(S).

Example

Query:

Result:

See also

toDecimal256.
toDecimal256OrNull.
toDecimal256OrDefault.

toDecimal256OrNull

Like toDecimal256, this function converts an input value to a value of type Nullable(Decimal(76, S)) but returns 0 in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 76, specifying how many digits the fractional part of a number can have. UInt8.

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal256OrNull('0xc0fe', 1);.

Note

Returned value

Value of type Nullable(Decimal(76, S)) if successful, otherwise value NULL of the same type. Decimal256(S).

Examples

Query:

Result:

See also

toDecimal256.
toDecimal256OrZero.
toDecimal256OrDefault.

toDecimal256OrDefault

Like toDecimal256, this function converts an input value to a value of type Decimal(76, S) but returns the default value in case of an error.

Syntax

Arguments

expr — A String representation of a number. String.
S — Scale parameter between 0 and 76, specifying how many digits the fractional part of a number can have. UInt8.
default (optional) — The default value to return if parsing to type Decimal256(S) is unsuccessful. Decimal256(S).

Supported arguments:

String representations of type (U)Int8/16/32/64/128/256.
String representations of type Float32/64.

Unsupported arguments:

String representations of Float32/64 values NaN and Inf.
String representations of binary and hexadecimal values, e.g. SELECT toDecimal256OrDefault('0xc0fe', 1);.

Note

Danger

Conversions drop extra digits and could operate in an unexpected way when working with Float32/Float64 inputs as the operations are performed using floating point instructions. For example: toDecimal256OrDefault(1.15, 2) is equal to 1.14 because 1.15 * 100 in floating point is 114.99. You can use a String input so the operations use the underlying integer type: toDecimal256OrDefault('1.15', 2) = 1.15

Returned value

Value of type Decimal(76, S) if successful, otherwise returns the default value if passed or 0 if not. Decimal256(S).

Examples

Query:

Result:

See also

toDecimal256.
toDecimal256OrZero.
toDecimal256OrNull.

toString

Functions for converting between numbers, strings (but not fixed strings), dates, and dates with times. All these functions accept one argument.

When converting to or from a string, the value is formatted or parsed using the same rules as for the TabSeparated format (and almost all other text formats). If the string can't be parsed, an exception is thrown and the request is canceled.

When converting dates to numbers or vice versa, the date corresponds to the number of days since the beginning of the Unix epoch. When converting dates with times to numbers or vice versa, the date with time corresponds to the number of seconds since the beginning of the Unix epoch.

The date and date-with-time formats for the toDate/toDateTime functions are defined as follows:

As an exception, if converting from UInt32, Int32, UInt64, or Int64 numeric types to Date, and if the number is greater than or equal to 65536, the number is interpreted as a Unix timestamp (and not as the number of days) and is rounded to the date. This allows support for the common occurrence of writing toDate(unix_timestamp), which otherwise would be an error and would require writing the more cumbersome toDate(toDateTime(unix_timestamp)).

Conversion between a date and a date with time is performed the natural way: by adding a null time or dropping the time.

Conversion between numeric types uses the same rules as assignments between different numeric types in C++.

Additionally, the toString function of the DateTime argument can take a second String argument containing the name of the time zone. Example: Asia/Yekaterinburg In this case, the time is formatted according to the specified time zone.

Example

Query:

Result:

Also see the toUnixTimestamp function.

toFixedString

Converts a String type argument to a FixedString(N) type (a string of fixed length N). If the string has fewer bytes than N, it is padded with null bytes to the right. If the string has more bytes than N, an exception is thrown.

Syntax

Arguments

s — A String to convert to a fixed string. String.
N — Length N. UInt8

Returned value

An N length fixed string of s. FixedString.

Example

Query:

Result:

toStringCutToZero

Accepts a String or FixedString argument. Returns the String with the content truncated at the first zero byte found.

Syntax

Example

Query:

Result:

Query:

Result:

toDecimalString

Converts a numeric value to String with the number of fractional digits in the output specified by the user.

Syntax

Arguments

number — Value to be represented as String, Int, UInt, Float, Decimal,
scale — Number of fractional digits, UInt8.
- Maximum scale for Decimal and Int, UInt types is 77 (it is the maximum possible number of significant digits for Decimal),
- Maximum scale for Float is 60.

Returned value

Input value represented as String with given number of fractional digits (scale). The number is rounded up or down according to common arithmetic in case requested scale is smaller than original number's scale.

Example

Query:

Result:

reinterpretAsUInt8

Performs byte reinterpretation by treating the input value as a value of type UInt8. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as UInt8. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as UInt8. UInt8.

Example

Query:

Result:

reinterpretAsUInt16

Performs byte reinterpretation by treating the input value as a value of type UInt16. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as UInt16. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as UInt16. UInt16.

Example

Query:

Result:

reinterpretAsUInt32

Performs byte reinterpretation by treating the input value as a value of type UInt32. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as UInt32. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as UInt32. UInt32.

Example

Query:

Result:

reinterpretAsUInt64

Performs byte reinterpretation by treating the input value as a value of type UInt64. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as UInt64. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as UInt64. UInt64.

Example

Query:

Result:

reinterpretAsUInt128

Performs byte reinterpretation by treating the input value as a value of type UInt128. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as UInt128. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as UInt128. UInt128.

Example

Query:

Result:

reinterpretAsUInt256

Performs byte reinterpretation by treating the input value as a value of type UInt256. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as UInt256. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as UInt256. UInt256.

Example

Query:

Result:

reinterpretAsInt8

Performs byte reinterpretation by treating the input value as a value of type Int8. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as Int8. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Int8. Int8.

Example

Query:

Result:

reinterpretAsInt16

Performs byte reinterpretation by treating the input value as a value of type Int16. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as Int16. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Int16. Int16.

Example

Query:

Result:

reinterpretAsInt32

Performs byte reinterpretation by treating the input value as a value of type Int32. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as Int32. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Int32. Int32.

Example

Query:

Result:

reinterpretAsInt64

Performs byte reinterpretation by treating the input value as a value of type Int64. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as Int64. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Int64. Int64.

Example

Query:

Result:

reinterpretAsInt128

Performs byte reinterpretation by treating the input value as a value of type Int128. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as Int128. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Int128. Int128.

Example

Query:

Result:

reinterpretAsInt256

Performs byte reinterpretation by treating the input value as a value of type Int256. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to byte reinterpret as Int256. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Int256. Int256.

Example

Query:

Result:

reinterpretAsFloat32

Performs byte reinterpretation by treating the input value as a value of type Float32. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to reinterpret as Float32. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Float32. Float32.

Example

Query:

Result:

reinterpretAsFloat64

Performs byte reinterpretation by treating the input value as a value of type Float64. Unlike CAST, the function does not attempt to preserve the original value - if the target type is not able to represent the input type, the output is meaningless.

Syntax

Parameters

x: value to reinterpret as Float64. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Reinterpreted value x as Float64. Float64.

Example

Query:

Result:

reinterpretAsDate

Accepts a string, fixed string or numeric value and interprets the bytes as a number in host order (little endian). It returns a date from the interpreted number as the number of days since the beginning of the Unix Epoch.

Syntax

Parameters

x: number of days since the beginning of the Unix Epoch. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Date. Date.

Implementation details

Note

If the provided string isn't long enough, the function works as if the string is padded with the necessary number of null bytes. If the string is longer than needed, the extra bytes are ignored.

Example

Query:

Result:

reinterpretAsDateTime

These functions accept a string and interpret the bytes placed at the beginning of the string as a number in host order (little endian). Returns a date with time interpreted as the number of seconds since the beginning of the Unix Epoch.

Syntax

Parameters

x: number of seconds since the beginning of the Unix Epoch. (U)Int*, Float, Date, DateTime, UUID, String or FixedString.

Returned value

Date and Time. DateTime.

Implementation details

Note

If the provided string isn't long enough, the function works as if the string is padded with the necessary number of null bytes. If the string is longer than needed, the extra bytes are ignored.

Example

Query:

Result:

reinterpretAsString

This function accepts a number, date or date with time and returns a string containing bytes representing the corresponding value in host order (little endian). Null bytes are dropped from the end. For example, a UInt32 type value of 255 is a string that is one byte long.

Syntax

Parameters

x: value to reinterpret to string. (U)Int*, Float, Date, DateTime.

Returned value

String containing bytes representing x. String.

Example

Query:

Result:

reinterpretAsFixedString

This function accepts a number, date or date with time and returns a FixedString containing bytes representing the corresponding value in host order (little endian). Null bytes are dropped from the end. For example, a UInt32 type value of 255 is a FixedString that is one byte long.

Syntax

Parameters

x: value to reinterpret to string. (U)Int*, Float, Date, DateTime.

Returned value

Fixed string containing bytes representing x. FixedString.

Example

Query:

Result:

reinterpretAsUUID

Note

In addition to the UUID functions listed here, there is dedicated UUID function documentation.

Accepts a 16 byte string and returns a UUID containing bytes representing the corresponding value in network byte order (big-endian). If the string isn't long enough, the function works as if the string is padded with the necessary number of null bytes to the end. If the string is longer than 16 bytes, the extra bytes at the end are ignored.

Syntax

Arguments

fixed_string — Big-endian byte string. FixedString.

Returned value

The UUID type value. UUID.

Examples

String to UUID.

Query:

Result:

Going back and forth from String to UUID.

Query:

Result:

reinterpret

Uses the same source in-memory bytes sequence for x value and reinterprets it to destination type.

Syntax

Arguments

x — Any type.
type — Destination type. String.

Returned value

Destination type value.

Examples

Query:

Result:

CAST

Converts an input value to the specified data type. Unlike the reinterpret function, CAST tries to present the same value using the new data type. If the conversion can not be done then an exception is raised. Several syntax variants are supported.

Syntax

Arguments

x — A value to convert. May be of any type.
T — The name of the target data type. String.
t — The target data type.

Returned value

Converted value.

Note

If the input value does not fit the bounds of the target type, the result overflows. For example, CAST(-1, 'UInt8') returns 255.

Examples

Query:

Result:

Query:

Result:

Conversion to FixedString (N) only works for arguments of type String or FixedString.

Type conversion to Nullable and back is supported.

Example

Query:

Result:

Query:

Result:

See also

cast_keep_nullable setting

accurateCast(x, T)

Converts x to the T data type.

The difference from cast is that accurateCast does not allow overflow of numeric types during cast if type value x does not fit the bounds of type T. For example, accurateCast(-1, 'UInt8') throws an exception.

Example

Query:

Result:

Query:

Result:

accurateCastOrNull(x, T)

Converts input value x to the specified data type T. Always returns Nullable type and returns NULL if the cast value is not representable in the target type.

Syntax

Arguments

x — Input value.
T — The name of the returned data type.

Returned value

The value, converted to the specified data type T.

Example

Query:

Result:

Query:

Result:

accurateCastOrDefault(x, T[, default_value])

Converts input value x to the specified data type T. Returns default type value or default_value if specified if the cast value is not representable in the target type.

Syntax

Arguments

x — Input value.
T — The name of the returned data type.
default_value — Default value of returned data type.

Returned value

The value converted to the specified data type T.

Example

Query:

Result:

Query:

Result:

toIntervalYear

Returns an interval of n years of data type IntervalYear.

Syntax

Arguments

n — Number of years. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n years. IntervalYear.

Example

Query:

Result:

toIntervalQuarter

Returns an interval of n quarters of data type IntervalQuarter.

Syntax

Arguments

n — Number of quarters. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n quarters. IntervalQuarter.

Example

Query:

Result:

toIntervalMonth

Returns an interval of n months of data type IntervalMonth.

Syntax

Arguments

n — Number of months. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n months. IntervalMonth.

Example

Query:

Result:

toIntervalWeek

Returns an interval of n weeks of data type IntervalWeek.

Syntax

Arguments

n — Number of weeks. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n weeks. IntervalWeek.

Example

Query:

Result:

toIntervalDay

Returns an interval of n days of data type IntervalDay.

Syntax

Arguments

n — Number of days. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n days. IntervalDay.

Example

Query:

Result:

toIntervalHour

Returns an interval of n hours of data type IntervalHour.

Syntax

Arguments

n — Number of hours. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n hours. IntervalHour.

Example

Query:

Result:

toIntervalMinute

Returns an interval of n minutes of data type IntervalMinute.

Syntax

Arguments

n — Number of minutes. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n minutes. IntervalMinute.

Example

Query:

Result:

toIntervalSecond

Returns an interval of n seconds of data type IntervalSecond.

Syntax

Arguments

n — Number of seconds. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n seconds. IntervalSecond.

Example

Query:

Result:

toIntervalMillisecond

Returns an interval of n milliseconds of data type IntervalMillisecond.

Syntax

Arguments

n — Number of milliseconds. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n milliseconds. IntervalMilliseconds.

Example

Query:

Result:

toIntervalMicrosecond

Returns an interval of n microseconds of data type IntervalMicrosecond.

Syntax

Arguments

n — Number of microseconds. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n microseconds. IntervalMicrosecond.

Example

Query:

Result:

toIntervalNanosecond

Returns an interval of n nanoseconds of data type IntervalNanosecond.

Syntax

Arguments

n — Number of nanoseconds. Integer numbers or string representations thereof, and float numbers. (U)Int*/Float*/String.

Returned values

Interval of n nanoseconds. IntervalNanosecond.

Example

Query:

Result:

parseDateTime

Converts a String to DateTime according to a MySQL format string.

This function is the opposite operation of function formatDateTime.

Syntax

Arguments

str — The String to be parsed
format — The format string. Optional. %Y-%m-%d %H:%i:%s if not specified.
timezone — Timezone. Optional.

Returned value(s)

Return a DateTime value parsed from the input string according to a MySQL-style format string.

Supported format specifiers

All format specifiers listed in formatDateTime except:

%Q: Quarter (1-4)

Example

Alias: TO_TIMESTAMP.

parseDateTimeOrZero

Same as for parseDateTime except that it returns zero date when it encounters a date format that cannot be processed.

parseDateTimeOrNull

Same as for parseDateTime except that it returns NULL when it encounters a date format that cannot be processed.

Alias: str_to_date.

parseDateTimeInJodaSyntax

Similar to parseDateTime, except that the format string is in Joda instead of MySQL syntax.

This function is the opposite operation of function formatDateTimeInJodaSyntax.

Syntax

Arguments

str — The String to be parsed
format — The format string. Optional. yyyy-MM-dd HH:mm:ss if not specified.
timezone — Timezone. Optional.

Returned value(s)

Return a DateTime value parsed from the input string according to a Joda-style format string.

Supported format specifiers

All format specifiers listed in formatDateTimeInJoda are supported, except:

S: fraction of second
z: time zone
Z: time zone offset/id

Example

parseDateTimeInJodaSyntaxOrZero

Same as for parseDateTimeInJodaSyntax except that it returns zero date when it encounters a date format that cannot be processed.

parseDateTimeInJodaSyntaxOrNull

Same as for parseDateTimeInJodaSyntax except that it returns NULL when it encounters a date format that cannot be processed.

parseDateTime64

Converts a String to DateTime64 according to a MySQL format string.

Syntax

Arguments

str — The String to be parsed.
format — The format string. Optional. %Y-%m-%d %H:%i:%s.%f if not specified.
timezone — Timezone. Optional.

Returned value(s)

Return a DateTime64 value parsed from the input string according to a MySQL-style format string. The precision of the returned value is 6.

parseDateTime64OrZero

Same as for parseDateTime64 except that it returns zero date when it encounters a date format that cannot be processed.

parseDateTime64OrNull

Same as for parseDateTime64 except that it returns NULL when it encounters a date format that cannot be processed.

parseDateTime64InJodaSyntax

Converts a String to DateTime64 according to a Joda format string.

Syntax

Arguments

str — The String to be parsed.
format — The format string. Optional. yyyy-MM-dd HH:mm:ss if not specified.
timezone — Timezone. Optional.

Returned value(s)

Return a DateTime64 value parsed from the input string according to a Joda-style format string. The precision of the returned value equal to the number of S placeholders in the format string (but at most 6).

parseDateTime64InJodaSyntaxOrZero

Same as for parseDateTime64InJodaSyntax except that it returns zero date when it encounters a date format that cannot be processed.

parseDateTime64InJodaSyntaxOrNull

Same as for parseDateTime64InJodaSyntax except that it returns NULL when it encounters a date format that cannot be processed.

parseDateTimeBestEffort

parseDateTime32BestEffort

Converts a date and time in the String representation to DateTime data type.

The function parses ISO 8601, RFC 1123 - 5.2.14 RFC-822 Date and Time Specification, ClickHouse's and some other date and time formats.

Syntax

Arguments

time_string — String containing a date and time to convert. String.
time_zone — Time zone. The function parses time_string according to the time zone. String.

Supported non-standard formats

A string containing 9..10 digit unix timestamp.
A string with a date and a time component: YYYYMMDDhhmmss, DD/MM/YYYY hh:mm:ss, DD-MM-YY hh:mm, YYYY-MM-DD hh:mm:ss, etc.
A string with a date, but no time component: YYYY, YYYYMM, YYYY*MM, DD/MM/YYYY, DD-MM-YY etc.
A string with a day and time: DD, DD hh, DD hh:mm. In this case MM is substituted by 01.
A string that includes the date and time along with time zone offset information: YYYY-MM-DD hh:mm:ss ±h:mm, etc. For example, 2020-12-12 17:36:00 -5:00.
A syslog timestamp: Mmm dd hh:mm:ss. For example, Jun 9 14:20:32.

For all of the formats with separator the function parses months names expressed by their full name or by the first three letters of a month name. Examples: 24/DEC/18, 24-Dec-18, 01-September-2018. If the year is not specified, it is considered to be equal to the current year. If the resulting DateTime happen to be in the future (even by a second after the current moment), then the current year is substituted by the previous year.

Returned value

time_string converted to the DateTime data type.

Examples

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

Query:

Result:

See also

parseDateTimeBestEffortUS

This function behaves like parseDateTimeBestEffort for ISO date formats, e.g. YYYY-MM-DD hh:mm:ss, and other date formats where the month and date components can be unambiguously extracted, e.g. YYYYMMDDhhmmss, YYYY-MM, DD hh, or YYYY-MM-DD hh:mm:ss ±h:mm. If the month and the date components cannot be unambiguously extracted, e.g. MM/DD/YYYY, MM-DD-YYYY, or MM-DD-YY, it prefers the US date format instead of DD/MM/YYYY, DD-MM-YYYY, or DD-MM-YY. As an exception from the latter, if the month is bigger than 12 and smaller or equal than 31, this function falls back to the behavior of parseDateTimeBestEffort, e.g. 15/08/2020 is parsed as 2020-08-15.

parseDateTimeBestEffortOrNull

parseDateTime32BestEffortOrNull

Same as for parseDateTimeBestEffort except that it returns NULL when it encounters a date format that cannot be processed.

parseDateTimeBestEffortOrZero

parseDateTime32BestEffortOrZero

Same as for parseDateTimeBestEffort except that it returns zero date or zero date time when it encounters a date format that cannot be processed.

parseDateTimeBestEffortUSOrNull

Same as parseDateTimeBestEffortUS function except that it returns NULL when it encounters a date format that cannot be processed.

parseDateTimeBestEffortUSOrZero

Same as parseDateTimeBestEffortUS function except that it returns zero date (1970-01-01) or zero date with time (1970-01-01 00:00:00) when it encounters a date format that cannot be processed.

parseDateTime64BestEffort

Same as parseDateTimeBestEffort function but also parse milliseconds and microseconds and returns DateTime data type.

Syntax

Arguments

time_string — String containing a date or date with time to convert. String.
precision — Required precision. 3 — for milliseconds, 6 — for microseconds. Default — 3. Optional. UInt8.
time_zone — Timezone. The function parses time_string according to the timezone. Optional. String.

Returned value

time_string converted to the DateTime data type.

Examples

Query:

Result:

parseDateTime64BestEffortUS

Same as for parseDateTime64BestEffort, except that this function prefers US date format (MM/DD/YYYY etc.) in case of ambiguity.

parseDateTime64BestEffortOrNull

Same as for parseDateTime64BestEffort except that it returns NULL when it encounters a date format that cannot be processed.

parseDateTime64BestEffortOrZero

Same as for parseDateTime64BestEffort except that it returns zero date or zero date time when it encounters a date format that cannot be processed.

parseDateTime64BestEffortUSOrNull

Same as for parseDateTime64BestEffort, except that this function prefers US date format (MM/DD/YYYY etc.) in case of ambiguity and returns NULL when it encounters a date format that cannot be processed.

parseDateTime64BestEffortUSOrZero

Same as for parseDateTime64BestEffort, except that this function prefers US date format (MM/DD/YYYY etc.) in case of ambiguity and returns zero date or zero date time when it encounters a date format that cannot be processed.

toLowCardinality

Converts input parameter to the LowCardinality version of same data type.

To convert data from the LowCardinality data type use the CAST function. For example, CAST(x as String).

Syntax

Arguments

expr — Expression resulting in one of the supported data types.

Returned values

Result of expr. LowCardinality of the type of expr.

Example

Query:

Result:

toUnixTimestamp64Second

Converts a DateTime64 to a Int64 value with fixed second precision. The input value is scaled up or down appropriately depending on its precision.

Note

The output value is a timestamp in UTC, not in the timezone of DateTime64.

Syntax

Arguments

value — DateTime64 value with any precision. DateTime64.

Returned value

value converted to the Int64 data type. Int64.

Example

Query:

Result:

toUnixTimestamp64Milli

Converts a DateTime64 to a Int64 value with fixed millisecond precision. The input value is scaled up or down appropriately depending on its precision.

Note

The output value is a timestamp in UTC, not in the timezone of DateTime64.

Syntax

Arguments

value — DateTime64 value with any precision. DateTime64.

Returned value

value converted to the Int64 data type. Int64.

Example

Query:

Result:

toUnixTimestamp64Micro

Converts a DateTime64 to a Int64 value with fixed microsecond precision. The input value is scaled up or down appropriately depending on its precision.

Note

The output value is a timestamp in UTC, not in the timezone of DateTime64.

Syntax

Arguments

value — DateTime64 value with any precision. DateTime64.

Returned value

value converted to the Int64 data type. Int64.

Example

Query:

Result:

toUnixTimestamp64Nano

Converts a DateTime64 to a Int64 value with fixed nanosecond precision. The input value is scaled up or down appropriately depending on its precision.

Note

The output value is a timestamp in UTC, not in the timezone of DateTime64.

Syntax

Arguments

value — DateTime64 value with any precision. DateTime64.

Returned value

value converted to the Int64 data type. Int64.

Example

Query:

Result:

fromUnixTimestamp64Second

Converts an Int64 to a DateTime64 value with fixed second precision and optional timezone. The input value is scaled up or down appropriately depending on its precision.

Note

Please note that input value is treated as a UTC timestamp, not timestamp at the given (or implicit) timezone.

Syntax

Arguments

value — value with any precision. Int64.
timezone — (optional) timezone name of the result. String.

Returned value

value converted to DateTime64 with precision 0. DateTime64.

Example

Query:

Result:

fromUnixTimestamp64Milli

Converts an Int64 to a DateTime64 value with fixed millisecond precision and optional timezone. The input value is scaled up or down appropriately depending on its precision.

Note

Please note that input value is treated as a UTC timestamp, not timestamp at the given (or implicit) timezone.

Syntax

Arguments

value — value with any precision. Int64.
timezone — (optional) timezone name of the result. String.

Returned value

value converted to DateTime64 with precision 3. DateTime64.

Example

Query:

Result:

fromUnixTimestamp64Micro

Converts an Int64 to a DateTime64 value with fixed microsecond precision and optional timezone. The input value is scaled up or down appropriately depending on its precision.

Note

Please note that input value is treated as a UTC timestamp, not timestamp at the given (or implicit) timezone.

Syntax

Arguments

value — value with any precision. Int64.
timezone — (optional) timezone name of the result. String.

Returned value

value converted to DateTime64 with precision 6. DateTime64.

Example

Query:

Result:

fromUnixTimestamp64Nano

Converts an Int64 to a DateTime64 value with fixed nanosecond precision and optional timezone. The input value is scaled up or down appropriately depending on its precision.

Note

Please note that input value is treated as a UTC timestamp, not timestamp at the given (or implicit) timezone.

Syntax

Arguments

value — value with any precision. Int64.
timezone — (optional) timezone name of the result. String.

Returned value

value converted to DateTime64 with precision 9. DateTime64.

Example

Query:

Result:

formatRow

Converts arbitrary expressions into a string via given format.

Syntax

Arguments

format — Text format. For example, CSV, TSV.
x,y, ... — Expressions.

Returned value

A formatted string. (for text formats it's usually terminated with the new line character).

Example

Query:

Result:

Note: If format contains suffix/prefix, it will be written in each row.

Example

Query:

Result:

Note: Only row-based formats are supported in this function.

formatRowNoNewline

Converts arbitrary expressions into a string via given format. Differs from formatRow in that this function trims the last \n if any.

Syntax

Arguments

format — Text format. For example, CSV, TSV.
x,y, ... — Expressions.

Returned value

A formatted string.

Example

Query:

Result:

Common Issues with Data Conversion​

toBool​

toInt8​

toInt8OrZero​

toInt8OrNull​

toInt8OrDefault​

toInt16​

toInt16OrZero​

toInt16OrNull​

toInt16OrDefault​

toInt32​

toInt32OrZero​

toInt32OrNull​

toInt32OrDefault​

toInt64​

toInt64OrZero​

toInt64OrNull​

toInt64OrDefault​

toInt128​

toInt128OrZero​

toInt128OrNull​

toInt128OrDefault​

toInt256​

toInt256OrZero​

toInt256OrNull​

toInt256OrDefault​

toUInt8​

toUInt8OrZero​

toUInt8OrNull​

toUInt8OrDefault​

toUInt16​

toUInt16OrZero​

toUInt16OrNull​

toUInt16OrDefault​

toUInt32​

toUInt32OrZero​

toUInt32OrNull​

toUInt32OrDefault​

toUInt64​

toUInt64OrZero​

toUInt64OrNull​

toUInt64OrDefault​

toUInt128​

toUInt128OrZero​

toUInt128OrNull​

toUInt128OrDefault​

toUInt256​

toUInt256OrZero​

toUInt256OrNull​

toUInt256OrDefault​

toFloat32​

toFloat32OrZero​

toFloat32OrNull​

toFloat32OrDefault​

toFloat64​

toFloat64OrZero​

toFloat64OrNull​

toFloat64OrDefault​

toBFloat16​

toBFloat16OrZero​

toBFloat16OrNull​

toDate​

toDateOrZero​

toDateOrNull​

toDateOrDefault​

toDateTime​

toDateTimeOrZero​

toDateTimeOrNull​

toDateTimeOrDefault​

toDate32​

toDate32OrZero​

toDate32OrNull​

toDate32OrDefault​

toDateTime64​

toDateTime64OrZero​

toDateTime64OrNull​

toDateTime64OrDefault​

toDecimal32​

toDecimal32OrZero​

toDecimal32OrNull​

Common Issues with Data Conversion

toBool

toInt8

toInt8OrZero

toInt8OrNull

toInt8OrDefault

toInt16

toInt16OrZero

toInt16OrNull

toInt16OrDefault

toInt32

toInt32OrZero

toInt32OrNull

toInt32OrDefault

toInt64

toInt64OrZero

toInt64OrNull

toInt64OrDefault

toInt128

toInt128OrZero

toInt128OrNull

toInt128OrDefault

toInt256

toInt256OrZero

toInt256OrNull

toInt256OrDefault

toUInt8

toUInt8OrZero

toUInt8OrNull

toUInt8OrDefault

toUInt16

toUInt16OrZero

toUInt16OrNull

toUInt16OrDefault

toUInt32

toUInt32OrZero

toUInt32OrNull

toUInt32OrDefault

toUInt64

toUInt64OrZero

toUInt64OrNull

toUInt64OrDefault

toUInt128

toUInt128OrZero

toUInt128OrNull

toUInt128OrDefault

toUInt256

toUInt256OrZero

toUInt256OrNull

toUInt256OrDefault

toFloat32

toFloat32OrZero

toFloat32OrNull

toFloat32OrDefault

toFloat64

toFloat64OrZero

toFloat64OrNull

toFloat64OrDefault

toBFloat16

toBFloat16OrZero

toBFloat16OrNull

toDate

toDateOrZero

toDateOrNull

toDateOrDefault

toDateTime

toDateTimeOrZero

toDateTimeOrNull

toDateTimeOrDefault

toDate32

toDate32OrZero

toDate32OrNull

toDate32OrDefault

toDateTime64

toDateTime64OrZero

toDateTime64OrNull

toDateTime64OrDefault

toDecimal32

toDecimal32OrZero

toDecimal32OrNull