类型转换函数

数据转换的常见问题

在某些情况下，to<type> 函数与 cast 的行为有所不同，例如在 LowCardinality 的情况下：cast 会去除 LowCardinality 特性，而 to<type> 函数则不会。对于 Nullable 也是如此，这种行为与 SQL 标准不兼容，并且可以通过 cast_keep_nullable 设置来更改。

备注

请注意，如果数据类型的值被转换为较小的数据类型（例如从 Int64 转换为 Int32）或在不兼容的数据类型之间转换（例如从 String 转换为 Int），可能会导致潜在的数据丢失。请确保仔细检查结果是否如预期。

示例：

toBool

将输入值转换为 Bool 类型的值。如果发生错误，则抛出异常。

语法

参数

expr — 返回数字或字符串的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值。
类型为 Float32/64 的值。
字符串 true 或 false（不区分大小写）。

返回值

基于对参数的评估返回 true 或 false。 Bool。

示例

查询：

结果：

toInt8

将输入值转换为 Int8 类型的值。如果发生错误，则抛出异常。

语法

参数

expr — 返回数字或字符串表示数字的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt8('0xc0fe');。

备注

如果输入值无法在 Int8 的范围内表示，则会发生溢出或下溢。这不算作错误。例如：SELECT toInt8(128) == -128;。

返回值

8 位整数值。 Int8。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt8OrZero。
toInt8OrNull。
toInt8OrDefault。

toInt8OrZero

与 toInt8 类似，该函数将输入值转换为 Int8 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

普通 Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt8OrZero('0xc0fe');。

备注

如果输入值无法在 Int8 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 8 位整数值，否则返回 0。 Int8。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt8。
toInt8OrNull。
toInt8OrDefault。

toInt8OrNull

与 toInt8 类似，该函数将输入值转换为 Int8 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt8OrNull('0xc0fe');。

备注

如果输入值无法在 Int8 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 8 位整数值，否则返回 NULL。 Int8 / NULL。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt8。
toInt8OrZero。
toInt8OrDefault。

toInt8OrDefault

与 toInt8 类似，该函数将输入值转换为 Int8 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或字符串表示的表达式。表达式 / 字符串。
default（可选） — 如果解析到 Int8 类型不成功，则返回的默认值。 Int8。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

在以下情况下返回默认值：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt8OrDefault('0xc0fe', CAST('-1', 'Int8'));。

备注

如果输入值无法在 Int8 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 8 位整数值，否则返回传入的默认值（如果提供）或 0（如果未提供）。 Int8。

备注

该函数使用向零取整的方式，即截断数字的分数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另见

toInt8。
toInt8OrZero。
toInt8OrNull。

toInt16

将输入值转换为 Int16 类型的值。如果发生错误，则抛出异常。

语法

参数

expr — 返回数字或字符串表示数字的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt16('0xc0fe');。

备注

如果输入值无法在 Int16 的范围内表示，则会发生溢出或下溢。这不算作错误。例如：SELECT toInt16(32768) == -32768;。

返回值

16 位整数值。 Int16。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt16OrZero。
toInt16OrNull。
toInt16OrDefault。

toInt16OrZero

与 toInt16 类似，该函数将输入值转换为 Int16 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt16OrZero('0xc0fe');。

备注

如果输入值无法在 Int16 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

16 位整数值如果成功，否则返回 0。 Int16。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt16。
toInt16OrNull。
toInt16OrDefault。

toInt16OrNull

与 toInt16 类似，该函数将输入值转换为 Int16 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt16OrNull('0xc0fe');。

备注

如果输入值无法在 Int16 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 16 位整数值，否则返回 NULL。 Int16 / NULL。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt16。
toInt16OrZero。
toInt16OrDefault。

toInt16OrDefault

与 toInt16 类似，该函数将输入值转换为 Int16 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或字符串表示的表达式。表达式 / 字符串。
default（可选） — 如果解析到 Int16 类型不成功，则返回的默认值。 Int16。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

在以下情况下返回默认值：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt16OrDefault('0xc0fe', CAST('-1', 'Int16'));。

备注

如果输入值无法在 Int16 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 16 位整数值，否则返回传入的默认值（如果提供）或 0（如果未提供）。 Int16。

备注

该函数使用向零取整的方式，即截断数字的分数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另见

toInt16。
toInt16OrZero。
toInt16OrNull。

toInt32

将输入值转换为 Int32 类型的值。如果发生错误，则抛出异常。

语法

参数

expr — 返回数字或字符串表示数字的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt32('0xc0fe');。

备注

如果输入值无法在 Int32 的范围内表示，则会发生溢出或下溢。这不算作错误。例如：SELECT toInt32(2147483648) == -2147483648;。

返回值

32 位整数值。 Int32。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt32OrZero。
toInt32OrNull。
toInt32OrDefault。

toInt32OrZero

与 toInt32 类似，该函数将输入值转换为 Int32 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt32OrZero('0xc0fe');。

备注

如果输入值无法在 Int32 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

32 位整数值如果成功，否则返回 0。 Int32

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt32。
toInt32OrNull。
toInt32OrDefault。

toInt32OrNull

与 toInt32 类似，该函数将输入值转换为 Int32 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt32OrNull('0xc0fe');。

备注

如果输入值无法在 Int32 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 32 位整数值，否则返回 NULL。 Int32 / NULL。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt32。
toInt32OrZero。
toInt32OrDefault。

toInt32OrDefault

与 toInt32 类似，该函数将输入值转换为 Int32 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或字符串表示的表达式。表达式 / 字符串。
default（可选） — 如果解析到 Int32 类型不成功，则返回的默认值。 Int32。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

在以下情况下返回默认值：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt32OrDefault('0xc0fe', CAST('-1', 'Int32'));。

备注

如果输入值无法在 Int32 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 32 位整数值，否则返回传入的默认值（如果提供）或 0（如果未提供）。 Int32。

备注

该函数使用向零取整的方式，即截断数字的分数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另见

toInt32。
toInt32OrZero。
toInt32OrNull。

toInt64

将输入值转换为 Int64 类型的值。如果发生错误，则抛出异常。

语法

参数

expr — 返回数字或字符串表示数字的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt64('0xc0fe');。

备注

如果输入值无法在 Int64 的范围内表示，则会发生溢出或下溢。这不算作错误。例如：SELECT toInt64(9223372036854775808) == -9223372036854775808;。

返回值

64 位整数值。 Int64。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt64OrZero。
toInt64OrNull。
toInt64OrDefault。

toInt64OrZero

与 toInt64 类似，该函数将输入值转换为 Int64 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt64OrZero('0xc0fe');。

备注

如果输入值无法在 Int64 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

64 位整数值如果成功，否则返回 0。 Int64。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt64。
toInt64OrNull。
toInt64OrDefault。

toInt64OrNull

与 toInt64 类似，该函数将输入值转换为 Int64 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。表达式 / 字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt64OrNull('0xc0fe');。

备注

如果输入值无法在 Int64 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 64 位整数值，否则返回 NULL。 Int64 / NULL。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt64。
toInt64OrZero。
toInt64OrDefault。

toInt64OrDefault

与 toInt64 类似，该函数将输入值转换为 Int64 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或字符串表示的表达式。表达式 / 字符串。
default（可选） — 如果解析到 Int64 类型不成功，则返回的默认值。 Int64。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

在以下情况下返回默认值：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt64OrDefault('0xc0fe', CAST('-1', 'Int64'));。

备注

如果输入值无法在 Int64 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

成功时返回 64 位整数值，否则返回传入的默认值（如果提供）或 0（如果未提供）。 Int64。

备注

该函数使用向零取整的方式，即截断数字的分数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另见

toInt64。
toInt64OrZero。
toInt64OrNull。

toInt128

将输入值转换为 Int128 类型的值。如果发生错误，则抛出异常。

语法

参数

expr — 返回数字或字符串表示数字的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt128('0xc0fe');。

备注

如果输入值无法在 Int128 的范围内表示，则会发生溢出或下溢。这不算作错误。

返回值

128 位整数值。 Int128。

备注

该函数使用向零取整的方式，即截断数字的分数位。

示例

查询：

结果：

另见

toInt128OrZero。
toInt128OrNull。
toInt128OrDefault。

toInt128OrZero

像 toInt128 这个函数一样，转换输入值为 Int128 类型的值，但在出现错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt128OrZero('0xc0fe');。

备注

如果输入值无法在 Int128 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 128 位整数值，否则返回 0。 Int128。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toInt128。
toInt128OrNull。
toInt128OrDefault。

toInt128OrNull

像 toInt128 这个函数一样，转换输入值为 Int128 类型的值，但在出现错误时返回 NULL。

语法

参数

x — 数字的字符串表示。表达式 / 字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt128OrNull('0xc0fe');。

备注

如果输入值无法在 Int128 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 128 位整数值，否则返回 NULL。 Int128 / NULL。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toInt128。
toInt128OrZero。
toInt128OrDefault。

toInt128OrDefault

像 toInt128 这个函数一样，将输入值转换为 Int128 类型的值，但在出现错误时返回默认值。如果未传递 default 值，则在出现错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default （可选）— 如果解析为 Int128 类型不成功时要返回的默认值。 Int128。

支持的参数：

(U)Int8/16/32/64/128/256。
Float32/64。
(U)Int8/16/32/128/256 的字符串表示。

为默认值返回的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt128OrDefault('0xc0fe', CAST('-1', 'Int128'));。

备注

如果输入值无法在 Int128 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 128 位整数值，否则返回传递的默认值，如果没有则返回 0。 Int128。

备注

该函数使用向零舍入，意味着它截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

参见

toInt128。
toInt128OrZero。
toInt128OrNull。

toInt256

将输入值转换为 Int256 类型的值。在出现错误时抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt256('0xc0fe');。

备注

如果输入值无法在 Int256 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

256 位整数值。 Int256。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toInt256OrZero。
toInt256OrNull。
toInt256OrDefault。

toInt256OrZero

像 toInt256 这个函数一样，将输入值转换为 Int256 类型的值，但在出现错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt256OrZero('0xc0fe');。

备注

如果输入值无法在 Int256 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 256 位整数值，否则返回 0。 Int256。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toInt256。
toInt256OrNull。
toInt256OrDefault。

toInt256OrNull

像 toInt256 这个函数一样，将输入值转换为 Int256 类型的值，但在出现错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt256OrNull('0xc0fe');。

备注

如果输入值无法在 Int256 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 256 位整数值，否则返回 NULL。 Int256 / NULL。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toInt256。
toInt256OrZero。
toInt256OrDefault。

toInt256OrDefault

像 toInt256 这个函数一样，将输入值转换为 Int256 类型的值，但在出现错误时返回默认值。如果未传递 default 值，则在出现错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default （可选）— 如果解析为 Int256 类型不成功时要返回的默认值。 Int256。

支持的参数：

(U)Int8/16/32/64/128/256 的值或字符串表示。
Float32/64 的值。

为默认值返回的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toInt256OrDefault('0xc0fe', CAST('-1', 'Int256'));。

备注

如果输入值无法在 Int256 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 256 位整数值，否则返回传递的默认值，如果没有则返回 0。 Int256。

备注

该函数使用向零舍入，意味着它截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

参见

toInt256。
toInt256OrZero。
toInt256OrNull。

toUInt8

将输入值转换为 UInt8 类型的值。如果出现错误则抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 型的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt8('0xc0fe');。

备注

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。例如：SELECT toUInt8(256) == 0;。

返回值

8 位无符号整数值。 UInt8。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt8OrZero。
toUInt8OrNull。
toUInt8OrDefault。

toUInt8OrZero

像 toUInt8 这个函数一样，将输入值转换为 UInt8 类型的值，但在出现错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

普通 Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt8OrZero('0xc0fe');。

备注

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 8 位无符号整数值，否则返回 0。 UInt8。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt8。
toUInt8OrNull。
toUInt8OrDefault。

toUInt8OrNull

像 toUInt8 这个函数一样，将输入值转换为 UInt8 类型的值，但在出现错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt8OrNull('0xc0fe');。

备注

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 8 位无符号整数值，否则返回 NULL。 UInt8 / NULL。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt8。
toUInt8OrZero。
toUInt8OrDefault。

toUInt8OrDefault

像 toUInt8 这个函数一样，将输入值转换为 UInt8 类型的值，但在出现错误时返回默认值。如果未传递 default 值，则在出现错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default （可选）— 如果解析为 UInt8 类型不成功时要返回的默认值。 UInt8。

支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值。

为默认值返回的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt8OrDefault('0xc0fe', CAST('0', 'UInt8'));。

备注

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 8 位无符号整数值，否则返回传递的默认值，如果没有则返回 0。 UInt8。

备注

该函数使用向零舍入，意味着它截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

参见

toUInt8。
toUInt8OrZero。
toUInt8OrNull。

toUInt16

将输入值转换为 UInt16 类型的值。如果出现错误则抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt16('0xc0fe');。

备注

如果输入值无法在 UInt16 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。例如：SELECT toUInt16(65536) == 0;。

返回值

16 位无符号整数值。 UInt16。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt16OrZero。
toUInt16OrNull。
toUInt16OrDefault。

toUInt16OrZero

像 toUInt16 这个函数一样，将输入值转换为 UInt16 类型的值，但在出现错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt16OrZero('0xc0fe');。

备注

如果输入值无法在 UInt16 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 16 位无符号整数值，否则返回 0。 UInt16。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt16。
toUInt16OrNull。
toUInt16OrDefault。

toUInt16OrNull

像 toUInt16 这个函数一样，将输入值转换为 UInt16 类型的值，但在出现错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt16OrNull('0xc0fe');。

备注

如果输入值无法在 UInt16 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 16 位无符号整数值，否则返回 NULL。 UInt16 / NULL。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt16。
toUInt16OrZero。
toUInt16OrDefault。

toUInt16OrDefault

像 toUInt16 这个函数一样，将输入值转换为 UInt16 类型的值，但在出现错误时返回默认值。如果未传递 default 值，则在出现错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default （可选）— 如果解析为 UInt16 类型不成功时要返回的默认值。 UInt16。

支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值。

为默认值返回的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt16OrDefault('0xc0fe', CAST('0', 'UInt16'));。

备注

如果输入值无法在 UInt16 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 16 位无符号整数值，否则返回传递的默认值，如果没有则返回 0。 UInt16。

备注

该函数使用向零舍入，意味着它截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

参见

toUInt16。
toUInt16OrZero。
toUInt16OrNull。

toUInt32

将输入值转换为 UInt32 类型的值。如果出现错误则抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt32('0xc0fe');。

备注

如果输入值无法在 UInt32 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。例如：SELECT toUInt32(4294967296) == 0;。

返回值

32 位无符号整数值。 UInt32。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt32OrZero。
toUInt32OrNull。
toUInt32OrDefault。

toUInt32OrZero

像 toUInt32 这个函数一样，将输入值转换为 UInt32 类型的值，但在出现错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt32OrZero('0xc0fe');。

备注

如果输入值无法在 UInt32 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 32 位无符号整数值，否则返回 0。UInt32

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt32。
toUInt32OrNull。
toUInt32OrDefault。

toUInt32OrNull

像 toUInt32 这个函数一样，将输入值转换为 UInt32 类型的值，但在出现错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt32OrNull('0xc0fe');。

备注

如果输入值无法在 UInt32 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

返回值

如果成功，返回 32 位无符号整数值，否则返回 NULL。 UInt32 / NULL。

备注

该函数使用向零舍入，意味着它截断数字的小数位。

示例

查询：

结果：

参见

toUInt32。
toUInt32OrZero。
toUInt32OrDefault。

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default（可选）— 如果解析为 UInt32 类型不成功时返回的默认值。 UInt32。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

返回默认值的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt32OrDefault('0xc0fe', CAST('0', 'UInt32'));。

备注

如果输入值无法在 UInt32 的范围内表示，则会发生结果的溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 32 位无符号整数值；如果失败，则返回传递的默认值或 0（如果没有传递）。 UInt32。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另请参阅

toUInt32.
toUInt32OrZero.
toUInt32OrNull.

toUInt64

将输入值转换为 UInt64 类型的值。如果发生错误，将抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值。

不支持的类型：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt64('0xc0fe');。

备注

如果输入值无法在 UInt64 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。例如：SELECT toUInt64(18446744073709551616) == 0;

返回值

64 位无符号整数值。 UInt64。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt64OrZero.
toUInt64OrNull.
toUInt64OrDefault.

toUInt64OrZero

像 toUInt64，这个函数将输入值转换为 UInt64 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt64OrZero('0xc0fe');。

备注

如果输入值无法在 UInt64 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 64 位无符号整数值；否则返回 0。 UInt64。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt64.
toUInt64OrNull.
toUInt64OrDefault.

toUInt64OrNull

像 toUInt64，这个函数将输入值转换为 UInt64 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。表达式 / 字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt64OrNull('0xc0fe');。

备注

如果输入值无法在 UInt64 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 64 位无符号整数值；否则返回 NULL。 UInt64 / NULL。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt64.
toUInt64OrZero.
toUInt64OrDefault.

toUInt64OrDefault

像 toUInt64，这个函数将输入值转换为 UInt64 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default（可选）— 如果解析为 UInt64 类型不成功时返回的默认值。 UInt64。

支持的参数：

(U)Int8/16/32/64/128/256 的值或字符串表示。
Float32/64 的值。

返回默认值的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt64OrDefault('0xc0fe', CAST('0', 'UInt64'));。

备注

如果输入值无法在 UInt64 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 64 位无符号整数值；否则返回传递的默认值（如果有）或 0（如果没有）。 UInt64。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另请参阅

toUInt64.
toUInt64OrZero.
toUInt64OrNull.

toUInt128

将输入值转换为 UInt128 类型的值。如果发生错误，将抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 的值或字符串表示。
Float32/64 类型的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt128('0xc0fe');。

备注

如果输入值无法在 UInt128 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

128 位无符号整数值。 UInt128。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt128OrZero.
toUInt128OrNull.
toUInt128OrDefault.

toUInt128OrZero

像 toUInt128，这个函数将输入值转换为 UInt128 类型的值，但在发生错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt128OrZero('0xc0fe');。

备注

如果输入值无法在 UInt128 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 128 位无符号整数值；否则返回 0。 UInt128。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt128.
toUInt128OrNull.
toUInt128OrDefault.

toUInt128OrNull

像 toUInt128，这个函数将输入值转换为 UInt128 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。表达式 / 字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt128OrNull('0xc0fe');。

备注

如果输入值无法在 UInt128 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 128 位无符号整数值；否则返回 NULL。 UInt128 / NULL。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt128.
toUInt128OrZero.
toUInt128OrDefault.

toUInt128OrDefault

像 toUInt128，这个函数将输入值转换为 UInt128 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default（可选）— 如果解析为 UInt128 类型不成功时返回的默认值。 UInt128。

支持的参数：

(U)Int8/16/32/64/128/256。
Float32/64。
(U)Int8/16/32/128/256 的字符串表示。

返回默认值的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt128OrDefault('0xc0fe', CAST('0', 'UInt128'));。

备注

如果输入值无法在 UInt128 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 128 位无符号整数值；否则返回传递的默认值（如果有）或 0（如果没有）。 UInt128。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另请参阅

toUInt128.
toUInt128OrZero.
toUInt128OrNull.

toUInt256

将输入值转换为 UInt256 类型的值。如果发生错误，将抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 的值或字符串表示。
Float32/64 类型的值。

不支持的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt256('0xc0fe');。

备注

如果输入值无法在 UInt256 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

256 位无符号整数值。 Int256。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt256OrZero.
toUInt256OrNull.
toUInt256OrDefault.

toUInt256OrZero

像 toUInt256，这个函数将输入值转换为 UInt256 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 0）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt256OrZero('0xc0fe');。

备注

如果输入值无法在 UInt256 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 256 位无符号整数值；否则返回 0。 UInt256。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt256.
toUInt256OrNull.
toUInt256OrDefault.

toUInt256OrNull

像 toUInt256，这个函数将输入值转换为 UInt256 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256 的字符串表示。

不支持的参数（返回 \N）：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt256OrNull('0xc0fe');。

备注

如果输入值无法在 UInt256 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 256 位无符号整数值；否则返回 NULL。 UInt256 / NULL。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。

示例

查询：

结果：

另请参阅

toUInt256.
toUInt256OrZero.
toUInt256OrDefault.

toUInt256OrDefault

像 toUInt256，这个函数将输入值转换为 UInt256 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default（可选）— 如果解析为 UInt256 类型不成功时返回的默认值。 UInt256。

支持的参数：

(U)Int8/16/32/64/128/256。
Float32/64。
(U)Int8/16/32/128/256 的字符串表示。

返回默认值的参数：

Float32/64 值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt256OrDefault('0xc0fe', CAST('0', 'UInt256'));。

备注

如果输入值无法在 UInt256 的范围内表示，则结果会产生溢出或下溢。这不被视为错误。

返回值

如果成功，则返回 256 位无符号整数值；否则返回传递的默认值（如果有）或 0（如果没有）。 UInt256。

备注

该函数采用四舍五入到零，意味着它会截断数字的小数位。
默认值类型应与转换类型相同。

示例

查询：

结果：

另请参阅

toUInt256.
toUInt256OrZero.
toUInt256OrNull.

toFloat32

将输入值转换为 Float32 类型的值。如果发生错误，将抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 的值。
(U)Int8/16/32/128/256 的字符串表示。
Float32/64 类型的值，包括 NaN 和 Inf。
Float32/64 的字符串表示，包括 NaN 和 Inf（不区分大小写）。

不支持的参数：

二进制和十六进制值的字符串表示，例如 SELECT toFloat32('0xc0fe');。

返回值

32 位浮点值。 Float32。

示例

查询：

结果：

另请参阅

toFloat32OrZero.
toFloat32OrNull.
toFloat32OrDefault.

toFloat32OrZero

像 toFloat32，这个函数将输入值转换为 Float32 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256、Float32/64 的字符串表示。

不支持的参数（返回 0）：

二进制和十六进制值的字符串表示，例如 SELECT toFloat32OrZero('0xc0fe');。

返回值

如果成功，则返回 32 位浮点值；否则返回 0。 Float32。

示例

查询：

结果：

另请参阅

toFloat32.
toFloat32OrNull.
toFloat32OrDefault.

toFloat32OrNull

像 toFloat32，这个函数将输入值转换为 Float32 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256、Float32/64 的字符串表示。

不支持的参数（返回 \N）：

二进制和十六进制值的字符串表示，例如 SELECT toFloat32OrNull('0xc0fe');。

返回值

如果成功，则返回 32 位浮点值；否则返回 \N。 Float32。

示例

查询：

结果：

另请参阅

toFloat32.
toFloat32OrZero.
toFloat32OrDefault.

toFloat32OrDefault

像 toFloat32，这个函数将输入值转换为 Float32 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式 / 字符串。
default（可选）— 如果解析为 Float32 类型不成功时返回的默认值。 Float32。

支持的参数：

(U)Int8/16/32/64/128/256 的值。
(U)Int8/16/32/128/256 的字符串表示。
Float32/64 类型的值，包括 NaN 和 Inf。
Float32/64 字符串表示，包括 NaN 和 Inf（不区分大小写）。

返回默认值的参数：

二进制和十六进制值的字符串表示，例如 SELECT toFloat32OrDefault('0xc0fe', CAST('0', 'Float32'));。

返回值

如果成功，则返回 32 位浮点值；否则返回传递的默认值（如果有）或 0（如果没有）。 Float32。

示例

查询：

结果：

另请参阅

toFloat32.
toFloat32OrZero.
toFloat32OrNull.

toFloat64

将输入值转换为 Float64 类型的值。如果发生错误，将抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。表达式。

支持的参数：

(U)Int8/16/32/64/128/256 的值。
(U)Int8/16/32/128/256 的字符串表示。
Float32/64 类型的值，包括 NaN 和 Inf。
Float32/64 的字符串表示，包括 NaN 和 Inf（不区分大小写）。

不支持的参数：

二进制和十六进制值的字符串表示，例如 SELECT toFloat64('0xc0fe');。

返回值

64 位浮点值。 Float64。

示例

查询：

结果：

另请参阅

toFloat64OrZero.
toFloat64OrNull.
toFloat64OrDefault.

toFloat64OrZero

像 toFloat64，这个函数将输入值转换为 Float64 类型的值，但在发生错误时返回 0。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256、Float32/64 的字符串表示。

不支持的参数（返回 0）：

二进制和十六进制值的字符串表示，例如 SELECT toFloat64OrZero('0xc0fe');。

返回值

如果成功，则返回 64 位浮点值；否则返回 0。 Float64。

示例

查询：

结果：

另请参阅

toFloat64.
toFloat64OrNull.
toFloat64OrDefault.

toFloat64OrNull

像 toFloat64，这个函数将输入值转换为 Float64 类型的值，但在发生错误时返回 NULL。

语法

参数

x — 数字的字符串表示。字符串。

支持的参数：

(U)Int8/16/32/128/256、Float32/64 的字符串表示。

不支持的参数（返回 \N）：

二进制和十六进制值的字符串表示，例如 SELECT toFloat64OrNull('0xc0fe');。

返回值

如果成功，则返回 64 位浮点值；否则返回 \N。 Float64。

示例

查询：

结果：

另请参阅

toFloat64.
toFloat64OrZero.
toFloat64OrDefault.

toFloat64OrDefault

与 toFloat64 相似，此函数将输入值转换为 Float64 类型的值，但在出现错误时返回默认值。如果没有传递 default 值，则在出现错误时返回 0。

语法

参数

expr — 返回数字或数字字符串表示的表达式。 Expression / String。
default （可选） — 解析为 Float64 类型失败时返回的默认值。 Float64。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值。
(U)Int8/16/32/128/256 的字符串表示。
类型为 Float32/64 的值，包括 NaN 和 Inf。
类型为 Float32/64 的字符串表示，包括 NaN 和 Inf（不区分大小写）。

返回默认值的参数：

二进制和十六进制值的字符串表示，例如 SELECT toFloat64OrDefault('0xc0fe', CAST('0', 'Float64'));。

返回值

如果成功则返回 64 位 Float 值，否则返回传递的默认值，如果没有则返回 0。 Float64。

示例

查询：

结果：

另见

toFloat64.
toFloat64OrZero.
toFloat64OrNull.

toBFloat16

将输入值转换为 BFloat16 类型的值。在出错时抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。 Expression。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值。
(U)Int8/16/32/128/256 的字符串表示。
类型为 Float32/64 的值，包括 NaN 和 Inf。
类型为 Float32/64 的字符串表示，包括 NaN 和 Inf（不区分大小写）。

返回值

16 位脑浮点值。 BFloat16。

示例

另见

toBFloat16OrZero.
toBFloat16OrNull.

toBFloat16OrZero

将字符串输入值转换为 BFloat16 类型的值。如果字符串不表示浮点值，则函数返回零。

语法

参数

x — 数字的字符串表示。 String。

支持的参数：

数字值的字符串表示。

不支持的参数（返回 0）：

二进制和十六进制值的字符串表示。
数值。

返回值

16 位脑浮点值，否则为 0。 BFloat16。

备注

该函数允许在从字符串表示转换时的精度无声损失。

示例

另见

toBFloat16.
toBFloat16OrNull.

toBFloat16OrNull

将字符串输入值转换为 BFloat16 类型的值。但如果字符串不表示浮点值，则该函数返回 NULL。

语法

参数

x — 数字的字符串表示。 String。

支持的参数：

数字值的字符串表示。

不支持的参数（返回 NULL）：

二进制和十六进制值的字符串表示。
数值。

返回值

16 位脑浮点值，否则为 NULL（\N）。 BFloat16。

备注

该函数允许在从字符串表示转换时的精度无声损失。

示例

另见

toBFloat16.
toBFloat16OrZero.

toDate

将参数转换为 Date 数据类型。

如果参数是 DateTime 或 DateTime64，它将被截断，并保留 DateTime 的日期部分：

如果参数是 String，它会被解析为 Date 或 DateTime。如果它被解析为 DateTime，则使用日期部分：

如果参数是一个数字，并且看起来像 UNIX 时间戳（大于 65535），则将其解释为 DateTime，然后在当前时区下截断为 Date。时区参数可以作为函数的第二个参数指定。截断为 Date 取决于时区：

以上示例演示了如何在不同的时区中，以相同的 UNIX 时间戳可以被解释为不同的日期。

如果参数是一个数字且小于 65536，则将其解释为自 1970-01-01（第一个 UNIX 天）以来的天数，并转换为 Date。它对应于 Date 数据类型的内部数值表示。示例：

此转换不依赖时区。

如果参数不适合 Date 类型的范围，则会导致实现定义的行为，可能饱和到支持的最大日期或溢出：

函数 toDate 也可以用其他形式书写：

toDateOrZero

与 toDate 相同，但在收到无效参数时返回 Date 的下边界。仅支持 String 参数。

示例

查询：

结果：

toDateOrNull

与 toDate 相同，但在收到无效参数时返回 NULL。仅支持 String 参数。

示例

查询：

结果：

toDateOrDefault

与 toDate 相同，但如果不成功，则返回默认值，该默认值为第二个参数（如果指定），否则为 Date 的下边界。

语法

示例

查询：

结果：

toDateTime

将输入值转换为 DateTime。

语法

参数

expr — 该值。 String, Int, Date 或 DateTime。
time_zone — 时区。 String。

备注

如果 expr 是一个数字，则它被解释为自 Unix 纪元开始以来的秒数（作为 Unix 时间戳）。如果 expr 是一个 String，它可以被解释为 Unix 时间戳或日期/时间的字符串表示。因此，短数字字符串表示（最多 4 位数字）的解析因歧义而被显式禁用，例如字符串 '1999' 可能既是年份（日期/ DateTime 的不完整字符串表示）或 Unix 时间戳。更长的数字字符串是允许的。

返回值

一个时间日期。 DateTime

示例

查询：

结果：

toDateTimeOrZero

与 toDateTime 相同，但在收到无效参数时返回 DateTime 的下边界。仅支持 String 参数。

示例

查询：

结果：

toDateTimeOrNull

与 toDateTime 相同，但在收到无效参数时返回 NULL。仅支持 String 参数。

示例

查询：

结果：

toDateTimeOrDefault

与 toDateTime 相同，但如果不成功，则返回默认值，该默认值可以是第三个参数（如果指定），否则为 DateTime 的下边界。

语法

示例

查询：

结果：

toDate32

将参数转换为 Date32 数据类型。如果值超出范围，toDate32 将返回 Date32 支持的边界值。如果参数具有 Date 类型，则考虑到其边界。

语法

参数

expr — 该值。 String, UInt32 或 Date。

返回值

一个日历日期。类型为 Date32。

示例

值在范围内：

值超出范围：

使用 Date 参数：

toDate32OrZero

与 toDate32 相同，但如果收到无效参数，则返回 Date32 的最小值。

示例

查询：

结果：

toDate32OrNull

与 toDate32 相同，但在收到无效参数时返回 NULL。

示例

查询：

结果：

toDate32OrDefault

将参数转换为 Date32 数据类型。如果值超出范围，toDate32OrDefault 将返回 Date32 支持的下边界值。如果参数具有 Date 类型，则考虑到其边界。如果收到无效参数，则返回默认值。

示例

查询：

结果：

toDateTime64

将输入值转换为 DateTime64 类型的值。

语法

参数

expr — 该值。 String, UInt32, Float 或 DateTime。
scale - 像素大小（精度）：10^-精度秒。有效范围：[ 0 : 9 ]。
timezone （可选） - 指定的 datetime64 对象的时区。

返回值

一个带有亚秒精度的日历日期和时间。 DateTime64。

示例

值在范围内：

作为具有精度的小数：

没有小数点，值仍被视为以秒为单位的 Unix 时间戳：

带有 timezone：

toDateTime64OrZero

与 toDateTime64 相同，此函数将输入值转换为 DateTime64 类型的值，但如果收到无效参数，则返回 DateTime64 的最小值。

语法

参数

expr — 该值。 String, UInt32, Float 或 DateTime。
scale - 像素大小（精度）：10^-精度秒。有效范围：[ 0 : 9 ]。
timezone （可选） - 指定的 DateTime64 对象的时区。

返回值

一个带有亚秒精度的日历日期和时间，否则为 [DateTime64]：1970-01-01 01:00:00.000 的最小值。 DateTime64。

示例

查询：

结果：

另见

toDateTime64.
toDateTime64OrNull.
toDateTime64OrDefault.

toDateTime64OrNull

与 toDateTime64 相同，此函数将输入值转换为 DateTime64 类型的值，但如果收到无效参数，则返回 NULL。

语法

参数

expr — 该值。 String, UInt32, Float 或 DateTime。
scale - 像素大小（精度）：10^-精度秒。有效范围：[ 0 : 9 ]。
timezone （可选） - 指定的 DateTime64 对象的时区。

返回值

一个带有亚秒精度的日历日期和时间，否则为 NULL。 DateTime64/NULL。

示例

查询：

结果：

另见

toDateTime64.
toDateTime64OrZero.
toDateTime64OrDefault.

toDateTime64OrDefault

与 toDateTime64 相同，此函数将输入值转换为 DateTime64 类型的值，但如果收到无效参数，则返回 DateTime64 的默认值或提供的默认值。

语法

参数

expr — 该值。 String, UInt32, Float 或 DateTime。
scale - 像素大小（精度）：10^-精度秒。有效范围：[ 0 : 9 ]。
timezone （可选） - 指定的 DateTime64 对象的时区。
default （可选） - 如果收到无效参数，则返回的默认值。 DateTime64。

返回值

一个带有亚秒精度的日历日期和时间，否则返回 [DateTime64] 的最小值或提供的 default 值（如果有）。 DateTime64。

示例

查询：

结果：

另见

toDateTime64.
toDateTime64OrZero.
toDateTime64OrNull.

toDecimal32

将输入值转换为类型为 Decimal(9, S) 的值，精度为 S。在发生错误时抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。 Expression。
S — 在 0 到 9 之间的精度参数，指定数字的小数部分可以有多少位数。 UInt8。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的值或字符串表示。
类型为 Float32/64 的值或字符串表示。

不支持的参数：

类型为 Float32/64 的值 NaN 和 Inf (不区分大小写) 的值或字符串表示。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal32('0xc0fe', 1);。

备注

如果 expr 的值超过 Decimal32 的边界：( -1 * 10^(9 - S), 1 * 10^(9 - S) )，则可能发生溢出。小数中的多余位数被丢弃（未四舍五入）。整数部分中的多余位数会导致异常。

危险

转换会丢弃额外的数字，并且在使用 Float32/Float64 输入时可能会以意想不到的方式操作，因为操作是使用浮点指令进行的。例如： toDecimal32(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中是 114.99。您可以使用字符串输入，这样操作会使用底层整数类型：toDecimal32('1.15', 2) = 1.15

返回值

类型为 Decimal(9, S) 的值。 Decimal32(S)。

示例

查询：

结果：

另见

toDecimal32OrZero.
toDecimal32OrNull.
toDecimal32OrDefault.

toDecimal32OrZero

与 toDecimal32 相同，此函数将输入值转换为类型为 Decimal(9, S) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 在 0 到 9 之间的精度参数，指定数字的小数部分可以有多少位数。 UInt8。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的字符串表示。
类型为 Float32/64 的字符串表示。

不支持的参数：

类型为 Float32/64 的值 NaN 和 Inf 的字符串表示。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal32OrZero('0xc0fe', 1);。

备注

如果 expr 的值超过 Decimal32 的边界：( -1 * 10^(9 - S), 1 * 10^(9 - S) )，则可能发生溢出。小数中的多余位数被丢弃（未四舍五入）。整数部分中的多余位数会导致错误。

返回值

如果成功，则返回类型为 Decimal(9, S) 的值，否则返回 0，并保留 S 位小数。 Decimal32(S)。

示例

查询：

结果：

另见

toDecimal32.
toDecimal32OrNull.
toDecimal32OrDefault.

toDecimal32OrNull

与 toDecimal32 相同，此函数将输入值转换为类型为 Nullable(Decimal(9, S)) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 在 0 到 9 之间的精度参数，指定数字的小数部分可以有多少位数。 UInt8。

支持的参数：

类型为 (U)Int8/16/32/64/128/256 的字符串表示。
类型为 Float32/64 的字符串表示。

不支持的参数：

类型为 Float32/64 的值 NaN 和 Inf 的字符串表示。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal32OrNull('0xc0fe', 1);。

备注

返回值

如果成功，则返回类型为 Nullable(Decimal(9, S)) 的值，否则返回相同类型的值 NULL。 Decimal32(S)。

示例

查询：

结果：

另见

toDecimal32.
toDecimal32OrZero.
toDecimal32OrDefault.

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 9 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。
default（可选）— 如果解析为 Decimal32(S) 类型失败，则返回的默认值。 Decimal32(S)。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal32OrDefault('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal32 的边界，则可能发生溢出：( -1 * 10^(9 - S), 1 * 10^(9 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致错误。

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal32OrDefault(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal32OrDefault('1.15', 2) = 1.15

返回值

如果成功，则返回类型为 Decimal(9, S) 的值，否则返回默认值（如果提供了）或 0（如果未提供）。 Decimal32(S)。

示例

查询：

结果：

另见

toDecimal32。
toDecimal32OrZero。
toDecimal32OrNull。

toDecimal64

将输入值转换为类型 Decimal(18, S) 的值，比例为 S。在发生错误时会抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。 Expression。
S — 范围在 0 到 18 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值或字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf（不区分大小写）。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal64('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal64 的边界，则可能发生溢出：( -1 * 10^(18 - S), 1 * 10^(18 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致异常。

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal64(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal64('1.15', 2) = 1.15

返回值

类型为 Decimal(18, S) 的值。 Decimal64(S)。

示例

查询：

结果：

另见

toDecimal64OrZero。
toDecimal64OrNull。
toDecimal64OrDefault。

toDecimal64OrZero

与 toDecimal64 类似，此函数将输入值转换为 Decimal(18, S) 类型的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 18 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal64OrZero('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal64 的边界，则可能发生溢出：( -1 * 10^(18 - S), 1 * 10^(18 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致错误。

返回值

如果成功，则返回类型为 Decimal(18, S) 的值，否则返回 0，带有 S 位小数。 Decimal64(S)。

示例

查询：

结果：

另见

toDecimal64。
toDecimal64OrNull。
toDecimal64OrDefault。

toDecimal64OrNull

与 toDecimal64 类似，此函数将输入值转换为类型 Nullable(Decimal(18, S)) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 18 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal64OrNull('0xc0fe', 1);。

备注

返回值

如果成功，则返回类型为 Nullable(Decimal(18, S)) 的值，否则返回同类型的值 NULL。 Decimal64(S)。

示例

查询：

结果：

另见

toDecimal64。
toDecimal64OrZero。
toDecimal64OrDefault。

toDecimal64OrDefault

与 toDecimal64 类似，此函数将输入值转换为类型 Decimal(18, S) 的值，但在发生错误时返回默认值。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 18 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。
default（可选）— 如果解析为 Decimal64(S) 类型失败，则返回的默认值。 Decimal64(S)。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal64OrDefault('0xc0fe', 1);。

备注

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal64OrDefault(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal64OrDefault('1.15', 2) = 1.15

返回值

如果成功，则返回类型为 Decimal(18, S) 的值，否则返回提供的默认值，若未提供则返回 0。 Decimal64(S)。

示例

查询：

结果：

另见

toDecimal64。
toDecimal64OrZero。
toDecimal64OrNull。

toDecimal128

将输入值转换为类型 Decimal(38, S) 的值，比例为 S。在发生错误时会抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。 Expression。
S — 范围在 0 到 38 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值或字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf（不区分大小写）。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal128('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal128 的边界，则可能发生溢出：( -1 * 10^(38 - S), 1 * 10^(38 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致异常。

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal128(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal128('1.15', 2) = 1.15

返回值

类型为 Decimal(38, S) 的值。 Decimal128(S)。

示例

查询：

结果：

另见

toDecimal128OrZero。
toDecimal128OrNull。
toDecimal128OrDefault。

toDecimal128OrZero

与 toDecimal128 类似，此函数将输入值转换为类型 Decimal(38, S) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 38 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal128OrZero('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal128 的边界，则可能发生溢出：( -1 * 10^(38 - S), 1 * 10^(38 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致错误。

返回值

如果成功，则返回类型为 Decimal(38, S) 的值，否则返回 0，带有 S 位小数。 Decimal128(S)。

示例

查询：

结果：

另见

toDecimal128。
toDecimal128OrNull。
toDecimal128OrDefault。

toDecimal128OrNull

与 toDecimal128 类似，此函数将输入值转换为类型 Nullable(Decimal(38, S)) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 38 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal128OrNull('0xc0fe', 1);。

备注

返回值

如果成功，则返回类型为 Nullable(Decimal(38, S)) 的值，否则返回同类型的值 NULL。 Decimal128(S)。

示例

查询：

结果：

另见

toDecimal128。
toDecimal128OrZero。
toDecimal128OrDefault。

toDecimal128OrDefault

与 toDecimal128 类似，此函数将输入值转换为类型 Decimal(38, S) 的值，但在发生错误时返回默认值。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 38 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。
default（可选）— 如果解析为 Decimal128(S) 类型失败，则返回的默认值。 Decimal128(S)。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal128OrDefault('0xc0fe', 1);。

备注

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal128OrDefault(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal128OrDefault('1.15', 2) = 1.15

返回值

如果成功，则返回类型为 Decimal(38, S) 的值，否则返回提供的默认值，若未提供则返回 0。 Decimal128(S)。

示例

查询：

结果：

另见

toDecimal128。
toDecimal128OrZero。
toDecimal128OrNull。

toDecimal256

将输入值转换为类型 Decimal(76, S) 的值，比例为 S。在发生错误时会抛出异常。

语法

参数

expr — 返回数字或数字字符串表示的表达式。 Expression。
S — 范围在 0 到 76 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的值或字符串表示。
Float32/64 类型的值或字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf（不区分大小写）。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal256('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal256 的边界，则可能发生溢出：( -1 * 10^(76 - S), 1 * 10^(76 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致异常。

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal256(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal256('1.15', 2) = 1.15

返回值

类型为 Decimal(76, S) 的值。 Decimal256(S)。

示例

查询：

结果：

另见

toDecimal256OrZero。
toDecimal256OrNull。
toDecimal256OrDefault。

toDecimal256OrZero

与 toDecimal256 类似，此函数将输入值转换为类型 Decimal(76, S) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 76 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal256OrZero('0xc0fe', 1);。

备注

如果 expr 的值超出了 Decimal256 的边界，则可能发生溢出：( -1 * 10^(76 - S), 1 * 10^(76 - S) )。小数部分的多余位数会被丢弃（而不是四舍五入）。整数部分的多余位数会导致错误。

返回值

如果成功，则返回类型为 Decimal(76, S) 的值，否则返回 0，带有 S 位小数。 Decimal256(S)。

示例

查询：

结果：

另见

toDecimal256。
toDecimal256OrNull。
toDecimal256OrDefault。

toDecimal256OrNull

与 toDecimal256 类似，此函数将输入值转换为类型 Nullable(Decimal(76, S)) 的值，但在发生错误时返回 0。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 76 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal256OrNull('0xc0fe', 1);。

备注

返回值

如果成功，则返回类型为 Nullable(Decimal(76, S)) 的值，否则返回同类型的值 NULL。 Decimal256(S)。

示例

查询：

结果：

另见

toDecimal256。
toDecimal256OrZero。
toDecimal256OrDefault。

toDecimal256OrDefault

与 toDecimal256 类似，此函数将输入值转换为类型 Decimal(76, S) 的值，但在发生错误时返回默认值。

语法

参数

expr — 数字的字符串表示。 String。
S — 范围在 0 到 76 之间的比例参数，指定数字的小数部分可以有多少位。 UInt8。
default（可选）— 如果解析为 Decimal256(S) 类型失败，则返回的默认值。 Decimal256(S)。

受支持的参数：

(U)Int8/16/32/64/128/256 类型的字符串表示。
Float32/64 类型的字符串表示。

不支持的参数：

Float32/64 值的字符串表示 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toDecimal256OrDefault('0xc0fe', 1);。

备注

危险

在处理 Float32/Float64 输入时，转换会丢弃多余的位数，并可能以意想不到的方式执行，因为操作是使用浮点指令执行的。例如：toDecimal256OrDefault(1.15, 2) 等于 1.14，因为 1.15 * 100 在浮点中为 114.99。您可以使用字符串输入，以便操作使用底层整数类型：toDecimal256OrDefault('1.15', 2) = 1.15

返回值

如果成功，则返回类型为 Decimal(76, S) 的值，否则返回提供的默认值，若未提供则返回 0。 Decimal256(S)。

示例

查询：

结果：

另见

toDecimal256。
toDecimal256OrZero。
toDecimal256OrNull。

toString

用于在数字、字符串（但不固定字符串）、日期和带时间的日期之间转换的函数。所有这些函数接受一个参数。

在转换为字符串或从字符串转换时，值使用与 TabSeparated 格式（以及几乎所有其他文本格式）相同的规则进行格式化或解析。如果字符串无法解析，则会抛出异常并取消请求。

在将日期转换为数字或反之时，日期对应于自 Unix 纪元开始以来的天数。在将带时间的日期转换为数字或反之时，带时间的日期对应于自 Unix 纪元开始以来的秒数。

toDate/toDateTime 函数的日期和带时间日期格式定义如下：

作为例外，当从 UInt32、Int32、UInt64 或 Int64 数字类型转换为日期时，如果数字大于或等于 65536，则该数字被解释为 Unix 时间戳（而不是天数），并被四舍五入到日期。这支持了常见的情况，即写 toDate(unix_timestamp)，否则将出错，并需要编写更繁琐的 toDate(toDateTime(unix_timestamp))。

日期和带时间的日期之间的转换以自然方式进行：通过添加空时间或丢弃时间。

数字类型之间的转换使用与 C++ 中不同数字类型之间的赋值相同的规则。

此外，DateTime 参数的 toString 函数可以接受第二个字符串参数，其中包含时区的名称。例如：Asia/Yekaterinburg。在这种情况下，时间会按照指定的时区进行格式化。

示例

查询：

结果：

另见 toUnixTimestamp 函数。

参数

s — 要转换为固定字符串的字符串。 String。
N — 长度 N。 UInt8

返回值

一个长度为 N 的固定字符串，内容为 s。 FixedString。

示例

查询：

结果：

toStringCutToZero

接受一个 String 或 FixedString 参数。返回内容在找到的第一个零字节位置截断的字符串。

语法

示例

查询：

结果：

查询：

结果：

toDecimalString

将一个数值转换为字符串，输出的小数位数由用户指定。

语法

参数

number — 要表示为字符串的值， Int, UInt, Float, Decimal。
scale — 小数位数， UInt8。
- Decimal 和 Int, UInt 类型的最大精度为 77（这是 Decimal 的最大有效数字位数），
- Float 的最大精度为 60。

返回值

输入值表示为 String，带有给定的小数位数（scale）。如果请求的尺度小于原始数字的尺度，则按照通常的算术规则对数字进行四舍五入。

示例

查询：

结果：

reinterpretAsUInt8

通过将输入值视为 UInt8 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 UInt8 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 UInt8。 UInt8。

示例

查询：

结果：

reinterpretAsUInt16

通过将输入值视为 UInt16 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 UInt16 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 UInt16。 UInt16。

示例

查询：

结果：

reinterpretAsUInt32

通过将输入值视为 UInt32 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 UInt32 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 UInt32。 UInt32。

示例

查询：

结果：

reinterpretAsUInt64

通过将输入值视为 UInt64 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 UInt64 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 UInt64。 UInt64。

示例

查询：

结果：

reinterpretAsUInt128

通过将输入值视为 UInt128 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 UInt128 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 UInt128。 UInt128。

示例

查询：

结果：

reinterpretAsUInt256

通过将输入值视为 UInt256 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 UInt256 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 UInt256。 UInt256。

示例

查询：

结果：

reinterpretAsInt8

通过将输入值视为 Int8 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Int8 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Int8。 Int8。

示例

查询：

结果：

reinterpretAsInt16

通过将输入值视为 Int16 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Int16 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Int16。 Int16。

示例

查询：

结果：

reinterpretAsInt32

通过将输入值视为 Int32 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Int32 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Int32。 Int32。

示例

查询：

结果：

reinterpretAsInt64

通过将输入值视为 Int64 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Int64 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Int64。 Int64。

示例

查询：

结果：

reinterpretAsInt128

通过将输入值视为 Int128 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Int128 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Int128。 Int128。

示例

查询：

结果：

reinterpretAsInt256

通过将输入值视为 Int256 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Int256 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Int256。 Int256。

示例

查询：

结果：

reinterpretAsFloat32

通过将输入值视为 Float32 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Float32 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Float32。 Float32。

示例

查询：

结果：

reinterpretAsFloat64

通过将输入值视为 Float64 类型的值来执行字节重解释。与 CAST 不同，该函数不尝试保留原始值 - 如果目标类型无法表示输入类型，则输出是没有意义的。

语法

参数

x: 要重解释为 Float64 的值。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

将值 x 重新解释为 Float64。 Float64。

示例

查询：

结果：

reinterpretAsDate

接受一个字符串、固定字符串或数值，并将字节解释为一个主机顺序（小端）。返回从解释的数字表示的日期，表示为自 Unix 纪元开始的天数。

语法

参数

x: 自 Unix 纪元开始的天数。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

日期。 Date。

实现细节

备注

如果提供的字符串不足，则该函数的工作方式如下：假设字符串用所需数量的空字节进行填充。如果字符串长度超过了需要的长度，则额外的字节将被忽略。

示例

查询：

结果：

reinterpretAsDateTime

这些函数接受一个字符串，并将字符串开始位置的字节解释为主机顺序（小端）的数字。返回的日期时间表示为自 Unix 纪元开始的秒数。

语法

参数

x: 自 Unix 纪元开始的秒数。(U)Int*, Float, Date, DateTime, UUID, String 或 FixedString。

返回值

日期和时间。 DateTime。

实现细节

备注

示例

查询：

结果：

reinterpretAsString

该函数接受一个数字、日期或日期时间，并返回一个字符串，包含表示相应值的字节，采用主机顺序（小端）。末尾的空字节被丢弃。例如，一个 UInt32 类型的值 255 是一个字节长的字符串。

语法

参数

x: 要重新解释为字符串的值。(U)Int*, Float, Date, DateTime。

返回值

包含表示 x 的字节的字符串。 String。

示例

查询：

结果：

reinterpretAsFixedString

该函数接受一个数字、日期或日期时间，并返回一个 FixedString，包含表示相应值的字节，采用主机顺序（小端）。末尾的空字节被丢弃。例如，一个 UInt32 类型的值 255 是一个长度为一个字节的 FixedString。

语法

参数

x: 要重新解释为字符串的值。(U)Int*, Float, Date, DateTime。

返回值

包含表示 x 的字节的固定字符串。 FixedString。

示例

查询：

结果：

reinterpretAsUUID

备注

除这里列出的 UUID 函数外，还有专门的 UUID 函数文档。

接受一个 16 字节的字符串，并通过将每个 8 字节的半部分以小端字节顺序解释为 UUID。如果字符串长度不足，则该函数的工作方式如下：假设字符串用所需数量的空字节进行填充。如果字符串超过 16 字节，末尾的额外字节将被忽略。

语法

参数

fixed_string — 大端字节字符串。 FixedString。

返回值

UUID 类型的值。 UUID。

示例

将字符串转换为 UUID。

查询：

结果：

在字符串与 UUID 之间相互转换。

查询：

结果：

reinterpret

使用 x 值中的相同源内存字节序列，并将其重新解释为目标类型。

语法

参数

x — 任何类型。
type — 目标类型。 String。

返回值

目标类型的值。

示例

查询：

结果：

CAST

将输入值转换为指定的数据类型。与 reinterpret 函数不同，CAST 尝试用新数据类型表示相同的值。如果转换无法完成，则会抛出异常。支持多种语法变体。

语法

参数

x — 要转换的值。可以是任何类型。
T — 目标数据类型的名称。 String。
t — 目标数据类型。

返回值

转换后的值。

备注

如果输入值不符合目标类型的范围，则结果将溢出。例如，CAST(-1, 'UInt8') 返回 255。

示例

查询：

结果：

查询：

结果：

转换为 FixedString (N) 仅适用于 String 或 FixedString 类型的参数。

类型转换为 Nullable 并且可以返回。

示例

查询：

结果：

查询：

结果：

另见

cast_keep_nullable 设置

accurateCast(x, T)

将 x 转换为 T 数据类型。

与 cast 的不同之处在于 accurateCast 不允许在转换时对数字类型溢出，如果值 x 不符合类型 T 的范围，则会抛出异常。例如，accurateCast(-1, 'UInt8') 会抛出异常。

示例

查询：

结果：

查询：

结果：

accurateCastOrNull(x, T)

将输入值 x 转换为指定的数据类型 T。始终返回 Nullable 类型，如果转换值在目标类型中无法表示，则返回 NULL。

语法

参数

x — 输入值。
T — 返回数据类型的名称。

返回值

转换为指定数据类型 T 的值。

示例

查询：

结果：

查询：

结果：

accurateCastOrDefault(x, T[, default_value])

将输入值 x 转换为指定的数据类型 T。如果转换值无法表示为目标类型，则返回默认类型值或指定的 default_value。

语法

参数

x — 输入值。
T — 返回数据类型的名称。
default_value — 返回数据类型的默认值。

返回值

转换为指定数据类型 T 的值。

示例

查询：

结果：

查询：

结果：

toIntervalYear

返回 n 年的时间间隔，数据类型为 IntervalYear。

语法

参数

n — 年的数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 年的时间间隔。 IntervalYear。

示例

查询：

结果：

toIntervalQuarter

返回 n 季度的时间间隔，数据类型为 IntervalQuarter。

语法

参数

n — 季度的数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 季度的时间间隔。 IntervalQuarter。

示例

查询：

结果：

toIntervalMonth

返回 n 个月的时间间隔，数据类型为 IntervalMonth。

语法

参数

n — 月份的数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 个月的时间间隔。 IntervalMonth。

示例

查询：

结果：

toIntervalWeek

返回 n 个星期的时间间隔，数据类型为 IntervalWeek。

语法

参数

n — 星期的数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 个星期的时间间隔。 IntervalWeek。

示例

查询：

结果：

toIntervalDay

返回 n 天的时间间隔，数据类型为 IntervalDay。

语法

参数

n — 天的数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 天的时间间隔。 IntervalDay。

示例

查询：

结果：

toIntervalHour

返回 n 小时的时间间隔，数据类型为 IntervalHour。

语法

参数

n — 小时数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 小时的时间间隔。 IntervalHour。

示例

查询：

结果：

toIntervalMinute

返回 n 分钟的时间间隔，数据类型为 IntervalMinute。

语法

参数

n — 分钟数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 分钟的时间间隔。 IntervalMinute。

示例

查询：

结果：

toIntervalSecond

返回 n 秒的时间间隔，数据类型为 IntervalSecond。

语法

参数

n — 秒的数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 秒的时间间隔。 IntervalSecond。

示例

查询：

结果：

toIntervalMillisecond

返回 n 毫秒的时间间隔，数据类型为 IntervalMillisecond。

语法

参数

n — 毫秒数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 毫秒的时间间隔。 IntervalMilliseconds。

示例

查询：

结果：

toIntervalMicrosecond

返回 n 微秒的时间间隔，数据类型为 IntervalMicrosecond。

语法

参数

n — 微秒数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 微秒的时间间隔。 IntervalMicrosecond。

示例

查询：

结果：

toIntervalNanosecond

返回 n 纳秒的时间间隔，数据类型为 IntervalNanosecond。

语法

参数

n — 纳秒数量。整数或其字符串表示，以及浮点数。(U)Int*/Float*/String。

返回值

n 纳秒的时间间隔。 IntervalNanosecond。

示例

查询：

结果：

parseDateTime

将 String 转换为 DateTime，遵循 MySQL 格式字符串。

此函数是 formatDateTime 函数的反操作。

语法

参数

str — 待解析的字符串
format — 格式字符串。可选。如果未指定，则为 %Y-%m-%d %H:%i:%s。
timezone — 时区。可选。

返回值

根据 MySQL 风格格式字符串解析的 DateTime 值。

支持的格式说明符

所有在 formatDateTime 中列出的格式说明符，除了：

%Q: 季度 (1-4)

示例

别名： TO_TIMESTAMP。

parseDateTimeOrZero

同 parseDateTime 函数，除了在遇到无法处理的日期格式时返回零日期。

parseDateTimeOrNull

同 parseDateTime 函数，除了在遇到无法处理的日期格式时返回 NULL。

别名： str_to_date。

parseDateTimeInJodaSyntax

类似于 parseDateTime，除了格式字符串是 Joda，而不是 MySQL 语法。

此函数是 formatDateTimeInJodaSyntax 函数的反操作。

语法

参数

str — 待解析的字符串
format — 格式字符串。可选。如果未指定，则为 yyyy-MM-dd HH:mm:ss。
timezone — 时区。可选。

返回值

根据 Joda 风格格式字符串解析的 DateTime 值。

支持的格式说明符

在 formatDateTimeInJoda 中列出的所有格式说明符都受支持，除了：

S: 秒的小数部分
z: 时区
Z: 时区偏移/标识

示例

parseDateTimeInJodaSyntaxOrZero

同 parseDateTimeInJodaSyntax，除了在遇到无法处理的日期格式时返回零日期。

parseDateTimeInJodaSyntaxOrNull

同 parseDateTimeInJodaSyntax，除了在遇到无法处理的日期格式时返回 NULL。

parseDateTime64

将 String 转换为 DateTime64，遵循一个 MySQL 格式字符串。

语法

参数

str — 待解析的字符串。
format — 格式字符串。可选。如果未指定，则为 %Y-%m-%d %H:%i:%s.%f。
timezone — 时区。可选。

返回值

根据 MySQL 风格格式字符串解析的 DateTime64 值。返回值的精度为 6。

parseDateTime64OrZero

同 parseDateTime64，除了在遇到无法处理的日期格式时返回零日期。

parseDateTime64OrNull

同 parseDateTime64，除了在遇到无法处理的日期格式时返回 NULL。

parseDateTime64InJodaSyntax

将 String 转换为 DateTime64，遵循一个 Joda 格式字符串。

语法

参数

str — 待解析的字符串。
format — 格式字符串。可选。如果未指定，则为 yyyy-MM-dd HH:mm:ss。
timezone — 时区。可选。

返回值

根据 Joda 风格格式字符串解析的 DateTime64 值。返回值的精度等于格式字符串中 S 占位符的数量（但最多为 6）。

parseDateTime64InJodaSyntaxOrZero

同 parseDateTime64InJodaSyntax，除了在遇到无法处理的日期格式时返回零日期。

parseDateTime64InJodaSyntaxOrNull

同 parseDateTime64InJodaSyntax，除了在遇到无法处理的日期格式时返回 NULL。

parseDateTimeBestEffort

parseDateTime32BestEffort

将 String 表示形式的日期和时间转换为 DateTime 数据类型。

该函数解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 日期和时间规范、ClickHouse 及其他一些日期和时间格式。

语法

参数

time_string — 包含要转换的日期和时间的字符串。 String。
time_zone — 时区。该函数根据时区解析 time_string。 String。

支持的非标准格式

包含 9..10 位 unix 时间戳的字符串。
含有日期和时间成分的字符串：YYYYMMDDhhmmss、DD/MM/YYYY hh:mm:ss、DD-MM-YY hh:mm、YYYY-MM-DD hh:mm:ss 等。
含有日期但没有时间成分的字符串：YYYY、YYYYMM、YYYY*MM、DD/MM/YYYY、DD-MM-YY 等。
含有天和时间的字符串：DD、DD hh、DD hh:mm。在这种情况下，MM 由 01 替代。
包含日期和时间以及时区偏移信息的字符串：YYYY-MM-DD hh:mm:ss ±h:mm 等。例如，2020-12-12 17:36:00 -5:00。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

对于所有有分隔符的格式，函数解析月份名称，以其全名或月份名称的前三个字母表示。例子：24/DEC/18、24-Dec-18、01-September-2018。如果未指定年份，则认为等于当前年份。如果结果的 DateTime 发生在未来（即使是当前时刻之后的一秒），则用前一年代替当前年份。

返回值

转换后的 DateTime 数据类型的 time_string。

示例

查询：

结果：

查询：

结果：

查询：

结果：

查询：

结果：

查询：

结果：

查询：

结果：

参见

parseDateTimeBestEffortUS

此函数的行为与 parseDateTimeBestEffort 函数相同，针对 ISO 日期格式，例如 YYYY-MM-DD hh:mm:ss，以及其他日期格式，其中月份和日期组件可以不含歧义地提取，例如 YYYYMMDDhhmmss、YYYY-MM、DD hh 或 YYYY-MM-DD hh:mm:ss ±h:mm。如果月份和日期组件不能不含歧义地提取，例如 MM/DD/YYYY、MM-DD-YYYY 或 MM-DD-YY，它将优先选择美国日期格式，而不是 DD/MM/YYYY、DD-MM-YYYY 或 DD-MM-YY。作为后者的例外，如果月份大于 12 且小于或等于 31，则该函数回退到 parseDateTimeBestEffort 的行为，例如 15/08/2020 将被解析为 2020-08-15。

parseDateTimeBestEffortOrNull

parseDateTime32BestEffortOrNull

同 parseDateTimeBestEffort ，除了在遇到无法处理的日期格式时返回 NULL。

parseDateTimeBestEffortOrZero

parseDateTime32BestEffortOrZero

同 parseDateTimeBestEffort ，除了在遇到无法处理的日期格式时返回零日期或零日期时间。

parseDateTimeBestEffortUSOrNull

同 parseDateTimeBestEffortUS 函数，除了在遇到无法处理的日期格式时返回 NULL。

parseDateTimeBestEffortUSOrZero

同 parseDateTimeBestEffortUS 函数，除了在遇到无法处理的日期格式时返回零日期（1970-01-01）或零日期与时间（1970-01-01 00:00:00）。

parseDateTime64BestEffort

同 parseDateTimeBestEffort 函数，但还解析毫秒和微秒并返回 DateTime 数据类型。

语法

参数

time_string — 包含日期或日期时间的字符串。 String。
precision — 必需精度。3 — 表示毫秒，6 — 表示微秒。默认为 3。可选。 UInt8。
time_zone — 时区。该函数根据时区解析 time_string。可选。 String。

返回值

转换后的 DateTime 数据类型。

示例

查询：

结果：

parseDateTime64BestEffortUS

同 parseDateTime64BestEffort 函数，除了在模棱两可的情况下优先选择美国日期格式（MM/DD/YYYY 等）。

parseDateTime64BestEffortOrNull

同 parseDateTime64BestEffort 函数，除了在遇到无法处理的日期格式时返回 NULL。

parseDateTime64BestEffortOrZero

同 parseDateTime64BestEffort 函数，除了在遇到无法处理的日期格式时返回零日期或零日期时间。

parseDateTime64BestEffortUSOrNull

同 parseDateTime64BestEffort 函数，除了在模棱两可的情况下优先选择美国日期格式（MM/DD/YYYY 等），并在遇到无法处理的日期格式时返回 NULL。

parseDateTime64BestEffortUSOrZero

同 parseDateTime64BestEffort 函数，除了在模棱两可的情况下优先选择美国日期格式（MM/DD/YYYY 等），并在遇到无法处理的日期格式时返回零日期或零日期时间。

toLowCardinality

将输入参数转换为相同数据类型的 LowCardinality 版本。

要将数据从 LowCardinality 数据类型转换，请使用 CAST 函数。例如： CAST(x as String)。

语法

参数

expr — 结果为一种受支持的数据类型的表达式。

返回值

expr 的结果。 LowCardinality 类型的 expr。

示例

查询：

结果：

toUnixTimestamp64Second

将 DateTime64 转换为具有固定秒精度的 Int64 值。输入值根据其精度适当缩放。

备注

输出值为 UTC 时间戳，而不是 DateTime64 的时区。

语法

参数

value — 具有任意精度的 DateTime64 值。 DateTime64。

返回值

转换为 Int64 数据类型的 value。 Int64。

示例

查询：

结果：

toUnixTimestamp64Milli

将 DateTime64 转换为具有固定毫秒精度的 Int64 值。输入值根据其精度适当缩放。

备注

输出值为 UTC 时间戳，而不是 DateTime64 的时区。

语法

参数

value — 具有任意精度的 DateTime64 值。 DateTime64。

返回值

转换为 Int64 数据类型的 value。 Int64。

示例

查询：

结果：

toUnixTimestamp64Micro

将 DateTime64 转换为具有固定微秒精度的 Int64 值。输入值根据其精度适当缩放。

备注

输出值为 UTC 时间戳，而不是 DateTime64 的时区。

语法

参数

value — 具有任意精度的 DateTime64 值。 DateTime64。

返回值

转换为 Int64 数据类型的 value。 Int64。

示例

查询：

结果：

toUnixTimestamp64Nano

将 DateTime64 转换为具有固定纳秒精度的 Int64 值。输入值根据其精度适当缩放。

备注

输出值为 UTC 时间戳，而不是 DateTime64 的时区。

语法

参数

value — 具有任意精度的 DateTime64 值。 DateTime64。

返回值

转换为 Int64 数据类型的 value。 Int64。

示例

查询：

结果：

fromUnixTimestamp64Second

将 Int64 转换为具有固定秒精度和可选时区的 DateTime64 值。输入值根据其精度适当缩放。

备注

请注意，输入值被视为 UTC 时间戳，而不是给定（或隐式）时区的时间戳。

语法

参数

value — 任意精度的值。 Int64.
timezone — （可选）结果的时区名称。 String.

返回值

将 value 转换为具有精度 0 的 DateTime64。 DateTime64.

示例

查询:

结果:

fromUnixTimestamp64Milli

将 Int64 转换为具有固定毫秒精度和可选时区的 DateTime64 值。输入值根据其精度适当缩放。

备注

请注意，输入值被视为 UTC 时间戳，而不是给定（或隐式）时区的时间戳。

语法

参数

value — 任意精度的值。 Int64.
timezone — （可选）结果的时区名称。 String.

返回值

将 value 转换为具有精度 3 的 DateTime64。 DateTime64.

示例

查询:

结果:

fromUnixTimestamp64Micro

将 Int64 转换为具有固定微秒精度和可选时区的 DateTime64 值。输入值根据其精度适当缩放。

备注

请注意，输入值被视为 UTC 时间戳，而不是给定（或隐式）时区的时间戳。

语法

参数

value — 任意精度的值。 Int64.
timezone — （可选）结果的时区名称。 String.

返回值

将 value 转换为具有精度 6 的 DateTime64。 DateTime64.

示例

查询:

结果:

fromUnixTimestamp64Nano

将 Int64 转换为具有固定纳秒精度和可选时区的 DateTime64 值。输入值根据其精度适当缩放。

备注

请注意，输入值被视为 UTC 时间戳，而不是给定（或隐式）时区的时间戳。

语法

参数

value — 任意精度的值。 Int64.
timezone — （可选）结果的时区名称。 String.

返回值

将 value 转换为具有精度 9 的 DateTime64。 DateTime64.

示例

查询:

结果:

formatRow

将任意表达式转换为通过给定格式生成的字符串。

语法

参数

format — 文本格式。例如 CSV, TSV.
x,y, ... — 表达式。

返回值

格式化的字符串。（对于文本格式，通常以换行符结束）。

示例

查询:

结果:

注意: 如果格式包含后缀/前缀，它将在每一行中写入。

示例

查询:

结果:

注意: 该函数仅支持基于行的格式。

formatRowNoNewline

将任意表达式转换为通过给定格式生成的字符串。与 formatRow 的区别在于该函数会修剪最后一个 \n（如果有的话）。

语法

参数

format — 文本格式。例如 CSV, TSV.
x,y, ... — 表达式。

返回值

格式化的字符串。

示例

查询:

结果:

数据转换的常见问题​

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​

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​

toDecimal64​

数据转换的常见问题

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

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

toDecimal64