类型转换函数

数据转换中的常见问题

to<type> 函数和 cast 在某些情况下行为不同，例如在使用 LowCardinality 时：cast 会移除 LowCardinality 特征，而 to<type> 函数则不会。对于 Nullable 也是如此。这种行为与 SQL 标准不兼容，可以通过 cast_keep_nullable 设置进行调整。

注意

当某种数据类型的值被转换为更小的数据类型（例如从 Int64 转为 Int32）或在不兼容的数据类型之间转换（例如从 String 转为 Int）时，要注意可能发生的数据丢失。请务必仔细检查转换结果是否符合预期。

示例：

SELECT
    toTypeName(toLowCardinality('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type

┌─source_type────────────┬─to_type_result_type────┬─cast_result_type─┐
│ LowCardinality(String) │ LowCardinality(String) │ String           │
└────────────────────────┴────────────────────────┴──────────────────┘

SELECT
    toTypeName(toNullable('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ String           │
└──────────────────┴─────────────────────┴──────────────────┘

SELECT
    toTypeName(toNullable('') AS val) AS source_type,
    toTypeName(toString(val)) AS to_type_result_type,
    toTypeName(CAST(val, 'String')) AS cast_result_type
SETTINGS cast_keep_nullable = 1

┌─source_type──────┬─to_type_result_type─┬─cast_result_type─┐
│ Nullable(String) │ Nullable(String)    │ Nullable(String) │
└──────────────────┴─────────────────────┴──────────────────┘

关于 `toString` 函数的说明

toString 函数族用于在数字、字符串（但不包括定长字符串）、日期以及带时间的日期之间进行转换。所有这些函数都只接受一个参数。

在与字符串之间进行转换时，值的格式化或解析使用与 TabSeparated 格式（以及几乎所有其他文本格式）相同的规则。如果字符串无法解析，则会抛出异常并取消请求。
在日期与数字之间互相转换时，日期对应于自 Unix 纪元开始以来的天数。
在带时间的日期与数字之间互相转换时，带时间的日期对应于自 Unix 纪元开始以来的秒数。
当参数为 DateTime 时，toString 函数可以接受第二个字符串参数，包含时区名称，例如：Europe/Amsterdam。在这种情况下，时间会根据指定的时区进行格式化。

关于 `toDate`/`toDateTime` 函数的说明

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

YYYY-MM-DD
YYYY-MM-DD hh:mm:ss

作为例外情况，当从 UInt32、Int32、UInt64 或 Int64 数值类型转换为 Date 时，如果该数值大于或等于 65536，则该数值会被解释为 Unix 时间戳（而不是天数），并被舍入到对应的日期。这使得常见的写法 toDate(unix_timestamp) 得到支持，否则这会是一个错误，并且需要写成更繁琐的 toDate(toDateTime(unix_timestamp))。

在日期与带时间的日期之间进行转换时，采用自然的方式：要么补零时间部分，要么丢弃时间部分。

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

示例

查询：

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

结果：

┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belgrade   │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Berlin     │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bratislava │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Brussels   │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bucharest  │ 2023-09-08 22:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘

另请参阅 toUnixTimestamp 函数。

CAST

引入版本：v1.1

将一个值转换为指定的数据类型。与 reinterpret 函数不同，CAST 会尝试在目标类型中产生相同的值。如果无法做到，则会抛出异常。

语法

CAST(x, T)
or CAST(x AS T)
or x::T

参数

x — 任意类型的值。Any
T — 目标数据类型。String

返回值

返回转换为目标数据类型后的值。Any

示例

基本用法

SELECT CAST(42, 'String')

┌─CAST(42, 'String')─┐
│ 42                 │
└────────────────────┘

使用 AS 语法

SELECT CAST('2025-01-01' AS Date)

┌─CAST('2025-01-01', 'Date')─┐
│                 2025-01-01 │
└────────────────────────────┘

使用 :: 语法

SELECT '123'::UInt32

┌─CAST('123', 'UInt32')─┐
│                   123 │
└───────────────────────┘

accurateCast

引入版本：v1.1

将一个值转换为指定的数据类型。与 CAST 不同，accurateCast 会执行更严格的类型检查，如果转换会导致数据精度丢失或无法进行转换，则抛出异常。

该函数比常规的 CAST 更安全，因为它可以防止精度丢失和无效转换。

语法

accurateCast(x, T)

参数

x — 要转换的值。Any
T — 目标数据类型的名称。String

返回值

返回转换为目标数据类型后的值。Any

示例

转换成功示例

SELECT accurateCast(42, 'UInt16')

┌─accurateCast(42, 'UInt16')─┐
│                        42 │
└───────────────────────────┘

字符串转数字

SELECT accurateCast('123.45', 'Float64')

┌─accurateCast('123.45', 'Float64')─┐
│                            123.45 │
└───────────────────────────────────┘

accurateCastOrDefault

引入版本：v21.1

将值转换为指定的数据类型。与 accurateCast 类似，但在无法精确完成转换时，会返回一个默认值而不是抛出异常。

如果将默认值作为第二个参数提供，则它必须是目标类型的值。如果未提供默认值，则使用目标类型的默认值。

语法

accurateCastOrDefault(x, T[, default_value])

参数

x — 要进行转换的值。Any
T — 目标数据类型的名称。const String
default_value — 可选。转换失败时返回的默认值。Any

返回值

返回转换为目标数据类型的值；如果无法转换，则返回默认值。Any

示例

转换成功

SELECT accurateCastOrDefault(42, 'String')

┌─accurateCastOrDefault(42, 'String')─┐
│ 42                                  │
└─────────────────────────────────────┘

转换失败并使用显式默认值

SELECT accurateCastOrDefault('abc', 'UInt32', 999::UInt32)

┌─accurateCastOrDefault('abc', 'UInt32', 999)─┐
│                                         999 │
└─────────────────────────────────────────────┘

带隐式默认值的转换失败

SELECT accurateCastOrDefault('abc', 'UInt32')

┌─accurateCastOrDefault('abc', 'UInt32')─┐
│                                      0 │
└────────────────────────────────────────┘

accurateCastOrNull

自 v1.1 引入

将一个值转换为指定的数据类型。与 accurateCast 类似，但如果无法精确完成转换，则返回 NULL 而不是抛出异常。

此函数将 accurateCast 的安全性与优雅的错误处理相结合。

语法

accurateCastOrNull(x, T)

参数

x — 要转换的值。Any
T — 目标数据类型名称。String

返回值

返回转换为目标数据类型的值，如果无法转换则返回 NULL。Any

示例

转换成功

SELECT accurateCastOrNull(42, 'String')

┌─accurateCastOrNull(42, 'String')─┐
│ 42                               │
└──────────────────────────────────┘

转换失败时返回 NULL

SELECT accurateCastOrNull('abc', 'UInt32')

┌─accurateCastOrNull('abc', 'UInt32')─┐
│                                ᴺᵁᴸᴸ │
└─────────────────────────────────────┘

formatRow

引入版本：v20.7

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

注意

如果格式中包含前缀或后缀，它会写入到每一行中。此函数仅支持基于行的输出格式。

语法

formatRow(format, x, y, ...)

参数

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

返回值

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

示例

基本用法

SELECT formatRow('CSV', number, 'good')
FROM numbers(3)

┌─formatRow('CSV', number, 'good')─┐
│ 0,"good"
                         │
│ 1,"good"
                         │
│ 2,"good"
                         │
└──────────────────────────────────┘

使用自定义格式

SELECT formatRow('CustomSeparated', number, 'good')
FROM numbers(3)
SETTINGS format_custom_result_before_delimiter='<prefix>\n', format_custom_result_after_delimiter='<suffix>'

┌─formatRow('CustomSeparated', number, 'good')─┐
│ <prefix>
0    good
<suffix>                   │
│ <prefix>
1    good
<suffix>                   │
│ <prefix>
2    good
<suffix>                   │
└──────────────────────────────────────────────┘

formatRowNoNewline

引入版本：v20.7

与 formatRow 相同，但会去除每一行末尾的换行符。

按给定格式将任意表达式转换为字符串，并从结果中移除所有末尾的换行符。

语法

formatRowNoNewline(format, x, y, ...)

参数

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

返回值

返回去除换行符的格式化字符串。String

示例

基础用法

SELECT formatRowNoNewline('CSV', number, 'good')
FROM numbers(3)

┌─formatRowNoNewline('CSV', number, 'good')─┐
│ 0,"good"                                  │
│ 1,"good"                                  │
│ 2,"good"                                  │
└───────────────────────────────────────────┘

fromUnixTimestamp64Micro

引入于：v20.5

将以微秒为单位的 Unix 时间戳转换为具有微秒精度的 DateTime64 值。

输入值被视为具有微秒精度的 Unix 时间戳（自 1970-01-01 00:00:00 UTC 起的微秒数）。

语法

fromUnixTimestamp64Micro(value[, timezone])

参数

value — 以微秒为单位的 Unix 时间戳。Int64
timezone — 可选。返回值所使用的时区。String

返回值

返回一个具有微秒级精度的 DateTime64 值。DateTime64(6)

示例

用法示例

SELECT fromUnixTimestamp64Micro(1640995200123456)

┌─fromUnixTimestamp64Micro(1640995200123456)─┐
│                 2022-01-01 00:00:00.123456 │
└────────────────────────────────────────────┘

fromUnixTimestamp64Milli

自 v20.5 引入

将以毫秒为单位的 Unix 时间戳转换为具有毫秒级精度的 DateTime64 值。

输入值被视为一个具有毫秒级精度的 Unix 时间戳（自 1970-01-01 00:00:00 UTC 起的毫秒数）。

语法

fromUnixTimestamp64Milli(value[, timezone])

参数

value — 以毫秒为单位的 Unix 时间戳。Int64
timezone — 可选。返回值所使用的时区。String

返回值

具有毫秒精度的 DateTime64 值。DateTime64(3)

示例

用法示例

SELECT fromUnixTimestamp64Milli(1640995200123)

┌─fromUnixTimestamp64Milli(1640995200123)─┐
│                 2022-01-01 00:00:00.123 │
└─────────────────────────────────────────┘

fromUnixTimestamp64Nano

自 v20.5 版本引入

将以纳秒为单位的 Unix 时间戳转换为具有纳秒精度的 DateTime64 值。

输入值被视为具有纳秒精度的 Unix 时间戳（自 1970-01-01 00:00:00 UTC 起的纳秒数）。

注意

请注意，输入值被视为 UTC 时间戳，而不是使用输入值所指定时区的时间戳。

语法

fromUnixTimestamp64Nano(value[, timezone])

参数

value — 以纳秒为单位的 Unix 时间戳。Int64
timezone — 可选。返回值的时区。String

返回值

返回一个具有纳秒精度的 DateTime64 值。DateTime64(9)

示例

用法示例

SELECT fromUnixTimestamp64Nano(1640995200123456789)

┌─fromUnixTimestamp64Nano(1640995200123456789)─┐
│                2022-01-01 00:00:00.123456789 │
└──────────────────────────────────────────────┘

fromUnixTimestamp64Second

引入于：v24.12

将以秒为单位的 Unix 时间戳转换为具有秒级精度的 DateTime64 值。

输入值被视为具有秒级精度的 Unix 时间戳（自 1970-01-01 00:00:00 UTC 起的秒数）。

语法

fromUnixTimestamp64Second(value[, timezone])

参数

value — 以秒为单位的 Unix 时间戳。Int64
timezone — 可选。用于返回值的时区。String

返回值

返回一个秒级精度的 DateTime64 值。DateTime64(0)

示例

使用示例

SELECT fromUnixTimestamp64Second(1640995200)

┌─fromUnixTimestamp64Second(1640995200)─┐
│                   2022-01-01 00:00:00 │
└───────────────────────────────────────┘

parseDateTime

引入于：v23.3

根据 MySQL 日期格式字符串解析日期和时间字符串。

此函数是 formatDateTime 的逆函数。它使用格式字符串解析一个字符串参数，返回一个 DateTime 类型的值。

语法

parseDateTime(time_string, format[, timezone])

别名: TO_UNIXTIME

参数

time_string — 要解析为 DateTime 的字符串。String
format — 指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回根据 MySQL 风格的格式字符串从输入字符串解析得到的 DateTime。DateTime

示例

用法示例

SELECT parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                       2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────┘

parseDateTime32BestEffort

引入版本：v20.9

将日期和时间的字符串形式转换为 DateTime 数据类型。

该函数可以解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 自身格式以及其他一些日期和时间格式。

语法

parseDateTime32BestEffort(time_string[, time_zone])

参数

time_string — 包含要转换的日期和时间的字符串。String
time_zone — 可选。解析 time_string 时使用的时区。String

返回值

返回由 time_string 转换得到的 DateTime 值。DateTime

示例

用法示例

SELECT parseDateTime32BestEffort('23/10/2025 12:12:57')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-10-23 12:12:57 │
└───────────────────────────┘

包含时区

SELECT parseDateTime32BestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2025-08-18 10:22:16 │
└───────────────────────────┘

Unix 时间戳

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

┌─parseDateTime32BestEffort─┐
│       2015-07-07 12:04:41 │
└───────────────────────────┘

parseDateTime32BestEffortOrNull

引入版本：v20.9

与 parseDateTime32BestEffort 相同，不同之处在于当遇到无法处理的日期格式时返回 NULL。

语法

parseDateTime32BestEffortOrNull(time_string[, time_zone])

参数

time_string — 包含要转换的日期和时间的字符串。String
time_zone — 可选。用于解析 time_string 的时区。String

返回值

返回从字符串解析得到的 DateTime 对象，如果解析失败，则返回 NULL。DateTime

示例

用法示例

SELECT
    parseDateTime32BestEffortOrNull('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrNull('invalid date') AS invalid

┌─valid───────────────┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

parseDateTime32BestEffortOrZero

引入于：v20.9

与 parseDateTime32BestEffort 相同，不同之处在于当遇到无法处理的日期格式时，它会返回全零的日期或日期时间值。

语法

parseDateTime32BestEffortOrZero(time_string[, time_zone])

参数

time_string — 包含要转换的日期和时间的字符串。String
time_zone — 可选。用于解析 time_string 的时区。String

返回值

返回从字符串解析得到的 DateTime 对象，如果解析失败则返回零日期（1970-01-01 00:00:00）。DateTime

示例

使用示例

SELECT
    parseDateTime32BestEffortOrZero('23/10/2025 12:12:57') AS valid,
    parseDateTime32BestEffortOrZero('invalid date') AS invalid

┌─valid───────────────┬─invalid─────────────┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

parseDateTime64

引入版本：v24.11

根据 MySQL 日期格式字符串解析具有子秒级精度的日期和时间字符串。

对于 DateTime64 类型，此函数是 formatDateTime 的逆函数。它按照给定的格式字符串解析一个 String 参数。返回一个 DateTime64 类型的值，可在子秒级精度下表示 1900 年到 2299 年之间的日期和时间。

语法

parseDateTime64(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime64 类型的字符串。String
format — 指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回根据 MySQL 风格的格式字符串，从输入字符串解析得到的 DateTime64 值。DateTime64

示例

用法示例

SELECT parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                       2025-01-04 23:00:00.123       │
└─────────────────────────────────────────────────────────────────────┘

parseDateTime64BestEffort

引入版本：v20.1

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

语法

parseDateTime64BestEffort(time_string[, precision[, time_zone]])

参数

time_string — 包含要转换的日期或日期时间的字符串。String
precision — 可选。目标精度。3 表示毫秒，6 表示微秒。默认值：3。UInt8
time_zone — 可选。时区。函数会按照该时区解析 time_string。String

返回值

返回将 time_string 转换为 DateTime64 数据类型的结果。DateTime64

示例

用法示例

SELECT parseDateTime64BestEffort('2025-01-01') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',3,'Asia/Istanbul') AS a, toTypeName(a) AS t
FORMAT PrettyCompactMonoBlock

┌──────────────────────────a─┬─t──────────────────────────────┐
│ 2025-01-01 01:01:00.123000 │ DateTime64(3)                  │
│ 2025-01-01 00:00:00.000000 │ DateTime64(3)                  │
│ 2025-01-01 01:01:00.123460 │ DateTime64(6)                  │
│ 2025-12-31 22:01:00.123000 │ DateTime64(3, 'Asia/Istanbul') │
└────────────────────────────┴────────────────────────────────┘

parseDateTime64BestEffortOrNull

引入于：v20.1

与 parseDateTime64BestEffort 相同，不同之处在于，当遇到无法解析的日期格式时，它会返回 NULL。

语法

parseDateTime64BestEffortOrNull(time_string[, precision[, time_zone]])

参数

time_string — 包含要转换的日期或日期时间的字符串。String
precision — 可选。所需精度。3 表示毫秒，6 表示微秒。默认值：3。UInt8
time_zone — 可选。时区。函数会依据该时区解析 time_string。String

返回值

返回将 time_string 转换得到的 DateTime64 值；如果输入无法解析，则返回 NULL。DateTime64 或 NULL

示例

用法示例

SELECT parseDateTime64BestEffortOrNull('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrNull('invalid') AS invalid

┌─valid───────────────────┬─invalid─┐
│ 2025-01-01 01:01:00.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

parseDateTime64BestEffortOrZero

引入版本：v20.1

与 parseDateTime64BestEffort 相同，但在遇到无法解析的日期格式时，会返回零日期或零日期时间。

语法

parseDateTime64BestEffortOrZero(time_string[, precision[, time_zone]])

参数

time_string — 要转换的日期或日期时间字符串。String
precision — 可选。所需精度。3 表示毫秒，6 表示微秒。默认值：3。UInt8
time_zone — 可选。时区。函数会根据该时区解析 time_string。String

返回值

返回将 time_string 转换为 DateTime64 的结果；如果无法解析输入，则返回零日期/日期时间值（1970-01-01 00:00:00.000）。DateTime64

示例

用法示例

SELECT parseDateTime64BestEffortOrZero('2025-01-01 01:01:00.123') AS valid,
       parseDateTime64BestEffortOrZero('invalid') AS invalid

┌─valid───────────────────┬─invalid─────────────────┐
│ 2025-01-01 01:01:00.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

parseDateTime64BestEffortUS

自 v22.8 引入。

与 parseDateTime64BestEffort 相同，只是在存在歧义时，该函数会优先采用美国日期格式（MM/DD/YYYY 等）。

语法

parseDateTime64BestEffortUS(time_string [, precision [, time_zone]])

参数

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

返回值

返回将 time_string 按照美国日期格式习惯（用于解析存在歧义的情况）转换为 DateTime64 的结果。DateTime64

示例

用法示例

SELECT parseDateTime64BestEffortUS('02/10/2025 12:30:45.123') AS us_format,
       parseDateTime64BestEffortUS('15/08/2025 10:15:30.456') AS fallback_to_standard

┌─us_format───────────────┬─fallback_to_standard────┐
│ 2025-02-10 12:30:45.123 │ 2025-08-15 10:15:30.456 │
└─────────────────────────┴─────────────────────────┘

parseDateTime64BestEffortUSOrNull

引入自：v22.8

与 parseDateTime64BestEffort 相同，只是在存在歧义时，该函数会优先采用美国日期格式（MM/DD/YYYY 等），并在遇到无法处理的日期格式时返回 NULL。

语法

parseDateTime64BestEffortUSOrNull(time_string[, precision[, time_zone]])

参数

time_string — 包含要转换的日期或日期时间的字符串。String
precision — 可选。所需精度。3 表示毫秒，6 表示微秒。默认值：3。UInt8
time_zone — 可选。时区。函数会根据指定时区解析 time_string。String

返回值

返回按美国惯用格式将 time_string 转换为 DateTime64 的结果，如果输入无法解析则返回 NULL。DateTime64 或 NULL

示例

使用示例

SELECT parseDateTime64BestEffortUSOrNull('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrNull('invalid') AS invalid

┌─valid_us────────────────┬─invalid─┐
│ 2025-02-10 12:30:45.123 │    ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘

parseDateTime64BestEffortUSOrZero

自 v22.8 引入

与 parseDateTime64BestEffort 相同，只是在存在歧义时，此函数会优先采用美国日期格式（MM/DD/YYYY 等），并在遇到无法处理的日期格式时返回全零日期或全零日期时间值。

语法

parseDateTime64BestEffortUSOrZero(time_string [, precision [, time_zone]])

参数

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

返回值

返回按美国格式习惯将 time_string 转换得到的 DateTime64，如果输入无法解析，则返回零日期/日期时间值（1970-01-01 00:00:00.000）。DateTime64

示例

用法示例

SELECT parseDateTime64BestEffortUSOrZero('02/10/2025 12:30:45.123') AS valid_us,
       parseDateTime64BestEffortUSOrZero('invalid') AS invalid

┌─valid_us────────────────┬─invalid─────────────────┐
│ 2025-02-10 12:30:45.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘

parseDateTime64InJodaSyntax

引入于：v24.10

根据 Joda 日期格式化字符串解析具备亚秒级精度的日期时间字符串。

此函数是用于 DateTime64 的 formatDateTimeInJodaSyntax 的反函数。它使用 Joda 风格的格式化字符串解析一个 String 类型参数。返回一个 DateTime64 类型，该类型可以表示从 1900 年到 2299 年、具备亚秒级精度的日期。

有关格式模式，请参阅 Joda Time 文档。

语法

parseDateTime64InJodaSyntax(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime64 的字符串。String
format — 采用 Joda 语法的格式字符串，用于指定如何解析 time_string。String
timezone — 可选。时区。String

返回值

返回根据 Joda 风格的格式字符串从输入字符串解析得到的 DateTime64。DateTime64

示例

用法示例

SELECT parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                          2025-01-04 23:00:00.123   │
└────────────────────────────────────────────────────────────────────────────────────┘

parseDateTime64InJodaSyntaxOrNull

引入版本：v24.10

与 parseDateTime64InJodaSyntax 相同，但在遇到无法解析的日期格式时返回 NULL。

语法

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime64 的字符串。String
format — 使用 Joda 语法指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime64，如果解析失败则返回 NULL。Nullable(DateTime64)

示例

用法示例

SELECT parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                             2025-01-04 23:00:00.123      │
└──────────────────────────────────────────────────────────────────────────────────────────┘

parseDateTime64InJodaSyntaxOrZero

引入版本：v24.10

与 parseDateTime64InJodaSyntax 相同，但在遇到无法解析的日期格式时返回零日期值。

语法

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime64 的字符串。String
format — 使用 Joda 语法的格式字符串，指定如何解析 time_string。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime64；如果解析失败，则返回零值的 DateTime64。DateTime64

示例

用法示例

SELECT parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')

┌─parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│                                                              2025-01-04 23:00:00.123     │
└──────────────────────────────────────────────────────────────────────────────────────────┘

parseDateTime64OrNull

引入自：v24.11

与 parseDateTime64 相同，但在遇到无法解析的日期格式时返回 NULL。

语法

parseDateTime64OrNull(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime64 的字符串。String
format — 指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime64，如果解析失败，则返回 NULL。Nullable(DateTime64)

示例

用法示例

SELECT parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                            2025-01-04 23:00:00.123        │
└───────────────────────────────────────────────────────────────────────────┘

parseDateTime64OrZero

引入于：v24.11

与 parseDateTime64 相同，但在遇到无法解析的日期格式时返回零值日期。

语法

parseDateTime64OrZero(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime64 的字符串。String
format — 指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime64；如果解析失败，则返回 0 的 DateTime64 值。DateTime64

示例

使用示例

SELECT parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')

┌─parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│                                             2025-01-04 23:00:00.123       │
└───────────────────────────────────────────────────────────────────────────┘

parseDateTimeBestEffort

引入于：v1.1

将字符串形式的日期和时间转换为 DateTime 数据类型。该函数可以解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 日期和时间规范、ClickHouse 自身的格式以及其他一些日期和时间格式。

支持的非标准格式：

包含 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 等。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

对于所有带分隔符的格式，函数可以解析以月份全名或前三个字母表示的月份名称。如果未指定年份，则默认使用当前年份。

语法

parseDateTimeBestEffort(time_string[, time_zone])

参数

time_string — 包含要转换的日期和时间的字符串。String
time_zone — 可选。解析 time_string 时使用的时区。String

返回值

返回由 time_string 解析得到的 DateTime 值。DateTime

示例

使用示例

SELECT parseDateTimeBestEffort('23/10/2025 12:12:57') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-10-23 12:12:57 │
└─────────────────────────┘

含时区

SELECT parseDateTimeBestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-08-18 10:22:16 │
└─────────────────────────┘

Unix 时间戳

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

┌─parseDateTimeBestEffort─┐
│     2025-01-01 00:00:00 │
└─────────────────────────┘

parseDateTimeBestEffortOrNull

引入版本：v1.1

与 parseDateTimeBestEffort 相同，不同之处在于当遇到无法处理的日期格式时会返回 NULL。该函数可以解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 特有以及其他部分日期和时间格式。

支持的非标准格式：

包含 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 等。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

对于所有带分隔符的格式，函数都可以解析以完整名称或月份名称前三个字母表示的月份名。如果未指定年份，则默认认为等于当前年份。

语法

parseDateTimeBestEffortOrNull(time_string[, time_zone])

参数

time_string — 包含要转换日期和时间的字符串。String
time_zone — 可选。用于解析 time_string 的时区。String

返回值

返回 time_string 对应的 DateTime 值，如果输入无法解析则返回 NULL。DateTime 或 NULL

示例

使用示例

SELECT parseDateTimeBestEffortOrNull('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrNull('invalid') AS invalid

┌─valid───────────────┬─invalid─┐
│ 2025-10-23 12:12:57 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

parseDateTimeBestEffortOrZero

引入于：v1.1

与 parseDateTimeBestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间值。该函数可以解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 自身的格式以及其他一些日期和时间格式。

支持的非标准格式：

包含 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 等。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

对于所有带分隔符的格式，该函数可以解析以完整月份名称或月份名称前三个字母表示的月份。如果未指定年份，则默认为当前年份。

语法

parseDateTimeBestEffortOrZero(time_string[, time_zone])

参数

time_string — 包含要转换的日期和时间的字符串。String
time_zone — 可选。用于解析 time_string 的时区。String

返回值

返回与 time_string 对应的 DateTime 值；如果输入无法解析，则返回零日期/日期时间（1970-01-01 或 1970-01-01 00:00:00）。DateTime

示例

用法示例

SELECT parseDateTimeBestEffortOrZero('23/10/2025 12:12:57') AS valid,
       parseDateTimeBestEffortOrZero('invalid') AS invalid

┌─valid───────────────┬─invalid─────────────┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

parseDateTimeBestEffortUS

引入于：v1.1

对于 ISO 日期格式（例如 YYYY-MM-DD hh:mm:ss）以及其他可以无歧义地提取出“月”和“日”组成部分的日期格式（例如 YYYYMMDDhhmmss、YYYY-MM、DD hh 或 YYYY-MM-DD hh:mm:ss ±h:mm），此函数的行为与 parseDateTimeBestEffort 相同。如果“月”和“日”组成部分无法被无歧义地确定，例如 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。

语法

parseDateTimeBestEffortUS(time_string[, time_zone])

参数

time_string — 要转换的日期和时间字符串。String
time_zone — 可选。用于解析 time_string 的时区。String

返回值

返回由 time_string 解析得到的 DateTime，在存在歧义时优先按照美国日期格式进行解析。DateTime

示例

用法示例

SELECT parseDateTimeBestEffortUS('02/10/2025') AS us_format,
       parseDateTimeBestEffortUS('15/08/2025') AS fallback_to_standard

┌─us_format───────────┬─fallback_to_standard─┐
│ 2025-02-10 00:00:00 │  2025-08-15 00:00:00 │
└─────────────────────┴──────────────────────┘

parseDateTimeBestEffortUSOrNull

引入于：v1.1

与 parseDateTimeBestEffortUS 函数相同，只是当遇到无法处理的日期格式时会返回 NULL。

对于 ISO 日期格式，此函数的行为与 parseDateTimeBestEffort 相同，但在存在歧义的情况下会优先采用美国日期格式，并在解析出错时返回 NULL。

语法

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

参数

time_string — 包含要转换日期和时间的字符串。String
time_zone — 可选。解析 time_string 时使用的时区。String

返回值

将 time_string 按美国格式优先解析为 DateTime 返回；若输入无法解析，则返回 NULL。DateTime 或 NULL

示例

用法示例

SELECT parseDateTimeBestEffortUSOrNull('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrNull('invalid') AS invalid

┌─valid_us────────────┬─invalid─┐
│ 2025-02-10 00:00:00 │    ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘

parseDateTimeBestEffortUSOrZero

引入自：v1.1

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

对于 ISO 日期格式，此函数的行为与 parseDateTimeBestEffort 一致，但在存在歧义的情况下更偏向使用美国日期格式，并且在解析错误时返回零日期值。

语法

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

参数

time_string — 包含要转换的日期和时间的字符串。String
time_zone — 可选。解析 time_string 时使用的时区。String

返回值

返回按美国格式偏好将 time_string 解析得到的 DateTime 值；如果输入无法解析，则返回零日期/日期时间值（1970-01-01 或 1970-01-01 00:00:00）。DateTime

示例

用法示例

SELECT parseDateTimeBestEffortUSOrZero('02/10/2025') AS valid_us,
       parseDateTimeBestEffortUSOrZero('invalid') AS invalid

┌─valid_us────────────┬─invalid─────────────┐
│ 2025-02-10 00:00:00 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘

parseDateTimeInJodaSyntax

引入版本：v23.3

根据 Joda 日期格式字符串解析日期和时间字符串。

此函数是 formatDateTimeInJodaSyntax 的逆函数。它使用 Joda 风格的格式字符串解析一个 String 类型的参数，返回一个 DateTime 类型的值。

有关格式模式，请参考 Joda Time 文档。

语法

parseDateTimeInJodaSyntax(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime 的字符串。String
format — 使用 Joda 语法指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回根据 Joda 风格的格式字符串从输入字符串解析得到的 DateTime。DateTime

示例

使用示例

SELECT parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                      2025-01-04 23:00:00 │
└──────────────────────────────────────────────────────────────────────────┘

parseDateTimeInJodaSyntaxOrNull

自 v23.3 起引入

与 parseDateTimeInJodaSyntax 相同，但当遇到无法解析的日期格式时返回 NULL。

语法

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime 的字符串。String
format — 用于按照 Joda 语法指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime，若解析失败则返回 NULL。Nullable(DateTime)

示例

用法示例

SELECT parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                         2025-01-04 23:00:00    │
└────────────────────────────────────────────────────────────────────────────────┘

parseDateTimeInJodaSyntaxOrZero

引入于：v23.3

与 parseDateTimeInJodaSyntax 相同，但在遇到无法解析的日期格式时返回零日期值。

语法

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

参数

time_string — 要解析为 DateTime 的字符串。String
format — 使用 Joda 语法指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime，如果解析失败则返回零值的 DateTime。DateTime

示例

用法示例

SELECT parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')

┌─parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│                                                          2025-01-04 23:00:00   │
└────────────────────────────────────────────────────────────────────────────────┘

parseDateTimeOrNull

自 v23.3 起引入

与 parseDateTime 相同，但在遇到无法解析的日期格式时返回 NULL。

语法

parseDateTimeOrNull(time_string, format[, timezone])

别名: str_to_date

参数

time_string — 要解析为 DateTime 的字符串。String
format — 指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime，如果解析失败，则返回 NULL。Nullable(DateTime)

示例

用法示例

SELECT parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                            2025-01-04 23:00:00  │
└─────────────────────────────────────────────────────────────────┘

parseDateTimeOrZero

引入版本：v23.3

与 parseDateTime 相同，但在遇到无法解析的日期格式时返回零日期值。

语法

parseDateTimeOrZero(time_string, format[, timezone])

参数

time_string — 将被解析为 DateTime 的字符串。String
format — 指定如何解析 time_string 的格式字符串。String
timezone — 可选。时区。String

返回值

返回从输入字符串解析得到的 DateTime，如果解析失败则返回零值 DateTime。DateTime

示例

用法示例

SELECT parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')

┌─parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│                                             2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘

reinterpret

自 v1.1 起引入

对给定值 x 复用其在内存中的原始字节序列，并将其重新解释为目标类型。

语法

reinterpret(x, type)

参数

x — 任意类型。Any
type — 目标类型。如果是数组类型，则数组元素类型必须是定长类型。String

返回值

目标类型的值。Any

示例

用法示例

SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
    reinterpret(toInt8(1), 'Float32') AS int_to_float,
    reinterpret('1', 'UInt32') AS string_to_int

┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│         255 │        1e-45 │            49 │
└─────────────┴──────────────┴───────────────┘

数组示例

SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32

┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626]  │
└────────────────────────────┘

reinterpretAsDate

引入版本：v1.1

将输入值重新解释为一个 Date 值（假定为小端字节序），表示自 Unix 纪元起点 1970-01-01 以来经过的天数。

语法

reinterpretAsDate(x)

参数

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

返回值

日期。Date

示例

用法示例

SELECT reinterpretAsDate(65), reinterpretAsDate('A')

┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│            1970-03-07 │             1970-03-07 │
└───────────────────────┴────────────────────────┘

reinterpretAsDateTime

引入于：v1.1

将输入值重新解释为一个 DateTime 值（假设为小端序），该值表示自 Unix 纪元（1970-01-01）开始以来的天数。

语法

reinterpretAsDateTime(x)

参数

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

返回值

日期和时间。DateTime

示例

用法示例

SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')

┌─reinterpretAsDateTime(65)─┬─reinterpretAsDateTime('A')─┐
│       1970-01-01 01:01:05 │        1970-01-01 01:01:05 │
└───────────────────────────┴────────────────────────────┘

reinterpretAsFixedString

自 v1.1 引入

将输入值重新解释为定长字符串（假定为小端字节序）。末尾的空字节会被忽略，例如，对于 UInt32 值 255，该函数返回仅包含单个字符的字符串。

语法

reinterpretAsFixedString(x)

参数

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

返回值

定长字符串，其中的字节表示 x。FixedString

示例

使用示例

SELECT
    reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05')),
    reinterpretAsFixedString(toDate('1970-03-07'))

┌─reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsFixedString(toDate('1970-03-07'))─┐
│ A                                                           │ A                                              │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘

reinterpretAsFloat32

引入版本：v1.1

将输入值重新解释为 Float32 类型的值。与 CAST 不同，该函数不尝试保留原始值——如果目标类型无法表示输入值，则输出结果未定义。

语法

reinterpretAsFloat32(x)

参数

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

返回值

返回重新解释后的 x 值。Float32

示例

用法示例

SELECT reinterpretAsUInt32(toFloat32(0.2)) AS x, reinterpretAsFloat32(x)

┌──────────x─┬─reinterpretAsFloat32(x)─┐
│ 1045220557 │                     0.2 │
└────────────┴─────────────────────────┘

reinterpretAsFloat64

首次在 v1.1 中引入

将输入值重新解释为 Float64 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出是未定义的。

语法

reinterpretAsFloat64(x)

参数

x — 要按 Float64 重新解释的值。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

返回按 Float64 重新解释后的值 x。Float64

示例

使用示例

SELECT reinterpretAsUInt64(toFloat64(0.2)) AS x, reinterpretAsFloat64(x)

┌───────────────────x─┬─reinterpretAsFloat64(x)─┐
│ 4596373779694328218 │                     0.2 │
└─────────────────────┴─────────────────────────┘

reinterpretAsInt128

引入版本：v1.1

将输入值按 Int128 类型重新解释。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入值，其结果未定义。

语法

reinterpretAsInt128(x)

参数

x — 按 Int128 重新解释的值。可以是 (U)Int*、Float*、Date、DateTime、UUID、String 或 FixedString。

返回值

返回按 Int128 重新解释后的值 x。Int128

示例

使用示例

SELECT
    toInt64(257) AS x,
    toTypeName(x),
    reinterpretAsInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int64         │ 257 │ Int128          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt16

引入版本：v1.1

将输入值重新解释为 Int16 类型的值。与 CAST 不同，函数不会尝试保留原始值——如果目标类型无法表示输入值，输出是未定义的。

语法

reinterpretAsInt16(x)

参数

x — 要按 Int16 重新解释的值。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

返回按 Int16 重新解释后的值 x。Int16

示例

使用示例

SELECT
    toInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ Int8          │   1 │ Int16           │
└───┴───────────────┴─────┴─────────────────┘

reinterpretAsInt256

自 v1.1 引入

将输入值重新解释为 Int256 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入值，则输出结果未定义。

语法

reinterpretAsInt256(x)

参数

x — 要按 Int256 重新解释的值。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

返回按新类型重新解释后的值 x。Int256

示例

用法示例

SELECT
    toInt128(257) AS x,
    toTypeName(x),
    reinterpretAsInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int128        │ 257 │ Int256          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt32

引入版本：v1.1

将输入值重新解释为 Int32 类型的值。与 CAST 不同，函数不会尝试保留原始值——如果目标类型无法表示该输入值，则输出结果未定义。

语法

reinterpretAsInt32(x)

参数

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

返回值

返回按 Int32 重解释后的值 x。Int32

示例

使用示例

SELECT
    toInt16(257) AS x,
    toTypeName(x),
    reinterpretAsInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int16         │ 257 │ Int32           │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt64

引入版本：v1.1

将输入值重新解释为 Int64 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。

语法

reinterpretAsInt64(x)

参数

x — 要按 Int64 重新解释的值。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

返回按新类型重新解释后的值 x。Int64

示例

使用示例

SELECT
    toInt32(257) AS x,
    toTypeName(x),
    reinterpretAsInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int32         │ 257 │ Int64           │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsInt8

引入于：v1.1

将输入值重新解释为 Int8 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出未定义。

语法

reinterpretAsInt8(x)

参数

x — 要重新解释为 Int8 的值。可以为 (U)Int*、Float*、Date、DateTime、UUID、String 或 FixedString。

返回值

返回将 x 重新解释后的值。Int8

示例

用法示例

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsInt8(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ Int8            │
└───┴───────────────┴─────┴─────────────────┘

reinterpretAsString

引入版本：v1.1

将输入值重新解释为字符串（假定为小端字节序）。末尾的空字节会被忽略，例如，对于 UInt32 值 255，该函数会返回仅包含一个字符的字符串。

语法

reinterpretAsString(x)

参数

x — 要按字节重新解释为字符串的值。(U)Int* 或 Float* 或 Date 或 DateTime

返回值

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

示例

用法示例

SELECT
    reinterpretAsString(toDateTime('1970-01-01 01:01:05')),
    reinterpretAsString(toDate('1970-03-07'))

┌─reinterpretAsString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsString(toDate('1970-03-07'))─┐
│ A                                                      │ A                                         │
└────────────────────────────────────────────────────────┴───────────────────────────────────────────┘

reinterpretAsUInt128

引入版本：v1.1

将输入值重新解释为 UInt128 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入值，则输出是未定义的。

语法

reinterpretAsUInt128(x)

参数

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

返回值

返回重新解释后的值 x。UInt128

示例

使用示例

SELECT
    toUInt64(257) AS x,
    toTypeName(x),
    reinterpretAsUInt128(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt64        │ 257 │ UInt128         │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt16

自 v1.1 引入

将输入值重新解释为 UInt16 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示该输入值，则输出是未定义的。

语法

reinterpretAsUInt16(x)

参数

x — 要按 UInt16 重新解释的值。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

返回按 UInt16 重新解释后的值 x。UInt16

示例

使用示例

SELECT
    toUInt8(257) AS x,
    toTypeName(x),
    reinterpretAsUInt16(x) AS res,
    toTypeName(res)

┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8         │   1 │ UInt16          │
└───┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt256

自 v1.1 起引入

将输入值重新解释为 UInt256 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出未定义。

语法

reinterpretAsUInt256(x)

参数

x — 要重新解释为 UInt256 类型的值。可以是 (U)Int*、Float*、Date、DateTime、UUID、String 或 FixedString。

返回值

返回将 x 重新解释为 UInt256 类型后的值。

示例

用法示例

SELECT
    toUInt128(257) AS x,
    toTypeName(x),
    reinterpretAsUInt256(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt128       │ 257 │ UInt256         │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt32

引入于：v1.1

将输入值按 UInt32 类型重新解释。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入值，则输出是未定义的。

语法

reinterpretAsUInt32(x)

参数

x — 要按 UInt32 重新解释的值。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

返回被重新解释后的 x 值。UInt32

示例

用法示例

SELECT
    toUInt16(257) AS x,
    toTypeName(x),
    reinterpretAsUInt32(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt16        │ 257 │ UInt32          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt64

引入版本：v1.1

将输入值按 UInt64 类型重新解释为该类型的值。与 CAST 不同，函数不会尝试保留原始值——如果目标类型无法表示输入值，则输出是未定义的。

语法

reinterpretAsUInt64(x)

参数

x — 按 UInt64 重新解释的值。可以是 Int*、UInt*、Float*、Date、DateTime、UUID、String 或 FixedString。

返回值

返回按 UInt64 重新解释后的 x 的值。UInt64

示例

使用示例

SELECT
    toUInt32(257) AS x,
    toTypeName(x),
    reinterpretAsUInt64(x) AS res,
    toTypeName(res)

┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt32        │ 257 │ UInt64          │
└─────┴───────────────┴─────┴─────────────────┘

reinterpretAsUInt8

自 v1.1 起引入

将输入值重新解释为 UInt8 类型的值。与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入值，则输出未定义。

语法

reinterpretAsUInt8(x)

参数

x — 要重新解释为 UInt8 类型的值。类型可以是 (U)Int*、Float*、Date、DateTime、UUID、String 或 FixedString。

返回值

返回重新解释后的 x 值，类型为 UInt8。

示例

用法示例

SELECT
    toInt8(-1) AS val,
    toTypeName(val),
    reinterpretAsUInt8(val) AS res,
    toTypeName(res);

┌─val─┬─toTypeName(val)─┬─res─┬─toTypeName(res)─┐
│  -1 │ Int8            │ 255 │ UInt8           │
└─────┴─────────────────┴─────┴─────────────────┘

reinterpretAsUUID

自 v1.1 起引入

接受一个 16 字节的字符串，并通过将其分成两个 8 字节部分、按小端字节序解释来返回一个 UUID。如果字符串长度不足，函数的行为等同于在字符串末尾填充所需数量的空字节。如果字符串长度超过 16 字节，则会忽略末尾多余的字节。

语法

reinterpretAsUUID(fixed_string)

参数

fixed_string — 大端序字节串。FixedString

返回值

UUID 类型的值。UUID

示例

字符串转 UUID

SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))

┌─reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))─┐
│                                  08090a0b-0c0d-0e0f-0001-020304050607 │
└───────────────────────────────────────────────────────────────────────┘

toBFloat16

引入版本：v1.1

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

另请参阅：

toBFloat16OrZero。
toBFloat16OrNull。

语法

toBFloat16(expr)

参数

expr — 求值结果为数字或数字字符串表示的表达式。Expression

返回值

返回一个 16 位 bfloat16 浮点值。BFloat16

示例

用法示例

SELECT
toBFloat16(toFloat32(42.7)),
toBFloat16(toFloat32('42.7')),
toBFloat16('42.7')
FORMAT Vertical;

toBFloat16(toFloat32(42.7)): 42.5
toBFloat16(t⋯32('42.7')):    42.5
toBFloat16('42.7'):          42.5

toBFloat16OrNull

引入版本：v1.1

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

支持的参数：

数值的字符串表示。

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

二进制和十六进制数值的字符串表示。
数值类型的输入值。

注意

该函数在从字符串表示进行转换时允许静默地损失精度。

另请参阅：

toBFloat16。
toBFloat16OrZero。

语法

toBFloat16OrNull(x)

参数

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

返回值

返回一个 16 位 bfloat16 浮点数值，否则为 NULL。BFloat16 或 NULL

示例

用法示例

SELECT toBFloat16OrNull('0x5E'), -- unsupported arguments
       toBFloat16OrNull('12.3'), -- typical use
       toBFloat16OrNull('12.3456789') -- silent loss of precision

\N
12.25
12.3125

toBFloat16OrZero

引入版本：v1.1

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

支持的参数：

数值的字符串表示。

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

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

注意

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

另请参阅：

toBFloat16。
toBFloat16OrNull。

语法

toBFloat16OrZero(x)

参数

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

返回值

返回一个 16 位 BFloat16（brain floating point）值，否则返回 0。BFloat16

示例

用法示例

SELECT toBFloat16OrZero('0x5E'), -- unsupported arguments
       toBFloat16OrZero('12.3'), -- typical use
       toBFloat16OrZero('12.3456789') -- silent loss of precision

0
12.25
12.3125

toBool

自 v22.2 起引入

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

语法

toBool(expr)

参数

expr — 其结果为数字或字符串的表达式。对于字符串，接受 'true' 或 'false'（不区分大小写）。(U)Int* 或 Float* 或 String 或 Expression

返回值

根据参数的求值结果返回 true 或 false。Bool

示例

用法示例

SELECT
    toBool(toUInt8(1)),
    toBool(toInt8(-1)),
    toBool(toFloat32(1.01)),
    toBool('true'),
    toBool('false'),
    toBool('FALSE')
FORMAT Vertical

toBool(toUInt8(1)):      true
toBool(toInt8(-1)):      true
toBool(toFloat32(1.01)): true
toBool('true'):          true
toBool('false'):         false
toBool('FALSE'):         false

toDate

自 v1.1 引入

将输入值转换为 Date 类型。支持从 String、FixedString、DateTime 或数值类型进行转换。

语法

toDate(x)

参数

x — 要转换的输入值。String 或 FixedString 或 DateTime 或 (U)Int* 或 Float*

返回值

返回转换后的日期值。Date

示例

将 String 转换为 Date

SELECT toDate('2025-04-15')

2025-04-15

将 DateTime 转换为 Date

SELECT toDate(toDateTime('2025-04-15 10:30:00'))

2025-04-15

整数转换为 Date

SELECT toDate(20297)

2025-07-28

toDate32

首次引入于：v21.9

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

语法

toDate32(expr)

参数

expr — 要转换的值。String、UInt32 或 Date

返回值

返回一个日历日期。Date32

示例

处于有效范围内

SELECT toDate32('2025-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:           2025-01-01
toTypeName(value): Date32

超出有效范围

SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT Vertical

Row 1:
──────
value:           1900-01-01
toTypeName(value): Date32

toDate32OrDefault

引入版本：v21.11

将参数转换为 Date32 数据类型。如果值超出取值范围，toDate32OrDefault 会返回 Date32 支持的下边界值。如果参数的类型是 Date，则会同时考虑该类型的取值边界。当接收到无效参数时，返回默认值。

语法

toDate32OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。Date32

返回值

如果解析成功，则返回 Date32 类型的值；否则，如果传入了默认值则返回该默认值，如果未传入则返回 1900-01-01。Date32

示例

成功的转换

SELECT toDate32OrDefault('1930-01-01', toDate32('2020-01-01'))

1930-01-01

转换失败

SELECT toDate32OrDefault('xx1930-01-01', toDate32('2020-01-01'))

2020-01-01

toDate32OrNull

引入版本：v21.9

将输入值转换为 Date32 类型的值，但在传入无效参数时返回 NULL。与 toDate32 相同，只是当传入无效参数时返回 NULL。

语法

toDate32OrNull(x)

参数

x — 日期的字符串形式。String

返回值

成功时返回一个 Date32 值，否则返回 NULL。Date32 或 NULL

示例

使用示例

SELECT toDate32OrNull('2025-01-01'), toDate32OrNull('invalid')

┌─toDate32OrNull('2025-01-01')─┬─toDate32OrNull('invalid')─┐
│                   2025-01-01 │                      ᴺᵁᴸᴸ │
└──────────────────────────────┴───────────────────────────┘

toDate32OrZero

引入于：v21.9

将输入值转换为 Date32 类型的值，但在接收到无效参数时返回 Date32 的下限值。与 toDate32 相同，但在接收到无效参数时返回 Date32 的下限值。

另请参阅：

toDate32
toDate32OrNull
toDate32OrDefault

语法

toDate32OrZero(x)

参数

x — 日期的字符串形式。String

返回值

成功时返回一个 Date32 值，否则返回 Date32 的下界值（1900-01-01）。Date32

示例

用法示例

SELECT toDate32OrZero('2025-01-01'), toDate32OrZero('')

┌─toDate32OrZero('2025-01-01')─┬─toDate32OrZero('')─┐
│                   2025-01-01 │         1900-01-01 │
└──────────────────────────────┴────────────────────┘

toDateOrDefault

自 v21.11 引入

类似于 toDate，但在转换失败时，会返回一个默认值：如果指定了第二个参数，则返回该参数的值；否则返回 Date 的下界。

语法

toDateOrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。Date

返回值

成功时返回类型为 Date 的值；否则，如果传入了默认值则返回该默认值，未传入时返回 1970-01-01。Date

示例

转换成功

SELECT toDateOrDefault('2022-12-30')

2022-12-30

转换失败

SELECT toDateOrDefault('', CAST('2023-01-01', 'Date'))

2023-01-01

toDateOrNull

引入版本：v1.1

将输入值转换为 Date 类型的值，但在传入无效参数时返回 NULL。与 toDate 相同，但在传入无效参数时返回 NULL。

语法

toDateOrNull(x)

参数

x — 日期的字符串表示形式。String

返回值

成功时返回一个 Date 类型的值，否则返回 NULL。Date 或 NULL

示例

用法示例

SELECT toDateOrNull('2025-12-30'), toDateOrNull('invalid')

┌─toDateOrNull('2025-12-30')─┬─toDateOrNull('invalid')─┐
│                 2025-12-30 │                   ᴺᵁᴸᴸ │
└────────────────────────────┴────────────────────────┘

toDateOrZero

引入版本：v1.1

将输入值转换为 Date 类型的值，但在接收到无效参数时返回 Date 的下界值。与 toDate 相同，但在接收到无效参数时会返回 Date 的下界值。

另请参阅：

toDate
toDateOrNull
toDateOrDefault

语法

toDateOrZero(x)

参数

x — 日期的字符串表示。String

返回值

成功时返回一个 Date 类型的值，否则返回 Date 类型的下界值（1970-01-01）。Date

示例

用法示例

SELECT toDateOrZero('2025-12-30'), toDateOrZero('')

┌─toDateOrZero('2025-12-30')─┬─toDateOrZero('')─┐
│                 2025-12-30 │       1970-01-01 │
└────────────────────────────┴──────────────────┘

toDateTime

引入于：v1.1

将输入值转换为 DateTime 类型。

注意

如果 expr 是数字，则将其解释为自 Unix 纪元（Unix Epoch）开始以来经过的秒数（即 Unix 时间戳）。如果 expr 是 String，则可能被解释为 Unix 时间戳，或者是日期/日期时间的字符串表示。因此，由于存在歧义，明确禁用了对长度较短的数字字符串（最多 4 位）的解析，例如字符串 '1999' 既可以表示年份（不完整的 Date / DateTime 字符串表示），也可以表示 Unix 时间戳。而长度更长的数字字符串是允许的。

语法

toDateTime(expr[, time_zone])

参数

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

返回值

返回日期时间值。DateTime

示例

用法示例

SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT Vertical

Row 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'):     2025-01-01 00:00:00

toDateTime32

引入于：v20.9

将输入值转换为 DateTime 类型。支持从 String、FixedString、Date、Date32、DateTime 或数值类型（(U)Int*、Float*、Decimal）进行转换。与 DateTime 相比，DateTime32 提供了更大的取值范围，支持从 1900-01-01 到 2299-12-31 的日期。

语法

toDateTime32(x[, timezone])

参数

x — 要转换的输入值。String 或 FixedString 或 UInt* 或 Float* 或 Date 或 DateTime 或 DateTime64
timezone — 可选。用于返回的 DateTime 值的时区。String

返回值

返回转换后的值。DateTime

示例

值在有效范围内

SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('20255-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                                          │
└─────────────────────────┴────────────────────────────────────────────────────────┘

以指定精度的小数形式

SELECT toDateTime64(1735689600.000, 3) AS value, toTypeName(value);
-- without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64(1735689600.000, 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                            │
└─────────────────────────┴──────────────────────────────────────────┘
┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ DateTime64(3)                              │
└─────────────────────────┴────────────────────────────────────────────┘

带时区

SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul')                                      │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────┘

toDateTime64

引入版本：v20.1

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

语法

toDateTime64(expr, scale[, timezone])

参数

expr — 返回数字或数字字符串表示形式的表达式。Expression
scale — 刻度（精度）：10^(-scale) 秒。UInt8
timezone — 可选。指定的 DateTime64 对象所使用的时区。String

返回值

返回具有亚秒级精度的日历日期和时间。DateTime64

示例

值在范围内时

SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3)                                          │
└─────────────────────────┴────────────────────────────────────────────────────────┘

作为指定精度的 Decimal

SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- Without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ DateTime64(3)                              │
└─────────────────────────┴────────────────────────────────────────────┘

含时区

SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);

┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul')                                      │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────┘

toDateTime64OrDefault

自 v21.11 引入

与 toDateTime64 类似，此函数将输入值转换为 DateTime64 类型的值，但在收到无效参数时，会返回 DateTime64 的默认值或调用方提供的默认值。

语法

toDateTime64OrDefault(expr, scale[, timezone, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
scale — 刻度大小（精度）：10^-precision 秒。UInt8
timezone — 可选。时区。String
default — 可选。解析失败时返回的默认值。DateTime64

返回值

如果转换成功，则返回 DateTime64 类型的值；否则在提供默认值时返回该默认值，未提供时返回 1970-01-01 00:00:00.000。DateTime64

示例

转换成功

SELECT toDateTime64OrDefault('1976-10-18 00:00:00.30', 3)

1976-10-18 00:00:00.300

转换失败

SELECT toDateTime64OrDefault('1976-10-18 00:00:00 30', 3, 'UTC', toDateTime64('2001-01-01 00:00:00.00',3))

2000-12-31 23:00:00.000

toDateTime64OrNull

引入于：v20.1

将输入值转换为 DateTime64 类型的值，但在传入无效参数时返回 NULL。与 toDateTime64 相同，但在传入无效参数时返回 NULL。

语法

toDateTime64OrNull(x)

参数

x — 包含日期、时间且具有子秒精度的字符串表示。String

返回值

成功时返回一个 DateTime64 值，否则返回 NULL。DateTime64 或 NULL

示例

用法示例

SELECT toDateTime64OrNull('2025-12-30 13:44:17.123'), toDateTime64OrNull('invalid')

┌─toDateTime64OrNull('2025-12-30 13:44:17.123')─┬─toDateTime64OrNull('invalid')─┐
│                         2025-12-30 13:44:17.123 │                          ᴺᵁᴸᴸ │
└─────────────────────────────────────────────────┴───────────────────────────────┘

toDateTime64OrZero

自 v20.1 引入

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

另请参阅：

toDateTime64。
toDateTime64OrNull。
toDateTime64OrDefault。

语法

toDateTime64OrZero(x)

参数

x — 具有时间和子秒级精度的日期的字符串表示。String

返回值

成功时返回 DateTime64 值，否则返回 DateTime64 的下界（1970-01-01 00:00:00.000）。DateTime64

示例

用法示例

SELECT toDateTime64OrZero('2025-12-30 13:44:17.123'), toDateTime64OrZero('invalid')

┌─toDateTime64OrZero('2025-12-30 13:44:17.123')─┬─toDateTime64OrZero('invalid')─┐
│                         2025-12-30 13:44:17.123 │             1970-01-01 00:00:00.000 │
└─────────────────────────────────────────────────┴─────────────────────────────────────┘

toDateTimeOrDefault

引入版本：v21.11

与 toDateTime 类似，但在解析失败时会返回一个默认值。该默认值要么是第三个参数（如果指定），否则为 DateTime 的下边界值。

语法

toDateTimeOrDefault(expr[, timezone, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。String 或 (U)Int* 或 Float*
timezone — 可选。时区。String
default — 可选。解析失败时返回的默认值。DateTime

返回值

如果解析成功，则返回 DateTime 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 1970-01-01 00:00:00。DateTime

示例

转换成功

SELECT toDateTimeOrDefault('2022-12-30 13:44:17')

2022-12-30 13:44:17

转换失败

SELECT toDateTimeOrDefault('', 'UTC', CAST('2023-01-01', 'DateTime(\'UTC\')'))

2023-01-01 00:00:00

toDateTimeOrNull

引入于：v1.1

将输入值转换为 DateTime 类型的值，但在传入无效参数时返回 NULL。与 toDateTime 相同，但在传入无效参数时返回 NULL。

语法

toDateTimeOrNull(x)

参数

x — 包含时间的日期字符串表示形式。String

返回值

如果解析成功，则返回一个 DateTime 值，否则返回 NULL。DateTime 或 NULL

示例

使用示例

SELECT toDateTimeOrNull('2025-12-30 13:44:17'), toDateTimeOrNull('invalid')

┌─toDateTimeOrNull('2025-12-30 13:44:17')─┬─toDateTimeOrNull('invalid')─┐
│                     2025-12-30 13:44:17 │                        ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘

toDateTimeOrZero

自 v1.1 起提供

将输入值转换为 DateTime 类型的值，但在接收到无效参数时返回 DateTime 的最小值。与 toDateTime 相同，但在接收到无效参数时返回 DateTime 的最小值。

语法

toDateTimeOrZero(x)

参数

x — 含时间部分的日期字符串表示。String

返回值

成功时返回一个 DateTime 值，否则返回 DateTime 的下限（1970-01-01 00:00:00）。DateTime

示例

使用示例

SELECT toDateTimeOrZero('2025-12-30 13:44:17'), toDateTimeOrZero('invalid')

┌─toDateTimeOrZero('2025-12-30 13:44:17')─┬─toDateTimeOrZero('invalid')─┐
│                     2025-12-30 13:44:17 │         1970-01-01 00:00:00 │
└─────────────────────────────────────────┴─────────────────────────────┘

toDecimal128

引入于：v18.12

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

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

不支持的参数：

取值为 NaN 和 Inf（不区分大小写）的 Float* 值或其字符串表示。
二进制和十六进制值的字符串表示，例如：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。可以使用字符串（String）输入，使运算基于底层整数类型：toDecimal128('1.15', 2) = 1.15

语法

toDecimal128(expr, S)

参数

expr — 返回一个数字或数字字符串表示形式的表达式。Expression
S — 介于 0 和 38 之间的刻度（scale）参数，用于指定数字小数部分的位数上限。UInt8

返回值

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

示例

使用示例

SELECT
    toDecimal128(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal128(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal128('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(38, 1)
b:      99.67
type_b: Decimal(38, 2)
c:      99.67
type_c: Decimal(38, 3)

toDecimal128OrDefault

引入版本：v21.11

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

语法

toDecimal128OrDefault(expr, S[, default])

参数

expr — 数字的字符串表示形式。String
S — 取值范围为 0 到 38 的 scale 参数，用于指定数值小数部分最多可以包含的位数。UInt8
default — 可选。解析为 Decimal128(S) 类型失败时要返回的默认值。Decimal128(S)

返回值

成功时返回 Decimal(38, S) 类型的值；否则如果传入了默认值则返回该默认值，如果未传入默认值则返回 0。Decimal128(S)

示例

转换成功

SELECT toDecimal128OrDefault(toString(1/42), 18)

0.023809523809523808

转换失败

SELECT toDecimal128OrDefault('Inf', 0, CAST('-1', 'Decimal128(0)'))

-1

toDecimal128OrNull

引入于：v20.1

将输入值转换为 Decimal(38, S) 类型的值，但在出错时返回 NULL。类似于 toDecimal128，但在转换出错时返回 NULL，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示形式。
类型为 Float* 的值或其字符串表示形式。

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

Float* 值 NaN 和 Inf 的值或其字符串表示形式（不区分大小写）。
二进制和十六进制值的字符串表示形式。
超出 Decimal128 范围的值：(-1*10^(38 - S), 1*10^(38 - S))。

另请参阅：

toDecimal128。
toDecimal128OrZero。
toDecimal128OrDefault。

语法

toDecimal128OrNull(expr, S)

参数

expr — 返回数值或数值字符串表示形式的表达式。Expression
S — 介于 0 和 38 之间的标度（scale）参数，用于指定数字小数部分可以包含的位数。UInt8

返回值

成功时返回 Decimal(38, S) 值，否则返回 NULL。Decimal128(S) 或 NULL

示例

用法示例

SELECT toDecimal128OrNull('42.7', 2), toDecimal128OrNull('invalid', 2)

┌─toDecimal128OrNull('42.7', 2)─┬─toDecimal128OrNull('invalid', 2)─┐
│                         42.70 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal128OrZero

引入版本：v20.1

将输入值转换为 Decimal(38, S) 类型的值，但在发生错误时返回 0。类似于 toDecimal128 但在转换出错时返回 0，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

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

类型为 Float* 的 NaN 和 Inf 值或其字符串表示（不区分大小写）。
二进制值和十六进制值的字符串表示。

注意

如果输入值超出 Decimal128 的范围：(-1*10^(38 - S), 1*10^(38 - S))，函数返回 0。

语法

toDecimal128OrZero(expr, S)

参数

expr — 返回数值或其字符串表示的表达式。Expression
S — 取值范围为 0 到 38 的 scale 参数，用于指定数值小数部分最多可以有多少位数字。UInt8

返回值

成功时返回一个 Decimal(38, S) 值，否则返回 0。Decimal128(S)

示例

基本用法

SELECT toDecimal128OrZero('42.7', 2), toDecimal128OrZero('invalid', 2)

┌─toDecimal128OrZero('42.7', 2)─┬─toDecimal128OrZero('invalid', 2)─┐
│                         42.70 │                             0.00 │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal256

引入版本：v20.8

将输入值转换为 Decimal(76, S) 类型、scale 为 S 的值。若发生错误则抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

不支持的参数：

取值为 NaN 和 Inf（不区分大小写）的 Float* 值或其字符串表示。
二进制和十六进制值的字符串表示，例如：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。可以使用 String 类型的输入，此时运算将使用底层的整数类型：toDecimal256('1.15', 2) = 1.15

语法

toDecimal256(expr, S)

参数

expr — 返回数字或其字符串表示形式的表达式。Expression
S — 取值在 0 到 76 之间的 scale 参数，用于指定数字小数部分最多可以有多少位。UInt8

返回值

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

示例

用法示例

SELECT
    toDecimal256(99, 1) AS a, toTypeName(a) AS type_a,
    toDecimal256(99.67, 2) AS b, toTypeName(b) AS type_b,
    toDecimal256('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      99
type_a: Decimal(76, 1)
b:      99.67
type_b: Decimal(76, 2)
c:      99.67
type_c: Decimal(76, 3)

toDecimal256OrDefault

自 v21.11 起引入

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

语法

toDecimal256OrDefault(expr, S[, default])

参数

expr — 数字的字符串表示形式。String
S — 介于 0 和 76 之间的 scale 参数，指定数字小数部分最多可以有多少位。UInt8
default — 可选。解析为 Decimal256(S) 类型失败时返回的默认值。Decimal256(S)

返回值

成功时返回类型为 Decimal(76, S) 的值，否则如果传入了默认值则返回该默认值，未传入则返回 0。Decimal256(S)

示例

转换成功

SELECT toDecimal256OrDefault(toString(1/42), 76)

0.023809523809523808

转换失败

SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))

-1

toDecimal256OrNull

引入版本：v20.8

将输入值转换为 Decimal(76, S) 类型的值，但在出错时返回 NULL。类似于 toDecimal256，但在转换出错时返回 NULL，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示形式。
类型为 Float* 的值或其字符串表示形式。

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

Float* 值 NaN 和 Inf（大小写不敏感）的值或字符串表示形式。
二进制和十六进制值的字符串表示形式。
超出 Decimal256 边界的值：(-1 * 10^(76 - S), 1 * 10^(76 - S))。

参见：

toDecimal256。
toDecimal256OrZero。
toDecimal256OrDefault。

语法

toDecimal256OrNull(expr, S)

参数

expr — 返回数字或数字字符串表示形式的表达式。Expression
S — 介于 0 和 76 之间的 scale 参数，用于指定数字的小数部分最多可以有多少位。UInt8

返回值

转换成功时返回一个 Decimal(76, S) 值，否则返回 NULL。Decimal256(S) 或 NULL

示例

用法示例

SELECT toDecimal256OrNull('42.7', 2), toDecimal256OrNull('invalid', 2)

┌─toDecimal256OrNull('42.7', 2)─┬─toDecimal256OrNull('invalid', 2)─┐
│                         42.70 │                             ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal256OrZero

引入于：v20.8

将输入值转换为类型为 Decimal(76, S) 的值，但在出错时返回 0。类似于 toDecimal256，但在转换出错时返回 0，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

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

Float* 类型的 NaN 和 Inf 值或其字符串表示（不区分大小写）。
二进制值和十六进制值的字符串表示。

注意

如果输入值超出 Decimal256 的范围：(-1*10^(76 - S), 1*10^(76 - S))，则函数返回 0。

另请参阅：

toDecimal256。
toDecimal256OrNull。
toDecimal256OrDefault。

语法

toDecimal256OrZero(expr, S)

参数

expr — 返回数字或其字符串表示形式的表达式。Expression
S — 介于 0 到 76 之间的 scale 参数，用于指定数字小数部分可以包含的位数。UInt8

返回值

成功时返回 Decimal(76, S) 类型的值，否则返回 0。Decimal256(S)

示例

用法示例

SELECT toDecimal256OrZero('42.7', 2), toDecimal256OrZero('invalid', 2)

┌─toDecimal256OrZero('42.7', 2)─┬─toDecimal256OrZero('invalid', 2)─┐
│                         42.70 │                             0.00 │
└───────────────────────────────┴──────────────────────────────────┘

toDecimal32

引入于：v18.12

将输入值转换为 Decimal(9, S) 类型、标度为 S 的值。若发生错误则抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

不支持的参数：

值或字符串表示为 Float* 的 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。可以使用 String 作为输入，以便运算基于底层整数类型：toDecimal32('1.15', 2) = 1.15

语法

toDecimal32(expr, S)

参数

expr — 返回数字或数字字符串表示形式的表达式。Expression
S — 介于 0 和 9 之间的标度参数，指定数字小数部分可以包含的位数。UInt8

返回值

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

示例

用法示例

SELECT
    toDecimal32(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal32(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal32('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2
type_a: Decimal(9, 1)
b:      4.2
type_b: Decimal(9, 2)
c:      4.2
type_c: Decimal(9, 3)

toDecimal32OrDefault

自 v21.11 引入

与 toDecimal32 类似，此函数将输入值转换为 Decimal(9, S) 类型的值，但在出错时返回默认值。

语法

toDecimal32OrDefault(expr, S[, default])

参数

expr — 数字的字符串表示形式。String
S — 介于 0 和 9 之间的小数位数参数，指定数字小数部分最多可以有多少位。UInt8
default — 可选。如果解析为 Decimal32(S) 类型失败，返回的默认值。Decimal32(S)

返回值

解析成功时返回类型为 Decimal(9, S) 的值，否则返回传入的默认值；如果未传入默认值，则返回 0。Decimal32(S)

示例

转换成功

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

转换失败

SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))

-1

toDecimal32OrNull

自 v20.1 起引入

将输入值转换为 Decimal(9, S) 类型的值，但在出错时返回 NULL。与 toDecimal32 类似，但在转换出错时返回 NULL，而不是抛出异常。

支持的参数：

(U)Int* 类型的值或其字符串表示。
Float* 类型的值或其字符串表示。

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

Float* 类型的 NaN 和 Inf 值或其字符串表示（不区分大小写）。
二进制和十六进制值的字符串表示。
超出 Decimal32 范围的值：(-1*10^(9 - S), 1*10^(9 - S))。

另请参阅：

toDecimal32。
toDecimal32OrZero。
toDecimal32OrDefault。

语法

toDecimal32OrNull(expr, S)

参数

expr — 返回数值或数值字符串表示形式的表达式。Expression
S — 介于 0 到 9 之间的刻度参数，指定数字小数部分可以具有的位数。UInt8

返回值

成功时返回一个 Decimal(9, S) 值，否则返回 NULL。Decimal32(S) 或 NULL

示例

使用示例

SELECT toDecimal32OrNull('42.7', 2), toDecimal32OrNull('invalid', 2)

┌─toDecimal32OrNull('42.7', 2)─┬─toDecimal32OrNull('invalid', 2)─┐
│                        42.70 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

toDecimal32OrZero

引入于：v20.1

将输入值转换为类型为 Decimal(9, S) 的值，但在出错时返回 0。类似于 toDecimal32，但在转换出错时返回 0，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

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

类型为 Float* 的 NaN 和 Inf 值或其字符串表示（不区分大小写）。
二进制和十六进制值的字符串表示。

注意

如果输入值超出 Decimal32 的范围：(-1*10^(9 - S), 1*10^(9 - S))，则函数返回 0。

语法

toDecimal32OrZero(expr, S)

参数

expr — 返回一个数字或数字的字符串表示形式的表达式。Expression
S — 介于 0 和 9 之间的 scale 参数，用于指定数值小数部分的位数。UInt8

返回值

转换成功时返回 Decimal(9, S) 值，否则返回 0。Decimal32(S)

示例

用法示例

SELECT toDecimal32OrZero('42.7', 2), toDecimal32OrZero('invalid', 2)

┌─toDecimal32OrZero('42.7', 2)─┬─toDecimal32OrZero('invalid', 2)─┐
│                        42.70 │                            0.00 │
└──────────────────────────────┴─────────────────────────────────┘

toDecimal64

引入于：v18.12

将输入值转换为类型为 Decimal(18, S)、小数位数为 S 的值。在发生错误时抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

不支持的参数：

Float* 类型中的 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。你可以使用 String 输入，以便这些操作使用底层的整数类型：toDecimal64('1.15', 2) = 1.15

语法

toDecimal64(expr, S)

参数

expr — 返回数值或其字符串表示形式的表达式。Expression
S — 介于 0 到 18 之间的刻度参数，用于指定数值小数部分可以包含的位数。UInt8

返回值

返回一个 Decimal 值。Decimal(18, S)

示例

用法示例

SELECT
    toDecimal64(2, 1) AS a, toTypeName(a) AS type_a,
    toDecimal64(4.2, 2) AS b, toTypeName(b) AS type_b,
    toDecimal64('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical

Row 1:
──────
a:      2.0
type_a: Decimal(18, 1)
b:      4.20
type_b: Decimal(18, 2)
c:      4.200
type_c: Decimal(18, 3)

toDecimal64OrDefault

自 v21.11 起提供

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

语法

toDecimal64OrDefault(expr, S[, default])

参数

expr — 数字的字符串表示形式。String
S — 介于 0 和 18 之间的小数位数参数，指定数字小数部分最多可以包含的位数。UInt8
default — 可选。将值解析为 Decimal64(S) 类型失败时返回的默认值。Decimal64(S)

返回值

解析成功时返回类型为 Decimal(18, S) 的值；否则，如果传入了默认值则返回该默认值，否则返回 0。Decimal64(S)

示例

成功转换

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

转换失败

SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))

-1

toDecimal64OrNull

引入自：v20.1

将输入值转换为类型为 Decimal(18, S) 的值，但在出错时返回 NULL。类似于 toDecimal64，但在转换出错时返回 NULL 而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值或其字符串表示。

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

Float* 类型值 NaN 和 Inf（不区分大小写）或其字符串表示。
二进制和十六进制值的字符串表示。
超出 Decimal64 范围的值：(-1*10^(18 - S), 1*10^(18 - S))。

另请参阅：

toDecimal64。
toDecimal64OrZero。
toDecimal64OrDefault。

语法

toDecimal64OrNull(expr, S)

参数

expr — 返回数字或其字符串形式的表达式。Expression
S — 介于 0 到 18 之间的小数位精度参数，用于指定数字小数部分最多可以有多少位数字。UInt8

返回值

成功时返回一个 Decimal(18, S) 值，否则返回 NULL。Decimal64(S) 或 NULL

示例

用法示例

SELECT toDecimal64OrNull('42.7', 2), toDecimal64OrNull('invalid', 2)

┌─toDecimal64OrNull('42.7', 2)─┬─toDecimal64OrNull('invalid', 2)─┐
│                        42.70 │                            ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘

toDecimal64OrZero

引入于：v20.1

将输入值转换为类型为 Decimal(18, S) 的值，但在出错时返回 0。类似于 toDecimal64，但在转换出错时返回 0，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示形式。
类型为 Float* 的值或其字符串表示形式。

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

值为 NaN 和 Inf（不区分大小写）的 Float* 值或其字符串表示形式。
二进制值和十六进制值的字符串表示形式。

注意

如果输入值超出 Decimal64 的范围：(-1*10^(18 - S), 1*10^(18 - S))，函数将返回 0。

另请参阅：

toDecimal64。
toDecimal64OrNull。
toDecimal64OrDefault。

语法

toDecimal64OrZero(expr, S)

参数

expr — 返回数值或其字符串表示形式的表达式。Expression
S — 介于 0 和 18 之间的 scale 参数，用于指定数值小数部分的小数位数。UInt8

返回值

成功时返回 Decimal(18, S) 类型的值，否则返回 0。Decimal64(S)

示例

用法示例

SELECT toDecimal64OrZero('42.7', 2), toDecimal64OrZero('invalid', 2)

┌─toDecimal64OrZero('42.7', 2)─┬─toDecimal64OrZero('invalid', 2)─┐
│                        42.70 │                            0.00 │
└──────────────────────────────┴─────────────────────────────────┘

toDecimalString

引入版本：v23.3

将数值转换为带有指定小数位数的 String。

该函数会将输入值四舍五入到指定的小数位数。如果输入值的小数位少于指定的位数，则在小数部分补零，以达到精确指定的小数位数。

语法

toDecimalString(number, scale)

参数

number — 要转换为字符串的数值。可以是任意数值类型（Int、UInt、Float、Decimal）。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64 或 Decimal
scale — 小数部分要显示的位数。如有必要，结果会被四舍五入。UInt8

返回值

返回一个字符串形式的数值表示，且小数位数严格等于指定的位数。String

示例

对数字进行舍入并格式化

SELECT toDecimalString(2.1456, 2)

┌─toDecimalString(2.1456, 2)─┐
│ 2.15                       │
└────────────────────────────┘

零填充

SELECT toDecimalString(5, 3)

┌─toDecimalString(5, 3)─┐
│ 5.000                 │
└───────────────────────┘

不同数值类型

SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
       toDecimalString(CAST(42.7 AS Float32), 4) AS float_val

┌─decimal_val─┬─float_val─┐
│ 123.46      │ 42.7000   │
└─────────────┴───────────┘

toFixedString

引入版本：v1.1

将一个 String 参数转换为 FixedString(N) 类型（长度固定为 N 的字符串）。

如果字符串的字节数少于 N，则在右侧用空字节进行填充。如果字符串的字节数多于 N，则会抛出异常。

语法

toFixedString(s, N)

参数

s — 要转换的字符串。String
N — 结果 FixedString 的长度。const UInt*

返回值

返回长度为 N 的 FixedString。FixedString(N)

示例

用法示例

SELECT toFixedString('foo', 8) AS s;

┌─s─────────────┐
│ foo\0\0\0\0\0 │
└───────────────┘

toFloat32

引入于：v1.1

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

支持的参数：

类型为 (U)Int* 的值。
(U)Int8/16/32/128/256 的字符串形式。
类型为 Float* 的值，包括 NaN 和 Inf。
Float* 的字符串形式，包括 NaN 和 Inf（不区分大小写）。

不支持的参数：

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

另请参阅：

toFloat32OrZero。
toFloat32OrNull。
toFloat32OrDefault。

语法

toFloat32(expr)

参数

expr — 一个表达式，返回一个数字或该数字的字符串表示形式。Expression

返回值

返回一个 32 位浮点值。Float32

示例

用法示例

SELECT
    toFloat32(42.7),
    toFloat32('42.7'),
    toFloat32('NaN')
FORMAT Vertical

Row 1:
──────
toFloat32(42.7):   42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'):  nan

toFloat32OrDefault

引入版本：v21.11

与 toFloat32 类似，此函数会将输入值转换为 Float32 类型的值，但在发生错误时返回默认值。如果未传入 default 值，则在发生错误时返回 0。

语法

toFloat32OrDefault(expr[, default])

参数

expr — 结果为数字或数字字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。Float32

返回值

解析成功时返回 Float32 类型的值；否则，如果传入了默认值则返回该默认值，如果未传入则返回 0。Float32

示例

成功转换

SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))

转换失败

SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))

toFloat32OrNull

引入版本：v1.1

将输入值转换为 Float32 类型的值，但在出错时返回 NULL。类似于 toFloat32，但在转换出错时返回 NULL，而不是抛出异常。

支持的参数：

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

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

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

另请参阅：

toFloat32。
toFloat32OrZero。
toFloat32OrDefault。

语法

toFloat32OrNull(x)

参数

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

返回值

如果转换成功，返回 32 位浮点数，否则返回 NULL。Float32 或 NULL

示例

使用示例

SELECT
    toFloat32OrNull('42.7'),
    toFloat32OrNull('NaN'),
    toFloat32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  \N

toFloat32OrZero

引入版本：v1.1

将输入值转换为 Float32 类型的值，但在发生错误时返回 0。类似于 toFloat32，但在转换出错时返回 0 而不是抛出异常。

另请参阅：

toFloat32。
toFloat32OrNull。
toFloat32OrDefault。

语法

toFloat32OrZero(x)

参数

x — 数字的字符串形式。String

返回值

成功时返回 32 位浮点数值，否则返回 0。Float32

示例

用法示例

SELECT
    toFloat32OrZero('42.7'),
    toFloat32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'):  0

toFloat64

引入于：v1.1

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

支持的参数类型：

类型为 (U)Int* 的值。
(U)Int8/16/32/128/256 的字符串形式。
类型为 Float* 的值，包括 NaN 和 Inf。
类型为 Float* 的字符串形式，包括 NaN 和 Inf（不区分大小写）。

不支持的参数类型：

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

另请参阅：

toFloat64OrZero。
toFloat64OrNull。
toFloat64OrDefault。

语法

toFloat64(expr)

参数

expr — 其结果为数字或数字的字符串表示形式的表达式。Expression

返回值

返回 64 位浮点数值。Float64

示例

使用示例

SELECT
    toFloat64(42.7),
    toFloat64('42.7'),
    toFloat64('NaN')
FORMAT Vertical

Row 1:
──────
toFloat64(42.7):   42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'):  nan

toFloat64OrDefault

自 v21.11 引入

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

语法

toFloat64OrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。Float64

返回值

转换成功时返回 Float64 类型的值；否则，如果传入了默认值则返回该默认值，否则返回 0。Float64

示例

成功的转换

SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))

转换失败

SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))

toFloat64OrNull

引入版本：v1.1

将输入值转换为 Float64 类型的值，但在发生错误时返回 NULL。类似于 toFloat64，但在转换出错时返回 NULL，而不是抛出异常。

支持的参数：

类型为 (U)Int* 的值。
(U)Int8/16/32/128/256 的字符串形式。
类型为 Float* 的值，包括 NaN 和 Inf。
类型为 Float* 的字符串形式，包括 NaN 和 Inf（不区分大小写）。

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

二进制和十六进制值的字符串形式，例如 SELECT toFloat64OrNull('0xc0fe');。
无效的字符串格式。

另请参阅：

toFloat64。
toFloat64OrZero。
toFloat64OrDefault。

语法

toFloat64OrNull(x)

参数

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

返回值

如果转换成功，返回 64 位浮点数，否则返回 NULL。Float64 或 NULL

示例

使用示例

SELECT
    toFloat64OrNull('42.7'),
    toFloat64OrNull('NaN'),
    toFloat64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'):  nan
toFloat64OrNull('abc'):  \N

toFloat64OrZero

引入于：v1.1

将输入值转换为 Float64 类型的值，但在发生错误时返回 0。其行为类似于 toFloat64，但在转换出错时返回 0，而不是抛出异常。

另请参阅：

toFloat64。
toFloat64OrNull。
toFloat64OrDefault。

语法

toFloat64OrZero(x)

参数

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

返回值

成功时返回 64 位浮点数值，否则返回 0。Float64

示例

用法示例

SELECT
    toFloat64OrZero('42.7'),
    toFloat64OrZero('abc')
FORMAT Vertical

Row 1:
──────
toFloat64OrZero('42.7'): 42.7
toFloat64OrZero('abc'):  0

toInt128

引入于：v1.1

将输入值转换为 Int128 类型的值。出错时抛出异常。该函数采用向零舍入，这意味着会截断数字的小数部分。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

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

另请参阅：

toInt128OrZero。
toInt128OrNull。
toInt128OrDefault。

语法

toInt128(expr)

参数

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

返回值

返回一个 128 位整数值。Int128

示例

使用示例

SELECT
    toInt128(-128),
    toInt128(-128.8),
    toInt128('-128')
FORMAT Vertical

Row 1:
──────
toInt128(-128):   -128
toInt128(-128.8): -128
toInt128('-128'): -128

toInt128OrDefault

引入版本：v21.11

与 toInt128 类似，此函数将输入值转换为 Int128 类型的值，但在出错时返回默认值。如果未传入 default 参数，则在出错时返回 0。

语法

toInt128OrDefault(expr[, default])

参数

expr — 返回数值或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。Int128

返回值

如果转换成功，则返回 Int128 类型的值；否则，如果提供了默认值则返回该默认值，如果未提供则返回 0。Int128

示例

成功转换

SELECT toInt128OrDefault('-128', CAST('-1', 'Int128'))

-128

转换失败

SELECT toInt128OrDefault('abc', CAST('-1', 'Int128'))

-1

toInt128OrNull

引入版本：v20.8

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

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

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

另请参阅：

toInt128。
toInt128OrZero。
toInt128OrDefault。

语法

toInt128OrNull(x)

参数

x — 数字的 String 类型表示。String

返回值

返回类型为 Int128 的值，如果转换失败则返回 NULL。Int128 或 NULL

示例

用法示例

SELECT
    toInt128OrNull('-128'),
    toInt128OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'):  \N

toInt128OrZero

自 v20.8 引入

将输入值转换为 Int128 类型，但在出错时返回 0。类似于 toInt128，但会返回 0 而不是抛出异常。

另请参阅：

toInt128。
toInt128OrNull。
toInt128OrDefault。

语法

toInt128OrZero(x)

参数

x — 要进行转换的输入值，可以是 String、FixedString、Float*、Decimal、(U)Int*、Date 或 DateTime。

返回值

返回转换后的输入值，如果转换失败则返回 0。Int128

示例

使用示例

SELECT toInt128OrZero('123')

转换失败时返回 0

SELECT toInt128OrZero('abc')

toInt16

引入版本：v1.1

将输入值转换为 Int16 类型的值。在发生错误时抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串形式。
类型为 Float* 的值。

不支持的参数：

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

注意

如果输入值不能在 Int16 的范围内表示，则结果会发生上溢或下溢。这不视为错误。例如：SELECT toInt16(32768) == -32768;。

注意

该函数使用向零舍入，即截断数字的小数部分。

另请参阅：

toInt16OrZero。
toInt16OrNull。
toInt16OrDefault。

语法

toInt16(expr)

参数

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

返回值

返回一个 16 位整数值。Int16

示例

用法示例

SELECT
    toInt16(-16),
    toInt16(-16.16),
    toInt16('-16')
FORMAT Vertical

Row 1:
──────
toInt16(-16):    -16
toInt16(-16.16): -16
toInt16('-16'):  -16

toInt16OrDefault

引入于：v21.11

与 toInt16 类似，此函数将输入值转换为 Int16 类型的值，但在发生错误时返回默认值。如果未指定 default 值，则在发生错误时返回 0。

语法

toInt16OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。Int16

返回值

如果转换成功，则返回 Int16 类型的值；否则在传入默认值时返回该默认值，未传入则返回 0。Int16

示例

转换成功

SELECT toInt16OrDefault('-16', CAST('-1', 'Int16'))

-16

转换失败

SELECT toInt16OrDefault('abc', CAST('-1', 'Int16'))

-1

toInt16OrNull

引入版本：v1.1

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

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

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

另请参阅：

toInt16。
toInt16OrZero。
toInt16OrDefault。

语法

toInt16OrNull(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回 Int16 类型的值；如果转换失败，则返回 NULL。Int16 或 NULL

示例

用法示例

SELECT
    toInt16OrNull('-16'),
    toInt16OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): \N

toInt16OrZero

引入版本：v1.1

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

支持的参数：

(U)Int* 的字符串表示形式。

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

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toInt16OrZero('0xc0fe');。

注意

如果输入值不能在 Int16 的取值范围内表示，则结果会发生上溢或下溢。这不视为错误。

另请参阅：

toInt16。
toInt16OrNull。
toInt16OrDefault。

语法

toInt16OrZero(x)

参数

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

返回值

返回 Int16 类型的值，如果转换失败则返回 0。Int16

示例

用法示例

SELECT
    toInt16OrZero('16'),
    toInt16OrZero('abc')
FORMAT Vertical

Row 1:
──────
toInt16OrZero('16'): 16
toInt16OrZero('abc'): 0

toInt256

引入版本：v1.1

将输入值转换为 Int256 类型的值。出错时抛出异常。该函数使用趋零舍入，这意味着会截断数值的小数部分。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

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

另请参阅：

toInt256OrZero。
toInt256OrNull。
toInt256OrDefault。

语法

toInt256(expr)

参数

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

返回值

返回一个 256 位整数值。Int256

示例

使用示例

SELECT
    toInt256(-256),
    toInt256(-256.256),
    toInt256('-256')
FORMAT Vertical

Row 1:
──────
toInt256(-256):     -256
toInt256(-256.256): -256
toInt256('-256'):   -256

toInt256OrDefault

引入于：v21.11

与 toInt256 类似，此函数将输入值转换为 Int256 类型的值，但在发生错误时返回默认值。如果未传入 default 值，则在发生错误时返回 0。

语法

toInt256OrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。Int256

返回值

如果转换成功，则返回 Int256 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Int256

示例

成功转换

SELECT toInt256OrDefault('-256', CAST('-1', 'Int256'))

-256

转换失败

SELECT toInt256OrDefault('abc', CAST('-1', 'Int256'))

-1

toInt256OrNull

引入于：v20.8

与 toInt256 类似，此函数将输入值转换为 Int256 类型的值，但在出错时返回 NULL。

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

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

另请参阅：

toInt256。
toInt256OrZero。
toInt256OrDefault。

语法

toInt256OrNull(x)

参数

x — 数字的 String 类型表示。String

返回值

返回 Int256 类型的值；如果转换失败，则返回 NULL。Int256 或 NULL

示例

使用示例

SELECT
    toInt256OrNull('-256'),
    toInt256OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'):  \N

toInt256OrZero

引入于：v20.8

将输入值转换为 Int256 类型，但在发生错误时返回 0。类似于 toInt256，但不会抛出异常，而是返回 0。

另请参阅：

toInt256。
toInt256OrNull。
toInt256OrDefault。

语法

toInt256OrZero(x)

参数

x — 要转换的输入值，类型可以是 String、FixedString、Float*、Decimal、(U)Int*、Date 或 DateTime

返回值

返回转换后的值；如果转换失败，则返回 0。Int256

示例

使用示例

SELECT toInt256OrZero('123')

转换失败时返回 0

SELECT toInt256OrZero('abc')

toInt32

引入于：v1.1

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

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

如果输入值不能在 Int32 的取值范围内表示，则结果会发生上溢或下溢。这不被视为错误。例如：SELECT toInt32(2147483648) == -2147483648;

注意

该函数使用向零舍入，即截断数字的小数部分。

另请参阅：

toInt32OrZero。
toInt32OrNull。
toInt32OrDefault。

语法

toInt32(expr)

参数

expr — 返回数值或其字符串形式的表达式。Expression

返回值

返回一个 32 位整数值。Int32

示例

用法示例

SELECT
    toInt32(-32),
    toInt32(-32.32),
    toInt32('-32')
FORMAT Vertical

Row 1:
──────
toInt32(-32):    -32
toInt32(-32.32): -32
toInt32('-32'):  -32

toInt32OrDefault

引入于：v21.11

与 toInt32 类似，此函数将输入值转换为 Int32 类型的值，但在出错时返回默认值。如果未指定 default 值，则在出错时返回 0。

语法

toInt32OrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。Int32

返回值

成功时返回 Int32 类型的值，否则如果传入了默认值则返回该默认值，如果未传入则返回 0。Int32

示例

转换成功

SELECT toInt32OrDefault('-32', CAST('-1', 'Int32'))

-32

转换失败

SELECT toInt32OrDefault('abc', CAST('-1', 'Int32'))

-1

toInt32OrNull

引入自：v1.1

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

支持的参数：

(U)Int* 的字符串形式。

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

Float* 值的字符串形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串形式，例如 SELECT toInt32OrNull('0xc0fe');。

注意

如果输入值不能在 Int32 的取值范围内表示，则结果会发生上溢或下溢。这不被视为错误。

另请参阅：

toInt32。
toInt32OrZero。
toInt32OrDefault。

语法

toInt32OrNull(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回 Int32 类型的值；如果转换失败则返回 NULL。Int32 或 NULL

示例

用法示例

SELECT
    toInt32OrNull('-32'),
    toInt32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): \N

toInt32OrZero

引入于：v1.1

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

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

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

另请参阅：

toInt32。
toInt32OrNull。
toInt32OrDefault。

语法

toInt32OrZero(x)

参数

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

返回值

返回 Int32 类型的值；如果转换失败则返回 0。Int32

示例

用法示例

SELECT
    toInt32OrZero('32'),
    toInt32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toInt32OrZero('32'): 32
toInt32OrZero('abc'): 0

toInt64

引入于：v1.1

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

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

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

注意

该函数使用向零舍入，即会截断数字的小数部分。

另请参阅：

toInt64OrZero。
toInt64OrNull。
toInt64OrDefault。

语法

toInt64(expr)

参数

expr — 返回数字或数字字符串表示形式的表达式。支持：类型为 (U)Int* 的值或其字符串表示、类型为 Float* 的值。不支持：类型为 Float* 的值（包括 NaN 和 Inf）的字符串表示，以及二进制值和十六进制值的字符串表示。Expression

返回值

返回 64 位整数值。Int64

示例

用法示例

SELECT
    toInt64(-64),
    toInt64(-64.64),
    toInt64('-64')
FORMAT Vertical

Row 1:
──────
toInt64(-64):    -64
toInt64(-64.64): -64
toInt64('-64'):  -64

toInt64OrDefault

引入于：v21.11

与 toInt64 类似，此函数将输入值转换为 Int64 类型的值，但在出错时返回默认值。如果未传入 default 值，则在出错时返回 0。

语法

toInt64OrDefault(expr[, default])

参数

expr — 计算结果为数字或数字字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。Int64

返回值

转换成功时返回 Int64 类型的值；否则，如果传入了默认值则返回默认值，未传入则返回 0。Int64

示例

转换成功

SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))

-64

转换失败

SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))

-1

toInt64OrNull

引入于：v1.1

与 toInt64 类似，此函数将输入值转换为 Int64 类型的值，但在出错时则返回 NULL。

支持的参数：

(U)Int* 的字符串表示形式。

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

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toInt64OrNull('0xc0fe');。

注意

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

另请参阅：

toInt64。
toInt64OrZero。
toInt64OrDefault。

语法

toInt64OrNull(x)

参数

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

返回值

返回 Int64 类型的值，如果转换失败则返回 NULL。Int64 或 NULL

示例

用法示例

SELECT
    toInt64OrNull('-64'),
    toInt64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): \N

toInt64OrZero

自 v1.1 引入

将输入值转换为类型 Int64，但在出错时返回 0。类似于 toInt64，但在发生错误时返回 0，而不是抛出异常。

另请参阅：

toInt64。
toInt64OrNull。
toInt64OrDefault。

语法

toInt64OrZero(x)

参数

x — 要转换的输入值。String 或 FixedString 或 Float* 或 Decimal 或 (U)Int* 或 Date 或 DateTime

返回值

返回转换后的值，如果转换失败则返回 0。Int64

示例

用法示例

SELECT toInt64OrZero('123')

转换失败时返回零

SELECT toInt64OrZero('abc')

toInt8

引入于：v1.1

将输入值转换为 Int8 类型的值。在发生错误时抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示形式。
类型为 Float* 的值。

不支持的参数：

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toInt8('0xc0fe');。

注意

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

注意

该函数使用向零舍入，即截断数字的小数部分。

另请参阅：

toInt8OrZero。
toInt8OrNull。
toInt8OrDefault。

语法

toInt8(expr)

参数

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

返回值

返回一个 8 位整数值。Int8

示例

使用示例

SELECT
    toInt8(-8),
    toInt8(-8.8),
    toInt8('-8')
FORMAT Vertical

Row 1:
──────
toInt8(-8):   -8
toInt8(-8.8): -8
toInt8('-8'): -8

toInt8OrDefault

自 v21.11 起引入

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

语法

toInt8OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。Int8

返回值

如果转换成功，返回 Int8 类型的值；否则在传入默认值时返回该默认值，未传入则返回 0。Int8

示例

转换成功

SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))

-8

转换失败

SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))

-1

toInt8OrNull

引入于：v1.1

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

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

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

另请参阅：

toInt8。
toInt8OrZero。
toInt8OrDefault。

语法

toInt8OrNull(x)

参数

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

返回值

返回 Int8 类型的值，如果转换失败则返回 NULL。Int8 或 NULL

示例

用法示例

SELECT
    toInt8OrNull('-8'),
    toInt8OrNull('abc')
FORMAT Vertical

Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): \N

toInt8OrZero

引入于：v1.1

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

支持的参数：

(U)Int* 的字符串表示形式。

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

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toInt8OrZero('0xc0fe');。

注意

如果输入值不能在 Int8 的取值范围内表示，则结果会发生上溢或下溢。这不被视为错误。

另请参阅：

toInt8。
toInt8OrNull。
toInt8OrDefault。

语法

toInt8OrZero(x)

参数

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

返回值

返回 Int8 类型的值，如果转换失败则返回 0。Int8

示例

用法示例

SELECT
    toInt8OrZero('8'),
    toInt8OrZero('abc')
FORMAT Vertical

Row 1:
──────
toInt8OrZero('8'): 8
toInt8OrZero('abc'): 0

toInterval

引入于：v25.4

从数值和单位字符串创建一个 Interval 类型的值。

此函数提供了一种统一的方式，通过在单个函数中以字符串参数的形式指定单位，来创建不同类型的时间间隔（秒、分、小时、天、周、月、季度、年）。单位字符串不区分大小写。

这等价于调用各个类型专用的函数，例如 toIntervalSecond、toIntervalMinute、toIntervalDay 等，但允许以字符串参数的形式动态指定单位。

语法

toInterval(value, unit)

参数

value — 表示某个单位数量的数值。可以是任意数值类型。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64
unit — 时间单位。必须是常量字符串。有效值：'nanosecond'、'microsecond'、'millisecond'、'second'、'minute'、'hour'、'day'、'week'、'month'、'quarter'、'year'。String

返回值

返回指定类型的 Interval 类型值。结果类型取决于单位：IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter 或 IntervalYear。Interval

示例

使用不同时间单位创建区间

SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months

┌─seconds─┬─days─┬─months─┐
│ 5       │ 3    │ 2      │
└─────────┴──────┴────────┘

在日期运算中使用间隔

SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

动态创建时间间隔

SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)

┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘

toIntervalDay

自 v1.1 引入

返回一个长度为 n 天、数据类型为 IntervalDay 的时间间隔。

语法

toIntervalDay(n)

参数

n — 天数。可以是整数或其字符串形式，也可以是浮点数。(U)Int* 或 Float* 或 String

返回值

返回一个表示 n 天的时间间隔。Interval

示例

用法示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result

┌─────result─┐
│ 2025-06-20 │
└────────────┘

toIntervalHour

自 v1.1 引入

返回一个 IntervalHour 数据类型的、表示 n 小时的时间间隔。

语法

toIntervalHour(n)

参数

n — 小时数。可以是整数、其字符串表示形式，或浮点数。Int* 或 UInt* 或 Float* 或 String

返回值

返回一个持续 n 小时的时间间隔。Interval

示例

用法示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result

┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘

toIntervalMicrosecond

引入版本：v22.6

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

语法

toIntervalMicrosecond(n)

参数

n — 微秒数。(U)Int* 或 Float* 或 String

返回值

返回一个长度为 n 微秒的区间值。Interval

示例

使用示例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result

┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘

toIntervalMillisecond

自 v22.6 起引入

返回一个时长为 n 毫秒、数据类型为 IntervalMillisecond 的时间间隔。

语法

toIntervalMillisecond(n)

参数

n — 毫秒数。(U)Int* 或 Float* 或 String

返回值

返回一个长度为 n 毫秒的时间间隔。Interval

示例

用法示例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result

┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘

toIntervalMinute

自 v1.1 版本引入

返回一个由 n 分钟组成、数据类型为 IntervalMinute 的时间间隔。

语法

toIntervalMinute(n)

参数

n — 分钟数。可以是整数、其字符串表示形式或浮点数。(U)Int* 或 Float* 或 String

返回值

返回一个表示 n 分钟的时间间隔。Interval

示例

用法示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

toIntervalMonth

引入版本：v1.1

返回一个长度为 n 个月、数据类型为 IntervalMonth 的时间间隔。

语法

toIntervalMonth(n)

参数

n — 月份数。(U)Int* 或 Float* 或 String

返回值

返回一个表示 n 个月的时间间隔。Interval

示例

用法示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

┌─────result─┐
│ 2025-07-15 │
└────────────┘

toIntervalNanosecond

引入于：v22.6

返回一个长度为 n 个纳秒的数据区间，数据类型为 IntervalNanosecond。

语法

toIntervalNanosecond(n)

参数

n — 纳秒数。(U)Int* 或 Float* 或 String

返回值

返回一个表示 n 纳秒的时间间隔。Interval

示例

使用示例

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

toIntervalQuarter

引入版本：v1.1

返回一个表示 n 个季度的 IntervalQuarter 类型的时间间隔。

语法

toIntervalQuarter(n)

参数

n — 季度数量。(U)Int* 或 Float* 或 String

返回值

返回一个跨越 n 个季度的时间区间。Interval

示例

用法示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

┌─────result─┐
│ 2025-09-15 │
└────────────┘

toIntervalSecond

引入版本：v1.1

返回一个长度为 n 秒、数据类型为 IntervalSecond 的时间间隔。

语法

toIntervalSecond(n)

参数

n — 秒数。可以是整数、其字符串表示形式或浮点数。(U)Int* 或 Float* 或 String

返回值

返回一个持续 n 秒的时间区间。Interval

示例

用法示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

toIntervalWeek

引入版本：v1.1

返回一个表示 n 周的时间间隔，数据类型为 IntervalWeek。

语法

toIntervalWeek(n)

参数

n — 周数。(U)Int* 或 Float* 或 String

返回值

返回一个持续 n 周的时间间隔。Interval

示例

使用示例

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

┌─────result─┐
│ 2025-06-22 │
└────────────┘

toIntervalYear

引入版本：v1.1

返回一个表示 n 年的 IntervalYear 类型时间间隔。

语法

toIntervalYear(n)

参数

n — 年数。(U)Int* 或 Float* 或 String

返回值

返回一个表示 n 年的时间间隔。Interval

示例

用法示例

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

┌─────result─┐
│ 2025-06-15 │
└────────────┘

toLowCardinality

引入于：v18.12

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

提示

要将 LowCardinality 数据类型转换为普通数据类型，请使用 CAST 函数。例如：CAST(x AS String)。

语法

toLowCardinality(expr)

参数

expr — 其结果为受支持数据类型之一的表达式。String 或 FixedString 或 Date 或 DateTime 或 (U)Int* 或 Float*

返回值

返回将输入值转换为 LowCardinality 数据类型的结果。LowCardinality

示例

使用示例

SELECT toLowCardinality('1')

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

toString

自 v1.1 起引入

将值转换为其字符串表示。对于 DateTime 参数，该函数可以接收第二个 String 参数，用于指定时区名称。

语法

toString(value[, timezone])

参数

value — 要转换为字符串的值。Any
timezone — 可选。用于 DateTime 转换的时区名称。String

返回值

返回输入值的字符串表示形式。String

示例

使用示例

SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10

┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘

toStringCutToZero

引入版本：v1.1

接受一个 String 或 FixedString 参数，并返回一个 String，其中包含原始字符串的副本，但在第一个空字节处被截断。

空字节（\0）被视为字符串终止符。此函数适用于处理 C 风格字符串或二进制数据，在这些场景中空字节用于标记有效内容的结束。

语法

toStringCutToZero(s)

参数

s — 要处理的 String 或 FixedString。String 或 FixedString

返回值

返回一个包含首个空字节（null byte）之前所有字符的 String。String

示例

使用示例

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

toTime

在 v1.1 版本中引入

将输入值转换为 Time 类型。支持从 String、FixedString、DateTime 或表示自午夜起经过秒数的数值类型进行转换。

语法

toTime(x)

参数

x — 要转换的输入值。String 或 FixedString 或 DateTime 或 (U)Int* 或 Float*

返回值

返回转换后的值。Time

示例

将 String 转换为 Time 的示例

SELECT toTime('14:30:25')

14:30:25

将 DateTime 转换为 Time

SELECT toTime(toDateTime('2025-04-15 14:30:25'))

14:30:25

整数到时间的类型转换

SELECT toTime(52225)

14:30:25

toTime64

自 v25.6 起引入

将输入值转换为 Time64 类型。支持从 String、FixedString、DateTime64，或数值类型（表示自午夜起经过的微秒数）进行转换。为时间值提供微秒级精度。

语法

toTime64(x)

参数

x — 要转换的输入值。String 或 FixedString 或 DateTime64 或 (U)Int* 或 Float*

返回值

返回转换后的输入值，精度为微秒。Time64(6)

示例

将 String 转换为 Time64

SELECT toTime64('14:30:25.123456')

14:30:25.123456

将 DateTime64 转换为 Time64

SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))

14:30:25.123456

整数到 Time64 的转换

SELECT toTime64(52225123456)

14:30:25.123456

toTime64OrNull

引入于：v25.6

将输入值转换为 Time64 类型的值，但在出错时返回 NULL。类似于 toTime64，只是当转换出错时返回 NULL，而不是抛出异常。

另请参阅：

toTime64
toTime64OrZero

语法

toTime64OrNull(x)

参数

x — 具有亚秒级精度的时间的字符串表示。String

返回值

成功时返回 Time64 值，否则返回 NULL。Time64 或 NULL

示例

用法示例

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

toTime64OrZero

引入版本：v25.6

将输入值转换为 Time64 类型的值，但在发生错误时返回 00:00:00.000。类似于 toTime64，但在转换出错时返回 00:00:00.000，而不是抛出异常。

语法

toTime64OrZero(x)

参数

x — 具有亚秒级精度的时间字符串表示。String

返回值

如果成功，则返回一个 Time64 值，否则返回 00:00:00.000。Time64

示例

用法示例

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘

toTimeOrNull

引入版本：v1.1

将输入值转换为 Time 类型的值，但在出错时返回 NULL。类似于 toTime，但在转换出错时返回 NULL，而不是抛出异常。

另见：

toTime
toTimeOrZero

语法

toTimeOrNull(x)

参数

x — 表示时间的字符串。String

返回值

成功时返回一个 Time 类型的值，否则返回 NULL。Time 或 NULL

示例

用法示例

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

toTimeOrZero

自 v1.1 引入

将输入值转换为 Time 类型的值，但在出错时返回 00:00:00。与 toTime 类似，但在转换出错时返回 00:00:00，而不是抛出异常。

语法

toTimeOrZero(x)

参数

x — 时间的字符串表示形式。String

返回值

成功时返回一个 Time 类型的值，否则返回 00:00:00。Time

示例

使用示例

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

toUInt128

引入自：v1.1

将输入值转换为 UInt128 类型的值。在发生错误时抛出异常。该函数使用向零舍入方式，即截断数值的小数部分。

支持的参数：

类型为 (U)Int* 的值或其字符串表示形式。
类型为 Float* 的值。

不支持的参数：

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

注意

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

另请参阅：

toUInt128OrZero。
toUInt128OrNull。
toUInt128OrDefault。

语法

toUInt128(expr)

参数

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

返回值

返回一个 128 位无符号整数值。UInt128

示例

用法示例

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

toUInt128OrDefault

引入版本：v21.11

与 toUInt128 类似，此函数将输入值转换为 UInt128 类型的值，但在发生错误时返回默认值。如果未传入 default 值，则在出错时返回 0。

语法

toUInt128OrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。UInt128

返回值

如果转换成功，则返回 UInt128 类型的值；否则，如果传入了默认值，则返回该默认值；未传入时返回 0。UInt128

示例

成功转换

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

转换失败

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

toUInt128OrNull

引入自：v21.6

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

支持的参数：

(U)Int* 的字符串表示形式。

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

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toUInt128OrNull('0xc0fe');。

注意

如果输入值不能在 UInt128 的取值范围内表示，则结果会发生上溢或下溢。这不会被视为错误。

另请参见：

toUInt128。
toUInt128OrZero。
toUInt128OrDefault。

语法

toUInt128OrNull(x)

参数

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

返回值

返回 UInt128 类型的值；如果转换失败，则返回 NULL。UInt128 或 NULL

示例

使用示例

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

toUInt128OrZero

引入于：v1.1

与 toUInt128 类似，此函数将输入值转换为 UInt128 类型的值，但在出错时返回 0。

支持的参数：

(U)Int* 的字符串表示形式。

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

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toUInt128OrZero('0xc0fe');。

注意

如果输入值不能在 UInt128 的取值范围内表示，则结果会发生上溢或下溢。这不被视为错误。

另请参阅：

toUInt128。
toUInt128OrNull。
toUInt128OrDefault。

语法

toUInt128OrZero(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回 UInt128 类型的值，如果转换失败，则返回 0。UInt128

示例

用法示例

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

toUInt16

引入于：v1.1

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

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

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

注意

该函数采用向零舍入，即截断数值的小数部分。

另请参阅：

toUInt16OrZero。
toUInt16OrNull。
toUInt16OrDefault。

语法

toUInt16(expr)

参数

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

返回值

返回一个 16 位无符号整数值。UInt16

示例

使用示例

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

toUInt16OrDefault

引入于：v21.11

与 toUInt16 类似，此函数将输入值转换为 UInt16 类型的值，但在发生错误时返回默认值。如果未传入 default 值，则在发生错误时返回 0。

语法

toUInt16OrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。UInt16

返回值

解析成功时返回 UInt16 类型的值；否则返回传入的默认值；如果未传入默认值，则返回 0。UInt16

示例

成功转换

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

转换失败

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

toUInt16OrNull

引入于：v1.1

与 toUInt16 类似，此函数将输入值转换为 UInt16 类型的值，但在出错时返回 NULL。

支持的参数：

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

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

Float* 类型值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如：SELECT toUInt16OrNull('0xc0fe');。

注意

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

另请参阅：

toUInt16。
toUInt16OrZero。
toUInt16OrDefault。

语法

toUInt16OrNull(x)

参数

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

返回值

返回 UInt16 类型的值，如果转换失败则返回 NULL。UInt16 或 NULL

示例

用法示例

SELECT
    toUInt16OrNull('16'),
    toUInt16OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): \N

toUInt16OrZero

引入于：v1.1

与 toUInt16 类似，此函数将输入值转换为 UInt16 类型的值，但在出错时返回 0。

支持的参数：

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

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

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

注意

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

另请参阅：

toUInt16。
toUInt16OrNull。
toUInt16OrDefault。

语法

toUInt16OrZero(x)

参数

x — 数字的 String 类型表示。String

返回值

返回 UInt16 类型的值，如果转换失败则返回 0。UInt16

示例

用法示例

SELECT
    toUInt16OrZero('16'),
    toUInt16OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt16OrZero('16'):  16
toUInt16OrZero('abc'): 0

toUInt256

自 v1.1 引入

将输入值转换为 UInt256 类型的值。在发生错误时抛出异常。该函数采用向零舍入方式，即会截断数字的小数部分。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

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

另请参阅：

toUInt256OrZero。
toUInt256OrNull。
toUInt256OrDefault。

语法

toUInt256(expr)

参数

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

返回值

返回 256 位无符号整数值。UInt256

示例

使用示例

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

toUInt256OrDefault

引入自：v21.11

与 toUInt256 类似，此函数将输入值转换为 UInt256 类型的值，但在出错时返回默认值。如果未传入 default 值，则在发生错误时返回 0。

语法

toUInt256OrDefault(expr[, default])

参数

expr — 返回数字或数字的字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。UInt256

返回值

如果解析成功，返回 UInt256 类型的值；否则返回传入的默认值；如果未传入默认值，则返回 0。UInt256

示例

转换成功

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

转换失败

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

toUInt256OrNull

引入于：v20.8

与 toUInt256 类似，此函数将输入值转换为 UInt256 类型的值，但在出错时返回 NULL。

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

如果输入值不能在 UInt256 的取值范围内表示，结果会发生上溢或下溢。这不被视为错误。

另请参阅：

toUInt256。
toUInt256OrZero。
toUInt256OrDefault。

语法

toUInt256OrNull(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回类型为 UInt256 的值，如果转换失败则返回 NULL。UInt256 或 NULL

示例

用法示例

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

toUInt256OrZero

引入版本：v20.8

与 toUInt256 类似，此函数将输入值转换为 UInt256 类型的值，但在出错时返回 0。

支持的参数：

(U)Int* 的字符串表示。

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

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

注意

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

另请参阅：

toUInt256。
toUInt256OrNull。
toUInt256OrDefault。

语法

toUInt256OrZero(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回 UInt256 类型的值；如果转换失败，则返回 0。UInt256

示例

使用示例

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

toUInt32

自 v1.1 起引入

将输入值转换为 UInt32 类型的值。在发生错误时抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串形式。
类型为 Float* 的值。

不支持的参数：

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

注意

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

注意

该函数使用向零舍入方式，即会截断数字的小数部分。

另请参阅：

toUInt32OrZero。
toUInt32OrNull。
toUInt32OrDefault。

语法

toUInt32(expr)

参数

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

返回值

返回一个 32 位无符号整数。UInt32

示例

使用示例

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

toUInt32OrDefault

引入于：v21.11

类似于 toUInt32，此函数将输入值转换为类型为 UInt32 的值，但在发生错误时返回默认值。如果未传入 default 值，则在发生错误时返回 0。

语法

toUInt32OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。UInt32

返回值

如果解析成功，则返回类型为 UInt32 的值；否则在传入默认值时返回该默认值，未传入时返回 0。UInt32

示例

成功转换

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

转换失败

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

toUInt32OrNull

引入于：v1.1

与 toUInt32 类似，此函数将输入值转换为 UInt32 类型的值，但在出错时返回 NULL。

支持的参数：

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

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

Float* 类型值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如：SELECT toUInt32OrNull('0xc0fe');。

注意

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

另请参阅：

toUInt32。
toUInt32OrZero。
toUInt32OrDefault。

语法

toUInt32OrNull(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回 UInt32 类型的值，如果转换不成功则返回 NULL。UInt32 或 NULL

示例

使用示例

SELECT
    toUInt32OrNull('32'),
    toUInt32OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

toUInt32OrZero

引入于：v1.1

与 toUInt32 类似，此函数将输入值转换为 UInt32 类型的值，但在出错时返回 0。

支持的参数：

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

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

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

注意

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

另请参阅：

toUInt32。
toUInt32OrNull。
toUInt32OrDefault。

语法

toUInt32OrZero(x)

参数

x — 数字的 String 类型表示。String

返回值

返回 UInt32 类型的值，若转换失败则返回 0。UInt32

示例

用法示例

SELECT
    toUInt32OrZero('32'),
    toUInt32OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt32OrZero('32'):  32
toUInt32OrZero('abc'): 0

toUInt64

引入于：v1.1

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

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的类型：

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

注意

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

注意

该函数采用向零舍入方式，即截断数字的小数部分。

另请参阅：

toUInt64OrZero。
toUInt64OrNull。
toUInt64OrDefault。

语法

toUInt64(expr)

参数

expr — 结果为数字或数字字符串表示形式的表达式。Expression

返回值

返回 64 位无符号整数值。UInt64

示例

用法示例

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

toUInt64OrDefault

引入于：v21.11

与 toUInt64 类似，此函数将输入值转换为 UInt64 类型的值，但在发生错误时返回默认值。如果未传入 default 值，则在发生错误时返回 0。

语法

toUInt64OrDefault(expr[, default])

参数

expr — 返回数字或其字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时返回的默认值。UInt64

返回值

如果转换成功，返回 UInt64 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。UInt64

示例

转换成功

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

转换失败

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

toUInt64OrNull

引入版本：v1.1

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

支持的参数：

(U)Int* 的字符串表示形式。

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

Float* 值的字符串表示形式，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示形式，例如：SELECT toUInt64OrNull('0xc0fe');。

注意

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

另请参阅：

toUInt64。
toUInt64OrZero。
toUInt64OrDefault。

语法

toUInt64OrNull(x)

参数

x — 数字的 String 类型表示形式。String

返回值

返回 UInt64 类型的值，若转换失败则返回 NULL。UInt64 或 NULL

示例

使用示例

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

toUInt64OrZero

引入版本：v1.1

类似于 toUInt64，此函数将输入值转换为 UInt64 类型的值，但在出错时返回 0。

支持的参数：

(U)Int* 整数类型的字符串表示。

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

Float* 浮点类型值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt64OrZero('0xc0fe');。

注意

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

另请参阅：

toUInt64。
toUInt64OrNull。
toUInt64OrDefault。

语法

toUInt64OrZero(x)

参数

x — 数字的 String 类型表示。String

返回值

返回 UInt64 类型的值，如果转换失败则返回 0。UInt64

示例

用法示例

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

toUInt8

引入于：v1.1

将输入值转换为 UInt8 类型的值。在发生错误时抛出异常。

支持的参数：

类型为 (U)Int* 的值或其字符串表示。
类型为 Float* 的值。

不支持的参数：

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

注意

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

注意

该函数使用向零舍入，即会截断数值的小数部分。

另请参阅：

toUInt8OrZero。
toUInt8OrNull。
toUInt8OrDefault。

语法

toUInt8(expr)

参数

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

返回值

返回一个 8 位无符号整数值。UInt8

示例

用法示例

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

toUInt8OrDefault

引入自：v21.11

与 toUInt8 类似，此函数将输入值转换为 UInt8 类型的值，但在出错时返回默认值。如果未传入 default 值，则在出错时返回 0。

语法

toUInt8OrDefault(expr[, default])

参数

expr — 求值为数字或数字字符串表示形式的表达式。String 或 (U)Int* 或 Float*
default — 可选。解析失败时要返回的默认值。UInt8

返回值

如果转换成功，返回类型为 UInt8 的值；否则，如果传入了默认值则返回该默认值，如果未传入则返回 0。UInt8

示例

成功转换

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

转换失败时

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

toUInt8OrNull

引入版本：v1.1

与 toUInt8 类似，此函数将输入值转换为 UInt8 类型的值，但在出错时返回 NULL。

支持的参数：

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

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

普通 Float* 类型值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如：SELECT toUInt8OrNull('0xc0fe');。

注意

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

另请参阅：

toUInt8。
toUInt8OrZero。
toUInt8OrDefault。

语法

toUInt8OrNull(x)

参数

x — 数字的 String 类型表示。String

返回值

返回 UInt8 类型的值，如果转换失败则返回 NULL。UInt8 或 NULL

示例

用法示例

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

toUInt8OrZero

自 v1.1 起提供

与 toUInt8 类似，此函数会将输入值转换为 UInt8 类型的值，但在出错时返回 0。

支持的参数：

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

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

常规 Float* 类型值的字符串表示，包括 NaN 和 Inf。
二进制和十六进制值的字符串表示，例如 SELECT toUInt8OrZero('0xc0fe');。

注意

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

另请参阅：

toUInt8。
toUInt8OrNull。
toUInt8OrDefault。

语法

toUInt8OrZero(x)

参数

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

返回值

返回 UInt8 类型的值，如果转换失败则返回 0。UInt8

示例

用法示例

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

toUUID

自 v1.1 引入

将 String 类型的值转换为 UUID 类型的值。

语法

toUUID(string)

参数

string — UUID 的字符串表示。String 或 FixedString

返回值

根据 UUID 的字符串表示返回一个 UUID 值。UUID

示例

用法示例

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrZero

自 v20.12 引入

将输入值转换为 UUID 类型的值，但在发生错误时返回全零 UUID。类似于 toUUID，但在转换出错时返回全零 UUID（00000000-0000-0000-0000-000000000000），而不是抛出异常。

支持的参数：

标准格式的 UUID 字符串表示（8-4-4-4-12 个十六进制数字）。
不带连字符的 UUID 字符串表示（32 个十六进制数字）。

不支持的参数（返回全零 UUID）：

无效的字符串格式。
非字符串类型。

语法

toUUIDOrZero(x)

参数

x — UUID 的字符串形式。String

返回值

如果成功，则返回 UUID 值，否则返回全零 UUID（00000000-0000-0000-0000-000000000000）。UUID

示例

用法示例

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

toUnixTimestamp64Micro

自 v20.5 引入

将 DateTime64 转换为具有固定微秒精度的 Int64 值。输入值会根据其自身精度被相应地放大或缩小。

注意

输出值是相对于 UTC 的，而不是相对于输入值所在的时区。

语法

toUnixTimestamp64Micro(value)

参数

value — 任意精度的 DateTime64 值。DateTime64

返回值

返回以微秒为单位的 Unix 时间戳。Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

┌─toUnixTimestamp64Micro(dt64)─┐
│               1739489491011123 │
└────────────────────────────────┘

toUnixTimestamp64Milli

引入版本：v20.5

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

注意

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Milli(value)

参数

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

返回值

返回以毫秒为单位的 Unix 时间戳。Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

toUnixTimestamp64Nano

引入版本：v20.5

将 DateTime64 转换为具有固定纳秒精度的 Int64 值。输入值会根据其精度被相应地放大或缩小。

注意

输出值是相对于 UTC 的，而不是相对于输入值所在的时区。

语法

toUnixTimestamp64Nano(value)

参数

value — 任意精度的 DateTime64 值。DateTime64

返回值

返回以纳秒为单位的 Unix 时间戳。Int64

示例

用法示例

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

┌─toUnixTimestamp64Nano(dt64)────┐
│            1739489491011123456 │
└────────────────────────────────┘

toUnixTimestamp64Second

引入于：v24.12

将 DateTime64 转换为具有固定秒级精度的 Int64 值。输入值会根据其自身精度按比例进行相应的放大或缩小。

注意

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Second(value)

参数

value — 任意精度的 DateTime64 值。DateTime64

返回值

返回以秒为单位的 Unix 时间戳。Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘

数据转换中的常见问题​

关于 toString 函数的说明​

关于 toDate/toDateTime 函数的说明​

CAST​

accurateCast​

accurateCastOrDefault​

accurateCastOrNull​

formatRow​

formatRowNoNewline​

fromUnixTimestamp64Micro​

fromUnixTimestamp64Milli​

fromUnixTimestamp64Nano​

fromUnixTimestamp64Second​

parseDateTime​

parseDateTime32BestEffort​

parseDateTime32BestEffortOrNull​

parseDateTime32BestEffortOrZero​

parseDateTime64​

parseDateTime64BestEffort​

parseDateTime64BestEffortOrNull​

parseDateTime64BestEffortOrZero​

parseDateTime64BestEffortUS​

parseDateTime64BestEffortUSOrNull​

parseDateTime64BestEffortUSOrZero​

parseDateTime64InJodaSyntax​

parseDateTime64InJodaSyntaxOrNull​

parseDateTime64InJodaSyntaxOrZero​

parseDateTime64OrNull​

parseDateTime64OrZero​

parseDateTimeBestEffort​

parseDateTimeBestEffortOrNull​

parseDateTimeBestEffortOrZero​

parseDateTimeBestEffortUS​

parseDateTimeBestEffortUSOrNull​

parseDateTimeBestEffortUSOrZero​

parseDateTimeInJodaSyntax​

parseDateTimeInJodaSyntaxOrNull​

parseDateTimeInJodaSyntaxOrZero​

parseDateTimeOrNull​

parseDateTimeOrZero​

reinterpret​

reinterpretAsDate​

reinterpretAsDateTime​

reinterpretAsFixedString​

reinterpretAsFloat32​

reinterpretAsFloat64​

reinterpretAsInt128​

reinterpretAsInt16​

reinterpretAsInt256​

reinterpretAsInt32​

reinterpretAsInt64​

reinterpretAsInt8​

reinterpretAsString​

reinterpretAsUInt128​

reinterpretAsUInt16​

reinterpretAsUInt256​

reinterpretAsUInt32​

reinterpretAsUInt64​

reinterpretAsUInt8​

reinterpretAsUUID​

toBFloat16​

toBFloat16OrNull​

toBFloat16OrZero​

toBool​

toDate​

toDate32​

toDate32OrDefault​

toDate32OrNull​

toDate32OrZero​

toDateOrDefault​

toDateOrNull​

toDateOrZero​

toDateTime​

toDateTime32​

toDateTime64​

toDateTime64OrDefault​

toDateTime64OrNull​

toDateTime64OrZero​

toDateTimeOrDefault​

toDateTimeOrNull​

数据转换中的常见问题

关于 `toString` 函数的说明

关于 `toDate`/`toDateTime` 函数的说明

CAST

accurateCast

accurateCastOrDefault

accurateCastOrNull

formatRow

formatRowNoNewline

fromUnixTimestamp64Micro

fromUnixTimestamp64Milli

fromUnixTimestamp64Nano

fromUnixTimestamp64Second

parseDateTime

parseDateTime32BestEffort

parseDateTime32BestEffortOrNull

parseDateTime32BestEffortOrZero

parseDateTime64

parseDateTime64BestEffort

parseDateTime64BestEffortOrNull

parseDateTime64BestEffortOrZero

parseDateTime64BestEffortUS

parseDateTime64BestEffortUSOrNull

parseDateTime64BestEffortUSOrZero

parseDateTime64InJodaSyntax

parseDateTime64InJodaSyntaxOrNull

parseDateTime64InJodaSyntaxOrZero

parseDateTime64OrNull

parseDateTime64OrZero

parseDateTimeBestEffort

parseDateTimeBestEffortOrNull

parseDateTimeBestEffortOrZero

parseDateTimeBestEffortUS

parseDateTimeBestEffortUSOrNull

parseDateTimeBestEffortUSOrZero

parseDateTimeInJodaSyntax

parseDateTimeInJodaSyntaxOrNull

parseDateTimeInJodaSyntaxOrZero

parseDateTimeOrNull

parseDateTimeOrZero

reinterpret

reinterpretAsDate

reinterpretAsDateTime

reinterpretAsFixedString

reinterpretAsFloat32

reinterpretAsFloat64

reinterpretAsInt128

reinterpretAsInt16

reinterpretAsInt256

reinterpretAsInt32

reinterpretAsInt64

reinterpretAsInt8

reinterpretAsString

reinterpretAsUInt128

reinterpretAsUInt16

reinterpretAsUInt256

reinterpretAsUInt32

reinterpretAsUInt64

reinterpretAsUInt8

reinterpretAsUUID

toBFloat16

toBFloat16OrNull

toBFloat16OrZero

toBool

toDate

toDate32

toDate32OrDefault

toDate32OrNull

toDate32OrZero

toDateOrDefault

toDateOrNull

toDateOrZero

toDateTime

toDateTime32

toDateTime64

toDateTime64OrDefault

toDateTime64OrNull

toDateTime64OrZero

toDateTimeOrDefault

toDateTimeOrNull