类型转换函数

类型转换函数的文档

​

数据转换中的常见问题

ClickHouse 通常采用与 C++ 程序相同的行为。

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 函数可以接受第二个 String 参数，该参数包含时区名称，例如：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++ 中不同数值类型之间赋值相同的规则。

示例

Query

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

Response

┌──────────────────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

Introduced in：v1.1.0

将一个值转换为指定的数据类型。 与 reinterpret 函数不同，CAST 会尝试在目标类型中得到相同的值。 如果无法实现，则会引发异常。

Syntax

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

参数

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

返回值

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

示例

基本用法

Query

SELECT CAST(42, 'String')

Response

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

使用 AS 语法

Query

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

Response

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

使用 :: 语法

Query

SELECT '123'::UInt32

Response

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

​

DATE

引入于：v21.2.0

将参数转换为 Date 数据类型。这是 toDate 的 MySQL 兼容别名，行为与 toDate 相同。

语法

DATE(expr)

参数

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

返回值

返回 Date 值。Date

示例

基本用法

Query

SELECT DATE('2023-01-01')

Response

2023-01-01

​

accurateCast

引入版本：v1.1.0

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

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

语法

accurateCast(x, T)

参数

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

返回值

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

示例

转换成功

Query

SELECT accurateCast(42, 'UInt16')

Response

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

字符串转为数字

Query

SELECT accurateCast('123.45', 'Float64')

Response

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

​

accurateCastOrDefault

引入版本：v21.1.0

将值转换为指定的数据类型。 与 accurateCast 类似，但如果无法进行精确转换，则返回默认值，而不是抛出异常。

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

语法

accurateCastOrDefault(x, T[, default_value])

参数

• x — 要转换的值。Any
• T — 目标数据类型名称。const String
• default_value — 可选。如果转换失败，返回此默认值。Any

返回值

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

示例

转换成功

Query

SELECT accurateCastOrDefault(42, 'String')

Response

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

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

Query

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

Response

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

使用隐式默认值的转换失败

Query

SELECT accurateCastOrDefault('abc', 'UInt32')

Response

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

​

accurateCastOrNull

引入版本：v1.1.0

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

此函数结合了 accurateCast 的安全性以及更平稳的错误处理方式。

语法

accurateCastOrNull(x, T)

参数

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

返回值

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

示例

转换成功

Query

SELECT accurateCastOrNull(42, 'String')

Response

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

转换失败则返回 NULL

Query

SELECT accurateCastOrNull('abc', 'UInt32')

Response

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

​

formatRow

引入版本：v20.7.0

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

如果格式包含前缀/后缀，它们会写入每一行。 此函数仅支持基于行的格式。

语法

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

参数

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

返回值

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

示例

基本用法

Query

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

Response

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

使用自定义格式

Query

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

Response

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

​

formatRowNoNewline

引入版本：v20.7.0

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

通过指定的格式将任意表达式转换为字符串，但会移除结果末尾的所有换行符。

语法

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

参数

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

返回值

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

示例

基本用法

Query

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

Response

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

​

fromUnixTimestamp64Micro

引入于：v20.5.0

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

输入值会被视为具有微秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 起经过的微秒数) 。

语法

fromUnixTimestamp64Micro(value[, timezone])

参数

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

返回值

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

示例

使用示例

Query

SELECT fromUnixTimestamp64Micro(1640995200123456)

Response

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

​

fromUnixTimestamp64Milli

引入版本：v20.5.0

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

输入值会被视为毫秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 起经过的毫秒数) 。

语法

fromUnixTimestamp64Milli(value[, timezone])

参数

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

返回值

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

示例

用法示例

Query

SELECT fromUnixTimestamp64Milli(1640995200123)

Response

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

​

fromUnixTimestamp64Nano

引入版本：v20.5.0

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

输入值会被视为纳秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 以来的纳秒数) 。

请注意，输入值会被视为 UTC 时间戳，而不是按输入值自身的时区来处理。

语法

fromUnixTimestamp64Nano(value[, timezone])

参数

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

返回值

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

示例

用法示例

Query

SELECT fromUnixTimestamp64Nano(1640995200123456789)

Response

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

​

fromUnixTimestamp64Second

引入版本：v24.12.0

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

输入值会被视为秒精度的 Unix 时间戳 (自 1970-01-01 00:00:00 UTC 起经过的秒数) 。

语法

fromUnixTimestamp64Second(value[, timezone])

参数

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

返回值

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

示例

用法示例

Query

SELECT fromUnixTimestamp64Second(1640995200)

Response

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

​

kqlParameterCast

引入版本：v26.9.0

根据声明的 Kusto 查询语言类型检查值，并将其转换为该类型对应的 ClickHouse 承载类型：类型不属于所声明 KQL 类型的参数会在分析阶段被 拒绝，而不符合要求的值 (例如 int 溢出) 则会产生逐行 错误。第二个参数是声明的 KQL 类型名称，第三个参数用于在错误消息中描述该 参数；两者都必须是常量字符串。

当 dialect = 'kusto' 时，此函数用于支持带类型的函数参数。不应直接在 SQL 中 调用此函数。

语法

kqlParameterCast(value, type, parameter)

参数

• value — KQL 函数调用传入的参数。- type — 声明的 KQL 类型名称，为常量字符串。- parameter — 参数说明，为错误消息中使用的常量字符串。

返回值

value，以声明类型的 ClickHouse 承运商形式返回。

示例

long

Query

SELECT kqlParameterCast(5, 'long', 'the parameter') AS x, toTypeName(x)

Response

5	Int64

real

Query

SELECT kqlParameterCast(5, 'real', 'the parameter') AS x, toTypeName(x)

Response

5	Float64

​

kqlToTimespan

引入版本：v26.8.0

将值转换为 timespan (以纳秒为单位的 Interval) ，其行为与 Kusto 查询语言中的 totimespan() 相同：timespan 保持不变，数值按天数处理，字符串则按 [-][d.]hh:mm:ss[.fffffff] 格式解析；解析失败时转换为 NULL。

当 dialect = 'kusto' 时，此函数为 totimespan() 提供底层支持。它不应直接通过 SQL 调用。

语法

kqlToTimespan(x)

参数

• x — timespan、天数或表示 timespan 的字符串。

返回值

以纳秒时间间隔表示的值；如果字符串不表示 timespan，则返回 NULL。

示例

字符串

Query

SELECT kqlToTimespan('0.00:01:00')

Response

60000000000

天

Query

SELECT kqlToTimespan(2)

Response

172800000000000

​

parseDateTime

引入版本：v23.3.0

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

此函数是 formatDateTime 的逆函数。 它使用格式 String 解析 String 参数，并返回 DateTime 类型。

语法

parseDateTime(time_string, format[, timezone])

别名: TO_UNIXTIME

参数

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

返回值

根据 MySQL 风格的格式字符串，从输入字符串解析出的 DateTime。DateTime

示例

使用示例

Query

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

Response

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

​

parseDateTime32BestEffort

Introduced in: v20.9.0

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

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

语法

parseDateTime32BestEffort(time_string[, time_zone])

参数

• time_string — 包含待转换日期和时间的 String。String
• time_zone — 可选。解析 time_string 时所依据的时区。String

返回值

将 time_string 以 DateTime 类型返回。DateTime

示例

使用示例

Query

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

Response

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

带时区

Query

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

Response

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

Unix 时间戳

Query

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

Response

┌─parseDateTime32BestEffort─┐
│       2010-09-10 06:51:25 │
└───────────────────────────┘

​

parseDateTime32BestEffortOrNull

引入版本：v20.9.0

与 parseDateTime32BestEffort 相同，但在遇到无法处理的日期格式时会返回 NULL。

语法

parseDateTime32BestEffortOrNull(time_string[, time_zone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

parseDateTime32BestEffortOrZero

引入版本：v20.9.0

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

语法

parseDateTime32BestEffortOrZero(time_string[, time_zone])

参数

• time_string — 包含待转换日期和时间的 String。String
• time_zone — 可选。解析 time_string 时所依据的时区。String

返回值

返回从字符串解析出的 DateTime 对象；如果解析失败，则返回零日期 (1970-01-01 00:00:00) 。DateTime

示例

使用示例

Query

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

Response

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

​

parseDateTime64

引入版本：v24.11.0

按照 MySQL 日期格式字符串，解析带有子秒级精度的日期时间字符串。

对于 DateTime64，此函数是 formatDateTime 的逆操作。 它使用 格式 String 解析一个 String 参数。返回 DateTime64 类型，可表示 0000 年到 9999 年之间、具有子秒级精度的日期时间值 (较高精度覆盖的范围更窄，因为该值以 Int64 tick 数存储：精度 8 可到约 4892 年，精度 9 覆盖 1677 年到 2262 年) 。

语法

parseDateTime64(time_string, format[, timezone])

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

parseDateTime64BestEffort

在 v20.1.0 中引入

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

语法

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

参数

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

返回值

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

示例

用法示例

Query

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

Response

┌──────────────────────────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.0

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

语法

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

参数

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

返回值

返回转换后的 DateTime64 类型 time_string；如果输入无法解析，则返回 NULL。DateTime64 或 NULL

示例

用法示例

Query

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

Response

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

​

parseDateTime64BestEffortOrZero

引入版本：v20.1.0

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

语法

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

参数

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

返回值

返回转换后的 DateTime64 类型 time_string；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 00:00:00.000) 。DateTime64

示例

使用示例

Query

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

Response

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

​

parseDateTime64BestEffortUS

引入版本：v22.8.0

与 parseDateTime64BestEffort 相同，但在日期格式存在歧义时，此函数会优先采用美国日期格式 (MM/DD/YYYY 等) 。

语法

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

参数

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

返回值

返回将 time_string 转换为 DateTime64 后的结果；对于有歧义的情况，优先按美国日期格式解析。DateTime64

示例

使用示例

Query

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

Response

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

​

parseDateTime64BestEffortUSOrNull

引入版本：v22.8.0

与 parseDateTime64BestEffort 相同，不同之处在于：当日期格式存在歧义时，此函数会优先采用美国日期格式 (MM/DD/YYYY 等) ；当遇到无法处理的日期格式时，则返回 NULL。

语法

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

参数

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

返回值

返回采用美国日期格式优先规则解析后转换得到的 DateTime64 类型值；如果输入无法解析，则返回 NULL。(DateTime64 或 NULL)

示例

使用示例

Query

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

Response

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

​

parseDateTime64BestEffortUSOrZero

引入版本：v22.8.0

与 parseDateTime64BestEffort 相同，不同之处在于，此函数在存在歧义时会优先使用美国日期格式 (MM/DD/YYYY 等) ，并且在遇到无法处理的日期格式时会返回零日期或零日期时间。

语法

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

参数

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

返回值

返回按美国日期格式优先规则转换后的 time_string 的 DateTime64 值；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 00:00:00.000) 。DateTime64

示例

使用示例

Query

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

Response

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

​

parseDateTime64InJodaSyntax

引入版本：v24.10.0

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

对于 DateTime64，此函数是 formatDateTimeInJodaSyntax 的逆操作。 它使用 Joda 风格的格式 String 解析一个 String 类型的参数。返回 DateTime64 类型，可表示 0000 年至 9999 年间且具有子秒级精度的日期和时间 (较高精度覆盖的范围更窄，因为该值以 Int64 tick 数存储：精度 8 最远可达约 4892 年，精度 9 的范围为 1677 年至 2262 年) 。

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

语法

parseDateTime64InJodaSyntax(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

parseDateTime64InJodaSyntaxOrNull

Introduced in: v24.10.0

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

Syntax

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

┌─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.0

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

语法

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

┌─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.0

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

语法

parseDateTime64OrNull(time_string, format[, timezone])

参数

• time_string — 将被解析为 DateTime64 的字符串。String
• format — 指定 time_string 解析方式的格式字符串。String
• timezone — 可选。时区。String

返回值

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

示例

用法示例

Query

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

Response

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

​

parseDateTime64OrZero

引入版本：v24.11.0

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

语法

parseDateTime64OrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

parseDateTimeBestEffort

版本引入：v1.1.0

将 String 字符串表示形式中的日期和时间转换为 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。String
• time_zone — 可选。解析 time_string 时使用的时区。String

返回值

返回 DateTime 类型的 time_string。DateTime

示例

用法示例

Query

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

Response

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

带有时区

Query

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

Response

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

Unix 时间戳

Query

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

Response

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

​

parseDateTimeBestEffortOrNull

引入版本：v1.1.0

与 parseDateTimeBestEffort 相同，不同之处在于当遇到无法处理的日期格式时，它会返回 NULL。 该函数可解析 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。

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

语法

parseDateTimeBestEffortOrNull(time_string[, time_zone])

参数

• time_string — 包含待转换日期和时间的 String。String
• time_zone — 可选。用于解析 time_string 的时区。String

返回值

time_string 会以 DateTime 形式返回；如果输入无法解析，则返回 NULL。DateTime 或 NULL

示例

使用示例

Query

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

Response

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

​

parseDateTimeBestEffortOrZero

引入版本：v1.1.0

与 parseDateTimeBestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。 该函数可解析 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。

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

语法

parseDateTimeBestEffortOrZero(time_string[, time_zone])

参数

• time_string — 包含要转换的日期和时间的 String。String
• time_zone — 可选。解析 time_string 时所依据的时区。String

返回值

将 time_string 作为 DateTime 返回；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 或 1970-01-01 00:00:00) 。DateTime

示例

使用示例

Query

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

Response

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

​

parseDateTimeBestEffortUS

引入于：v1.1.0

对于 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。String
• time_zone — 可选。解析 time_string 时使用的时区。String

返回值

返回将 time_string 解析为 DateTime 的结果；对于有歧义的情况，优先按照美国日期格式进行解析。DateTime

示例

使用示例

Query

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

Response

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

​

parseDateTimeBestEffortUSOrNull

引入版本：v1.1.0

与 parseDateTimeBestEffortUS 函数相同，不同之处在于：当遇到无法处理的日期格式时，它会返回 NULL。

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

语法

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

参数

• time_string — 包含待转换日期和时间的 String。String
• time_zone — 可选。解析 time_string 时所依据的时区。String

返回值

将 time_string 按照美国日期格式优先规则解析为 DateTime 并返回；如果输入无法解析，则返回 NULL。DateTime 或 NULL

示例

用法示例

Query

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

Response

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

​

parseDateTimeBestEffortUSOrZero

引入版本：v1.1.0

与 parseDateTimeBestEffortUS 函数相同，但当遇到无法处理的日期格式时，它会返回零日期 (1970-01-01) 或零日期时间 (1970-01-01 00:00:00) 。

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

语法

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

参数

• time_string — 包含要转换的日期和时间的 String。String
• time_zone — 可选。按此时区解析 time_string。String

返回值

以美国日期格式优先规则的方式将 time_string 解析为 DateTime 并返回；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 或 1970-01-01 00:00:00) 。DateTime

示例

使用示例

Query

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

Response

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

​

parseDateTimeInJodaSyntax

引入版本：v23.3.0

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

此函数是 formatDateTimeInJodaSyntax 的逆操作。 它使用 Joda 风格的格式 String 解析 String 参数，并返回 DateTime 类型。

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

语法

parseDateTimeInJodaSyntax(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

parseDateTimeInJodaSyntaxOrNull

引入版本：v23.3.0

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

语法

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

parseDateTimeInJodaSyntaxOrZero

引入版本：v23.3.0

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

语法

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

parseDateTimeOrNull

版本引入：v23.3.0

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

语法

parseDateTimeOrNull(time_string, format[, timezone])

别名: str_to_date

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

parseDateTimeOrZero

在以下版本中引入：v23.3.0

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

语法

parseDateTimeOrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpret

引入版本：v1.1.0

对给定的值 x，使用其在内存中的同一源字节序列，并将其重新解释为目标类型。 当目标类型为 String 时，仅当源 Array 的元素类型为定长且在内存中连续存放时才支持 (例如，Array(UInt8) 或 Array(FixedString(2))) ；其元素字节会按照其原生内存顺序原样复制，因此在任何架构上，都可以将结果重新解释回原始 Array 类型。元素为变长 (例如，Array(String)) 或 Nullable (例如，Array(Nullable(Int32))) 的数组不受支持。

语法

reinterpret(x, type)

参数

• x — 要重新解释的值。重新解释为 String 时，源 Array 的元素必须是定长且连续存储的。Any
• type — 目标类型。若为数组，则其元素类型必须为定长类型。String

返回值

目标类型的值。Any

示例

用法示例

Query

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

Response

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

Array 示例

Query

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

Response

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

Array 到 String 示例

Query

SELECT hex(reinterpret([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8), 'String')) AS array_of_UInt8_to_string

Response

┌─array_of_UInt8_to_string─┐
│ 0102FF                   │
└──────────────────────────┘

​

reinterpretAsDate

引入版本：v1.1.0

将输入值重新解释为 Date 值 (假设采用小端字节序) ，即自 Unix 纪元 1970-01-01 起经过的天数

语法

reinterpretAsDate(x)

参数

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

返回值

日期。Date

示例

使用示例

Query

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

Response

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

​

reinterpretAsDateTime

引入版本：v1.1.0

将输入值重新解释为 DateTime 值 (按小端字节序) ，即自 Unix 纪元 1970-01-01 开始以来的天数

语法

reinterpretAsDateTime(x)

参数

• x — 自 Unix 纪元起经过的秒数。(U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

日期和时间。DateTime

示例

用法示例

Query

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

Response

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

​

reinterpretAsFixedString

引入版本：v1.1.0

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

语法

reinterpretAsFixedString(x)

参数

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

返回值

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

示例

使用示例

Query

-- The result is a sequence of bytes, so it is shown with `hex`.
SELECT
    hex(reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))),
    hex(reinterpretAsFixedString(toDate('1970-03-07')))

Response

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

​

reinterpretAsFloat32

Introduced in: v1.1.0

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

语法

reinterpretAsFloat32(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsFloat64

在以下版本中引入：v1.1.0

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

语法

reinterpretAsFloat64(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsInt128

首次引入于：v1.1.0

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

语法

reinterpretAsInt128(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsInt16

首次引入于：v1.1.0

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

语法

reinterpretAsInt16(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsInt256

引入版本：v1.1.0

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

语法

reinterpretAsInt256(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsInt32

引入版本：v1.1.0

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

语法

reinterpretAsInt32(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsInt64

引入版本：v1.1.0

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

语法

reinterpretAsInt64(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsInt8

引入版本：v1.1.0

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

语法

reinterpretAsInt8(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsString

引入版本：v1.1.0

将输入值重新解释为字符串。 对于标量值，字节顺序会归一化为小端字节序，且末尾的空字节会被忽略。例如，对于值为 255 的 UInt32，该函数会返回一个仅包含单个字符的字符串。 对于由固定大小元素组成的 Array，元素字节会按其原生内存顺序原样复制，不会裁剪末尾的零字节，也不会归一化为小端字节序，因此结果可以在任何架构上重新解释回原始 Array 类型。

语法

reinterpretAsString(x)

参数

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

返回值

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

示例

用法示例

Query

-- The result is a sequence of bytes, so it is shown with `hex`.
SELECT
    hex(reinterpretAsString(toDateTime('1970-01-01 01:01:05'))),
    hex(reinterpretAsString(toDate('1970-03-07')))

Response

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

Array 转 String 示例

Query

SELECT hex(reinterpretAsString([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8))) AS array_of_UInt8_to_string

Response

┌─array_of_UInt8_to_string─┐
│ 0102FF                   │
└──────────────────────────┘

​

reinterpretAsUInt128

首次引入于：v1.1.0

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

语法

reinterpretAsUInt128(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsUInt16

引入版本：v1.1.0

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

语法

reinterpretAsUInt16(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsUInt256

Introduced in: v1.1.0

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

Syntax

reinterpretAsUInt256(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsUInt32

首次引入版本：v1.1.0

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

语法

reinterpretAsUInt32(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsUInt64

首次引入版本：v1.1.0

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

语法

reinterpretAsUInt64(x)

参数

• x — 要重新解释为 UInt64 的值。Int* 或 UInt* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

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

示例

使用示例

Query

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

Response

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

​

reinterpretAsUInt8

Introduced in：v1.1.0

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

Syntax

reinterpretAsUInt8(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

reinterpretAsUUID

首次引入版本：v1.1.0

接受一个 16 字节字符串，并将其中每个 8 字节半段按 little-endian 字节序解释后返回一个 UUID。如果字符串长度不足，函数会像在末尾补足所需数量的空字节一样处理；如果字符串长度超过 16 字节，则会忽略末尾多出的字节。

语法

reinterpretAsUUID(fixed_string)

参数

• fixed_string — 大端字节串。FixedString

返回值

UUID 类型的值。UUID

示例

字符串转换为 UUID

Query

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

Response

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

​

toBFloat16

引入版本：v1.1.0

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

另请参见：

• toBFloat16OrZero。
• toBFloat16OrNull。

语法

toBFloat16(expr)

参数

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

返回值

返回一个 16 位 brain-float 类型的值。BFloat16

示例

使用示例

Query

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

Response

Row 1:
──────
toBFloat16(toFloat32(42.7)):   42.5
toBFloat16(toFloat32('42.7')): 42.5
toBFloat16('42.7'):            42.5

​

toBFloat16OrNull

引入于：v1.1.0

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

支持的参数：

• 数值的字符串表示形式。

不支持的参数 (返回 NULL) ：

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

该函数在从字符串表示形式转换时，允许静默丢失精度。

另请参见：

• toBFloat16.
• toBFloat16OrZero.

语法

toBFloat16OrNull(x)

参数

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

返回值

返回一个 16 位 brain-float 值；否则返回 NULL。BFloat16 或 NULL

示例

用法示例

Query

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

Response

\N	12.25	12.3125

​

toBFloat16OrZero

引入版本：v1.1.0

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

支持的参数：

• 数值的字符串表示形式。

不支持的参数 (返回 0) ：

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

该函数允许在从字符串表示形式转换时静默丢失精度。

另请参见：

• toBFloat16.
• toBFloat16OrNull.

语法

toBFloat16OrZero(x)

参数

• x — 数字的 String 表示形式。String

返回值

返回一个 16 位 brain-float 值；否则返回 0。BFloat16

示例

使用示例

Query

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

Response

0	12.25	12.3125

​

toBool

Introduced in：v22.2.0

将输入值转换为 Bool 类型。

语法

toBool(expr)

参数

• expr — 返回数值或字符串的表达式。对于字符串，可接受 ‘true’ 或 ‘false’ (不区分大小写) 。(U)Int* 或 Float* 或 String 或 Expression

返回值

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

示例

用法示例

Query

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

Response

Row 1:
──────
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.0

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

语法

toDate(x)

参数

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

返回值

返回转换后的输入值。Date

示例

将 String 转换为 Date

Query

SELECT toDate('2025-04-15')

Response

2025-04-15

将 DateTime 转换为 Date

Query

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

Response

2025-04-15

整数转换为日期

Query

SELECT toDate(20297)

Response

2025-07-28

​

toDate32

引入版本：v21.9.0

将参数转换为 Date32 数据类型。 如果值超出 [0000-01-01, 9999-12-31] 范围，toDate32 会返回 Date32 支持的边界值。 如果参数类型为 Date，则会考虑其取值边界。

语法

toDate32(expr)

参数

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

返回值

返回一个日历日期。Date32

示例

在取值范围内

Query

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

Response

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

1900 年以前

Query

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

Response

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

​

toDate32OrDefault

引入版本：v21.11.0

将参数转换为 Date32 数据类型。如果参数无法转换 (包括超出 Date32 范围的数值) ，该函数将返回默认值：如果指定了第二个参数，则返回该参数；否则返回 Date32 的历史默认值 1900-01-01 (而非其下界值 0000-01-01) 。如果参数的类型为 Date，则会考虑其边界。

请注意，与 toDate32 不同，该函数不会将超出范围的数值参数限制在 Date32 的边界值内；此类参数会被视为无法转换。

语法

toDate32OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

1930-01-01

转换失败

Query

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

Response

2020-01-01

超出范围的数值

Query

SELECT toDate32OrDefault(toUInt64(18446744073709551615), toDate32('2020-01-01'))

Response

2020-01-01

​

toDate32OrNull

引入版本：v21.9.0

将输入值转换为 Date32 类型的值；如果参数无效，则返回 NULL。 与 toDate32 相同，但在参数无效时会返回 NULL。

语法

toDate32OrNull(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

​

toDate32OrZero

引入版本：v21.9.0

将输入值转换为 Date32 类型的值；如果收到无效参数，则返回默认值 1900-01-01。 与 toDate32 相同，但如果收到无效参数，则返回 1900-01-01。 请注意，1900-01-01 是无效输入的历史默认值，并非 Date32 的下界值；其下界值为 0000-01-01。

另请参见：

• toDate32
• toDate32OrNull
• toDate32OrDefault

语法

toDate32OrZero(x)

参数

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

返回值

成功时返回 Date32 值，否则返回无效输入的历史默认值 (1900-01-01) 。Date32

示例

使用示例

Query

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

Response

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

​

toDateOrDefault

引入版本：v21.11.0

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

语法

toDateOrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toDateOrDefault('2022-12-30')

Response

2022-12-30

转换失败

Query

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

Response

2023-01-01

​

toDateOrNull

首次引入版本：v1.1.0

将输入值转换为 Date 类型的值；如果参数无效，则返回 NULL。 与 toDate 相同，但在参数无效时返回 NULL。 整数参数的解释方式与 toDate 相同 (如果不超过 65535，则表示自 1970-01-01 起的天数，否则表示 Unix 时间戳) ；如果超出 Date 类型的取值范围，则返回 NULL。

语法

toDateOrNull(x)

参数

• x — 日期的字符串表示形式，或以天数表示的整数，或 Unix 时间戳。String 或 (U)Int8/16/32/64

返回值

成功时返回 Date 值，否则返回 NULL。Date 或 NULL

示例

用法示例

Query

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

Response

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

​

toDateOrZero

引入版本：v1.1.0

将输入值转换为 Date 类型的值；如果传入的是无效参数，则返回 Date 的下界值。 与 toDate 相同，但如果传入的是无效参数，则返回 Date 的下界值。

另请参见：

• toDate
• toDateOrNull
• toDateOrDefault

语法

toDateOrZero(x)

参数

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

返回值

成功时返回 Date 值，否则返回 Date 的下界值 (1970-01-01) 。Date

示例

用法示例

Query

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

Response

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

​

toDateTime

引入版本：v1.1.0

将输入值转换为 DateTime 类型。

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

如果 expr 是 Time 或 Time64 值，则会将其解释为自 Unix 纪元开始以来的秒数：Time64 的小数部分会向负无穷方向取整，超出 DateTime 范围的值则遵循 date_time_overflow_behavior 设置。

语法

toDateTime(expr[, time_zone])

参数

• expr — 值。String 或 Int 或 Date 或 Date32 或 Time 或 Time64 或 DateTime 或 DateTime64
• time_zone — 时区。String

返回值

返回日期时间。DateTime

示例

使用示例

Query

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

Response

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.0

将输入值转换为 DateTime 类型。 支持从 String、FixedString、Date、Date32、Time、Time64、DateTime、DateTime64 或数值类型 ((U)Int8、(U)Int16、(U)Int32、(U)Int64、(U)Int128、(U)Int256、BFloat16、Float32、Float64) 转换。Decimal 值不受支持，会引发异常。 DateTime32 是 DateTime 的别名，支持 1970-01-01 00:00:00 至 2106-02-07 06:28:15 范围内的日期时间。 从字符串或上述可饱和的数值类型转换时，超出此范围的值会被饱和到范围边界。非有限浮点值 (NaN、inf、-inf) 无法转换，会引发异常。 从 Date32、DateTime64、Time 或 Time64 等其他日期时间类型转换时，遵循 date_time_overflow_behavior 设置：默认的 ignore 模式可能产生回绕值，saturate 会将值限制在范围边界内，而 throw 会引发异常。Time64 值会先向负无穷取整到整秒。

语法

toDateTime32(x[, timezone])

参数

• x — 要转换的输入值。String、FixedString、(U)Int*、Float*、BFloat16、Date、Date32、Time、Time64、DateTime 或 DateTime64
• timezone — 可选。返回的 DateTime 值所使用的时区。String

返回值

返回转换后的输入值。DateTime

示例

从字符串转换

Query

SELECT toDateTime32('2025-01-01 00:00:00') AS value, toTypeName(value);

Response

┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime          │
└─────────────────────┴───────────────────┘

从 Unix 时间戳转换

Query

SELECT toDateTime32(1735689600, 'UTC') AS value, toTypeName(value);

Response

┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime('UTC')   │
└─────────────────────┴───────────────────┘

指定时区

Query

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

Response

┌───────────────value─┬─toTypeName(value)─────────┐
│ 2025-01-01 00:00:00 │ DateTime('Asia/Istanbul') │
└─────────────────────┴───────────────────────────┘

​

toDateTime64

引入版本：v20.1.0

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

语法

toDateTime64(expr, scale[, timezone])

参数

• expr — 返回数值或数值字符串表示形式的表达式。Expression
• scale — 时间粒度 (精度) ：10^(-scale) 秒。UInt8
• timezone — 可选。指定 DateTime64 对象的时区。String

返回值

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

示例

值在范围内

Query

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

Response

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

作为指定精度的 Decimal

Query

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);

Response

┌───────────────────value─┬─toTypeName(value)─┐
│ 2019-01-01 00:00:00.000 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘
┌───────────────────value─┬─toTypeName(value)─┐
│ 9999-12-31 23:59:59.999 │ DateTime64(3)     │
└─────────────────────────┴───────────────────┘

指定时区

Query

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

Response

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

​

toDateTime64OrDefault

引入版本：v21.11.0

与 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

示例

成功转换

Query

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

Response

1976-10-18 00:00:00.300

转换失败

Query

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

Response

2001-01-01 00:00:00.000

​

toDateTime64OrNull

引入版本：v20.1.0

将输入值转换为 DateTime64 类型的值；如果接收到无效参数，则返回 NULL。 与 toDateTime64 相同，但如果接收到无效参数，则返回 NULL。 整数参数会被解释为以整秒表示的 Unix 时间戳；如果超出 DateTime64 类型的取值范围，则返回 NULL。

语法

toDateTime64OrNull(x[, precision[, timezone]])

参数

• x — 带有子秒级精度的日期时间字符串表示形式，或整数 Unix 时间戳。String 或 (U)Int8/16/32/64
• precision — 可选。返回值的子秒级精度。UInt8
• timezone — 可选。返回值的时区。String

返回值

如果成功，则返回 DateTime64 值；否则返回 NULL。DateTime64 或 NULL

示例

用法示例

Query

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

Response

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

​

toDateTime64OrZero

引入版本：v20.1.0

将输入值转换为 DateTime64 类型的值；如果接收到无效参数，则返回零 DateTime64 值 (Unix 纪元，1970-01-01 00:00:00) 。 与 toDateTime64 相同，但在接收到无效参数时会返回零 DateTime64 值。

另请参见：

• toDateTime64。
• toDateTime64OrNull。
• toDateTime64OrDefault。

语法

toDateTime64OrZero(x[, precision[, timezone]])

参数

• x — 带有子秒级精度的日期时间字符串表示形式。String
• precision — 可选。返回值的子秒级精度。UInt8
• timezone — 可选。返回值的时区。String

返回值

成功时返回 DateTime64 值，否则返回请求精度下的零 DateTime64 值 (1970-01-01 00:00:00) 。DateTime64

示例

使用示例

Query

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

Response

┌─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.0

与 toDateTime 类似，但如果转换失败，则返回默认值：若指定了第三个参数，则返回该参数；否则返回 DateTime 的下界值。

语法

toDateTimeOrDefault(expr[, timezone, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

2022-12-30 13:44:17

转换失败

Query

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

Response

2023-01-01 00:00:00

​

toDateTimeOrNull

引入版本：v1.1.0

将输入值转换为 DateTime 类型的值；如果接收到无效参数，则返回 NULL。 与 toDateTime 相同，但在接收到无效参数时会返回 NULL。 整数参数会被解释为 Unix 时间戳；如果超出 DateTime 类型的取值范围，则返回 NULL。

语法

toDateTimeOrNull(x[, timezone])

参数

• x — 日期时间的字符串表示形式，或整数 Unix 时间戳。String 或 (U)Int8/16/32/64
• timezone — 可选。返回值的时区。String

返回值

成功时返回 DateTime 值，否则返回 NULL。DateTime 或 NULL

示例

用法示例

Query

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

Response

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

带有时区的整数参数

Query

SELECT toDateTimeOrNull(1583851242, 'Asia/Shanghai'), toDateTimeOrNull(4294967296)

Response

┌─toDateTimeOrNull(1583851242, 'Asia/Shanghai')─┬─toDateTimeOrNull(4294967296)─┐
│                           2020-03-10 22:40:42 │                         ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴──────────────────────────────┘

​

toDateTimeOrZero

引入版本：v1.1.0

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

语法

toDateTimeOrZero(x)

参数

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

返回值

如果成功，则返回 DateTime 值；否则返回 DateTime 的下界值 (1970-01-01 00:00:00) 。DateTime

示例

使用示例

Query

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

Response

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

​

toDecimal128

引入版本：v18.12.0

将输入值转换为标度为 S 的 Decimal(38, S) 类型值。 出错时会抛出异常。

支持的参数：

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

不支持的参数：

• Float* 类型的 NaN 和 Inf 值，及其字符串表示形式 (不区分大小写) 。
• 二进制和十六进制值的字符串表示形式，例如 SELECT toDecimal128('0xc0fe', 1);。

如果 expr 的值超出 Decimal128 的范围：(-1*10^(38 - S), 1*10^(38 - S))，则可能发生溢出。 小数部分中过多的位数会被截掉 (不进行舍入) 。 整数部分中过多的位数会导致异常。

转换会截掉多余的位数；处理 Float32/Float64 输入时，由于运算使用的是浮点指令，结果可能不符合预期。 例如：toDecimal128(1.15, 2) 的结果是 1.14，因为在浮点运算中，1.15 * 100 的结果是 114.99。 你可以使用 String 输入，这样运算会使用底层整数类型：toDecimal128('1.15', 2) = 1.15

语法

toDecimal128(expr, S)

参数

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

返回值

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

示例

用法示例

Query

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

Response

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

Introduced in: v21.11.0

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

语法

toDecimal128OrDefault(expr, S[, default])

参数

• expr — 数字的 String 字符串表示形式。String
• S — 介于 0 到 38 之间的 scale 参数，用于指定数字的小数部分可包含的位数。UInt8
• default — 可选。如果解析为 Decimal128(S) 类型失败，则返回此默认值。Decimal128(S)

返回值

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

示例

转换成功

Query

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

Response

0.023809523809523808

转换失败

Query

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

Response

-1

​

toDecimal128OrNull

引入版本：v20.1.0

将输入值转换为 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

示例

使用示例

Query

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

Response

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

​

toDecimal128OrZero

引入版本：v20.1.0

将输入值转换为 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)

示例

基本用法

Query

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

Response

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

​

toDecimal256

引入版本：v20.8.0

将输入值转换为带有 S 标度的 Decimal(76, S) 类型的值。出错时会抛出异常。

支持的参数：

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

不支持的参数：

• Float* 值 NaN 和 Inf 及其字符串表示形式 (不区分大小写) 。
• 二进制和十六进制值的字符串表示形式，例如 SELECT toDecimal256('0xc0fe', 1);。

如果 expr 的值超出 Decimal256 的取值范围：(-1*10^(76 - S), 1*10^(76 - S))，则可能发生溢出。 小数部分中过多的数字会被截去 (不进行舍入) 。 整数部分位数过多将导致异常。

转换会截去多余的数字；在处理 Float32/Float64 输入时，由于运算使用浮点指令执行，结果可能不符合预期。 例如：toDecimal256(1.15, 2) 的结果为 1.14，因为在浮点运算中，1.15 * 100 的结果是 114.99。 你可以使用 String 类型的输入，这样运算会使用底层整数类型：toDecimal256('1.15', 2) = 1.15

语法

toDecimal256(expr, S)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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.0

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

语法

toDecimal256OrDefault(expr, S[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

0.023809523809523808

转换失败

Query

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

Response

-1

​

toDecimal256OrNull

引入版本：v20.8.0

将输入值转换为 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

示例

使用示例

Query

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

Response

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

​

toDecimal256OrZero

引入版本：v20.8.0

将输入值转换为 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)

示例

用法示例

Query

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

Response

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

​

toDecimal32

引入版本：v18.12.0

将输入值转换为 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 的 scale 参数，用于指定数值的小数部分可以有多少位。UInt8

返回值

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

示例

使用示例

Query

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

Response

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

Introduced in：v21.11.0

与 toDecimal32 类似，此函数会将输入值转换为 Decimal(9, S) 类型的值，但如果发生错误，则返回默认值。

语法

toDecimal32OrDefault(expr, S[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toDecimal32OrDefault(toString(0.0001), 5)

Response

0.0001

转换失败

Query

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

Response

-1

​

toDecimal32OrNull

引入版本：v20.1.0

将输入值转换为 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 之间的 scale 参数，指定数值的小数部分可包含的位数。UInt8

返回值

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

示例

用法示例

Query

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

Response

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

​

toDecimal32OrZero

引入版本：v20.1.0

将输入值转换为 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)

示例

用法示例

Query

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

Response

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

​

toDecimal64

引入版本：v18.12.0

将输入值转换为标度为 S 的 Decimal(18, 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 之间的 scale 参数，用于指定数值的小数部分可以有多少位。UInt8

返回值

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

示例

使用示例

Query

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

Response

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

​

toDecimal64OrDefault

首次引入版本：v21.11.0

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

语法

toDecimal64OrDefault(expr, S[, default])

参数

• expr — 数字的 String 字符串表示形式。String
• S — 介于 0 到 18 之间的 scale 参数，用于指定数字的小数部分最多可有多少位。UInt8
• default — 可选。如果无法解析为 Decimal64(S) 类型，则返回此默认值。Decimal64(S)

返回值

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

示例

成功转换

Query

SELECT toDecimal64OrDefault(toString(0.0001), 18)

Response

0.0001

转换失败

Query

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

Response

-1

​

toDecimal64OrNull

引入版本：v20.1.0

将输入值转换为 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 之间的 scale 参数，用于指定数值的小数部分可包含的位数。UInt8

返回值

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

示例

使用示例

Query

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

Response

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

​

toDecimal64OrZero

引入版本：v20.1.0

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

支持的参数：

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

不支持的参数 (返回 0) ：

• Float* 类型的 NaN 和 Inf 值，或其字符串表示形式 (不区分大小写) 。
• 二进制和十六进制值的字符串表示形式。

如果输入值超出 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)

示例

使用示例

Query

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

Response

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

​

toDecimalString

引入版本：v23.3.0

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

该函数会将输入值四舍五入到指定的小数位数。如果输入值的小数位数少于指定值， 则结果会用 0 补齐，以达到指定的确切小数位数。

语法

toDecimalString(number, scale)

参数

• number — 要转换为字符串的数值。可以是任意数值类型 (Int、UInt、Float、Decimal) 。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64 或 Decimal
• scale — 小数部分显示的位数。必要时会对结果进行四舍五入。UInt8

返回值

返回该数值的 String 表示形式，并且小数位数严格等于指定的位数。String

示例

对数值进行四舍五入并格式化

Query

SELECT toDecimalString(2.1456, 2)

Response

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

用零补齐

Query

SELECT toDecimalString(5, 3)

Response

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

不同数值类型

Query

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

Response

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

​

toFixedString

引入版本：v1.1.0

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

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

语法

toFixedString(s, N)

参数

• s — 要转换的 String。String
• N — 生成的 FixedString 的长度。const UInt*

返回值

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

示例

使用示例

Query

-- The padding is made of null bytes, so the result is shown with `hex`.
SELECT hex(toFixedString('foo', 8)) AS s;

Response

┌─s────────────────┐
│ 666F6F0000000000 │
└──────────────────┘

​

toFloat32

引入版本：v1.1.0

将输入值转换为 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

示例

使用示例

Query

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

Response

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

​

toFloat32OrDefault

引入版本：v21.11.0

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

语法

toFloat32OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

8

转换失败

Query

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

Response

0

​

toFloat32OrNull

引入版本：v1.1.0

将输入值转换为 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 位 Float 值，否则返回 NULL。Float32 或 NULL

示例

使用示例

Query

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

Response

Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'):  nan
toFloat32OrNull('abc'):  ᴺᵁᴸᴸ

​

toFloat32OrZero

首次引入版本：v1.1.0

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

另请参见：

• toFloat32。
• toFloat32OrNull。
• toFloat32OrDefault。

语法

toFloat32OrZero(x)

参数

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

返回值

成功时返回 32 位 Float 值，否则返回 0。Float32

示例

用法示例

Query

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

Response

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

​

toFloat64

引入版本：v1.1.0

将输入值转换为 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

示例

用法示例

Query

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

Response

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

​

toFloat64OrDefault

引入版本：v21.11.0

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

语法

toFloat64OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

8

转换失败

Query

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

Response

0

​

toFloat64OrNull

引入版本：v1.1.0

将输入值转换为 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 位 Float 值，否则返回 NULL。 Float64 或 NULL

示例

使用示例

Query

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

Response

Row 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'):  nan
toFloat64OrNull('abc'):  ᴺᵁᴸᴸ

​

toFloat64OrZero

引入于：v1.1.0

将输入值转换为 Float64 类型的值；如果发生错误，则返回 0。 与 toFloat64 类似，但在转换错误时会返回 0，而不是抛出异常。

另请参见：

• toFloat64。
• toFloat64OrNull。
• toFloat64OrDefault。

语法

toFloat64OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

第 1 行：
──────
toFloat64OrZero('42.7'): 42.7
toFloat64OrZero('abc'):  0

​

toInt128

首次引入于：v1.1.0

将输入值转换为 Int128 类型的值。 出错时会抛出异常。 该函数采用向零舍入，也就是说会截断数字的小数位。

支持的参数：

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

不支持的参数：

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

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

另请参见：

• toInt128OrZero。
• toInt128OrNull。
• toInt128OrDefault。

语法

toInt128(expr)

参数

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

返回值

返回一个 128 位整数值。Int128

示例

用法示例

Query

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

Response

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

​

toInt128OrDefault

引入版本：v21.11.0

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

语法

toInt128OrDefault(expr[, default])

参数

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

返回值

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

示例

成功转换

Query

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

Response

-128

转换失败

Query

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

Response

-1

​

toInt128OrNull

Introduced in: v20.8.0

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

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

如果输入值超出 Int128 的可表示范围，结果会发生上溢或下溢。 这不视为错误。

See also:

• toInt128。
• toInt128OrZero。
• toInt128OrDefault。

语法

toInt128OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

Row 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'):  ᴺᵁᴸᴸ

​

toInt128OrZero

引入版本：v20.8.0

将输入值转换为 Int128 类型，但如果发生错误则返回 0。 与 toInt128 类似，但返回 0 而不是抛出异常。

另请参见：

• toInt128。
• toInt128OrNull。
• toInt128OrDefault。

语法

toInt128OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

SELECT toInt128OrZero('123')

Response

123

转换失败时返回 0

Query

SELECT toInt128OrZero('abc')

Response

0

​

toInt16

引入于：v1.1.0

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

支持的参数：

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

不支持的参数：

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

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

该函数采用向零舍入，也就是说会截去数字的小数位。

另请参阅：

• toInt16OrZero。
• toInt16OrNull。
• toInt16OrDefault。

语法

toInt16(expr)

参数

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

返回值

返回一个 16 位整数值。Int16

示例

用法示例

Query

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

Response

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

​

toInt16OrDefault

引入版本：v21.11.0

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

语法

toInt16OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

-16

转换失败

Query

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

Response

-1

​

toInt16OrNull

引入版本：v1.1.0

与 toInt16 类似，此函数将输入值转换为 Int16 类型的值，但如果发生错误，则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参见：

• toInt16。
• toInt16OrZero。
• toInt16OrDefault。

语法

toInt16OrNull(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

Row 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): ᴺᵁᴸᴸ

​

toInt16OrZero

引入版本：v1.1.0

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

支持的参数：

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

不支持的参数 (返回 0) ：

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

如果输入值超出 Int16 的表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参见：

• toInt16。
• toInt16OrNull。
• toInt16OrDefault。

语法

toInt16OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

toInt256

引入版本：v1.1.0

将输入值转换为 Int256 类型的值。 如果发生错误，会抛出异常。 该函数采用向零舍入，也就是说会截去数字的小数位。

支持的参数：

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

不支持的参数：

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

如果输入值超出 Int256 的表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参见：

• toInt256OrZero。
• toInt256OrNull。
• toInt256OrDefault。

语法

toInt256(expr)

参数

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

返回值

返回一个 256 位整数值。Int256

示例

使用示例

Query

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

Response

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

​

toInt256OrDefault

引入版本：v21.11.0

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

语法

toInt256OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

-256

转换失败

Query

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

Response

-1

​

toInt256OrNull

引入版本：v20.8.0

与 toInt256 类似，此函数会将输入值转换为 Int256 类型的值，但如果发生错误，则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL)：

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

如果输入值超出了 Int256 的表示范围，则结果会发生上溢或下溢。 这不视为错误。

另请参阅：

• toInt256。
• toInt256OrZero。
• toInt256OrDefault。

语法

toInt256OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

Row 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'):  ᴺᵁᴸᴸ

​

toInt256OrZero

引入版本：v20.8.0

将输入值转换为 Int256 类型；如果发生错误，则返回 0。 与 toInt256 类似，但会返回 0，而不是抛出异常。

另请参见：

• toInt256。
• toInt256OrNull。
• toInt256OrDefault。

语法

toInt256OrZero(x)

参数

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

返回值

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

示例

用法示例

Query

SELECT toInt256OrZero('123')

Response

123

转换失败时返回 0

Query

SELECT toInt256OrZero('abc')

Response

0

​

toInt32

Introduced in: v1.1.0

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

支持的参数：

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

不支持的参数：

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

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

该函数采用向零舍入，即截去数字的小数位。

See also:

• toInt32OrZero。
• toInt32OrNull。
• toInt32OrDefault。

Syntax

toInt32(expr)

参数

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

返回值

返回一个 32 位整数。Int32

示例

用法示例

Query

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

Response

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

​

toInt32OrDefault

引入版本：v21.11.0

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

语法

toInt32OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

-32

转换失败

Query

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

Response

-1

​

toInt32OrNull

引入版本：v1.1.0

与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值，但如果发生错误则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL)：

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

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

另请参阅：

• toInt32。
• toInt32OrZero。
• toInt32OrDefault。

语法

toInt32OrNull(x)

参数

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

返回值

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

示例

用法示例

Query

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

Response

Row 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): ᴺᵁᴸᴸ

​

toInt32OrZero

引入版本：v1.1.0

与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值；如果发生错误，则返回 0。

支持的参数：

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

不支持的参数 (返回 0)：

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

如果输入值超出 Int32 的表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参阅：

• toInt32。
• toInt32OrNull。
• toInt32OrDefault。

语法

toInt32OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

toInt64

引入版本：v1.1.0

将输入值转换为 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) ，以及二进制和十六进制值的字符串表示形式。表达式

返回值

返回一个 64 位整数值。Int64

示例

使用示例

Query

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

Response

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

​

toInt64OrDefault

引入版本：v21.11.0

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

语法

toInt64OrDefault(expr[, default])

参数

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

返回值

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

示例

成功转换

Query

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

Response

-64

转换失败

Query

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

Response

-1

​

toInt64OrNull

引入版本：v1.1.0

与 toInt64 类似，此函数将输入值转换为 Int64 类型的值，但如果发生错误，则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

如果输入值超出 Int64 的表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参见：

• toInt64。
• toInt64OrZero。
• toInt64OrDefault。

语法

toInt64OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): ᴺᵁᴸᴸ

​

toInt64OrZero

引入版本：v1.1.0

将输入值转换为 Int64 类型，但如果发生错误则返回 0。 与 toInt64 类似，不过它会返回 0，而不是抛出异常。

另请参见：

• toInt64。
• toInt64OrNull。
• toInt64OrDefault。

语法

toInt64OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

SELECT toInt64OrZero('123')

Response

123

转换失败则返回零

Query

SELECT toInt64OrZero('abc')

Response

0

​

toInt8

引入版本：v1.1.0

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

支持的参数：

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

不支持的参数：

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

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

此函数使用向零舍入，即会截去数字的小数位。

另请参见：

• toInt8OrZero。
• toInt8OrNull。
• toInt8OrDefault。

语法

toInt8(expr)

参数

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

返回值

返回一个 8 位整数值。Int8

示例

使用示例

Query

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

Response

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

​

toInt8OrDefault

首次引入版本：v21.11.0

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

语法

toInt8OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

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

Response

-8

转换失败

Query

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

Response

-1

​

toInt8OrNull

引入版本：v1.1.0

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

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参阅：

• toInt8。
• toInt8OrZero。
• toInt8OrDefault。

语法

toInt8OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): ᴺᵁᴸᴸ

​

toInt8OrZero

版本引入：v1.1.0

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

支持的参数：

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

不支持的参数 (返回 0)：

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

如果输入值超出 Int8 的表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参见：

• toInt8。
• toInt8OrNull。
• toInt8OrDefault。

语法

toInt8OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

toInterval

引入版本：v25.4.0

根据数值和单位字符串创建一个 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 值。结果类型取决于 unit：IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter 或 IntervalYear。Interval

示例

创建不同单位的时间间隔

Query

SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months

Response

┌─seconds─┬─days─┬─months─┐
│       5 │    3 │      2 │
└─────────┴──────┴────────┘

在日期算术中使用时间间隔

Query

SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago

Response

┌─────────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 │
└──────────────────────┴─────────────────────┴─────────────────────┘

动态生成时间间隔

Query

SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)

Response

┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘

​

toIntervalDay

在 v1.1.0 中引入

返回一个由 n 天组成、数据类型为 IntervalDay 的时间间隔。

语法

toIntervalDay(n)

参数

• n — 天数。整数、整数的字符串表示形式或浮点数。(U)Int* 或 Float* 或 String

返回值

返回 n 天的时间间隔。Interval

示例

使用示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result

Response

┌─────result─┐
│ 2025-06-20 │
└────────────┘

​

toIntervalHour

在 v1.1.0 中引入

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

语法

toIntervalHour(n)

参数

• n — 小时数。可以是整数、其字符串表示形式或浮点数。Int* 或 UInt* 或 Float* 或 String

返回值

返回一个 n 小时的时间间隔。Interval

示例

用法示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result

Response

┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘

​

toIntervalMicrosecond

引入版本：v22.6.0

返回一个由 n 微秒组成的时间间隔，数据类型为 IntervalMicrosecond。

语法

toIntervalMicrosecond(n)

参数

• n — 微秒数。(U)Int* 或 Float* 或 String

返回值

返回由 n 微秒构成的时间间隔。Interval

示例

使用示例

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result

Response

┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘

​

toIntervalMillisecond

引入版本：v22.6.0

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

语法

toIntervalMillisecond(n)

参数

• n — 毫秒数。(U)Int* 或 Float* 或 String

返回值

返回一个包含 n 毫秒的时间间隔。Interval

示例

使用示例

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result

Response

┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘

​

toIntervalMinute

引入版本：v1.1.0

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

语法

toIntervalMinute(n)

参数

• n — 分钟数。整数、其字符串表示形式以及浮点数。(U)Int* 或 Float* 或 String

返回值

返回 n 分钟的时间间隔。Interval

示例

用法示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘

​

toIntervalMonth

引入版本：v1.1.0

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

语法

toIntervalMonth(n)

参数

• n — 月份数。(U)Int* 或 Float* 或 String

返回值

返回 n 个月的时间间隔。Interval

示例

使用示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result

Response

┌─────result─┐
│ 2025-07-15 │
└────────────┘

​

toIntervalNanosecond

引入版本：v22.6.0

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

语法

toIntervalNanosecond(n)

参数

• n — 纳秒数量。(U)Int* 或 Float* 或 String

返回值

返回 n 纳秒的时间间隔。Interval

示例

使用示例

Query

WITH
    toDateTime('2025-06-15') AS date,
    toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result

Response

┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘

​

toIntervalQuarter

在 v1.1.0 中引入

返回一个由 n 个季度组成、数据类型为 IntervalQuarter 的时间间隔。

语法

toIntervalQuarter(n)

参数

• n — 季度数量。(U)Int* 或 Float* 或 String

返回值

返回 n 个季度的时间间隔。Interval

示例

使用示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result

Response

┌─────result─┐
│ 2025-09-15 │
└────────────┘

​

toIntervalSecond

引入版本：v1.1.0

返回一个由 n 秒构成、数据类型为 IntervalSecond 的时间间隔。

语法

toIntervalSecond(n)

参数

• n — 秒数。整数、其字符串表示形式以及浮点数。(U)Int* 或 Float* 或 String

返回值

返回 n 秒的时间间隔。Interval

示例

使用示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result

Response

┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘

​

toIntervalWeek

引入版本：v1.1.0

返回一个表示 n 周的时间间隔，数据类型为 IntervalWeek。

语法

toIntervalWeek(n)

参数

• n — 周数。(U)Int* 或 Float* 或 String

返回值

返回 n 周的时间间隔。Interval

示例

用法示例

Query

WITH
    toDate('2025-06-15') AS date,
    toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result

Response

┌─────result─┐
│ 2025-06-22 │
└────────────┘

​

toIntervalYear

引入版本：v1.1.0

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

语法

toIntervalYear(n)

参数

• n — 年数。(U)Int* 或 Float* 或 String

返回值

返回一个 n 年的时间间隔。Interval

示例

使用示例

Query

WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result

Response

┌─────result─┐
│ 2025-06-15 │
└────────────┘

​

toLowCardinality

引入版本：v18.12.0

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

若要将 LowCardinality 数据类型转换为常规数据类型，请使用 CAST 函数。 例如：CAST(x AS String)。

语法

toLowCardinality(expr)

参数

• expr — 结果为以下任一受支持数据类型的表达式。String 或 FixedString 或 Date 或 DateTime 或 (U)Int* 或 Float*

返回值

返回转换为 LowCardinality 数据类型后的输入值。LowCardinality

示例

使用示例

Query

SELECT toLowCardinality('1')

Response

┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘

​

toString

引入版本：v1.1.0

将值转换为其字符串表示形式。 对于 DateTime 类型的参数，该函数还可以接受第二个 String 类型参数，用于指定时区名称。

语法

toString(value[, timezone])

参数

• value — 要转换为字符串的值。Any
• timezone — 可选。用于 DateTime 转换的时区名称。String

返回值

返回输入值的字符串表示形式。String

示例

使用示例

Query

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

Response

┌──────────────────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.0

接受一个 String 或 FixedString 类型的参数，并返回一个 String，该 String 是在第一个空字节处截断后的原始字符串副本。

空字节 (\0) 被视为字符串终止符。 当空字节用于标记有效内容的结尾时，此函数可用于处理 C 风格字符串或二进制数据。

语法

toStringCutToZero(s)

参数

• s — 要处理的 String 或 FixedString。String 或 FixedString

返回值

返回一个 String，包含第一个空字节之前的字符。String

示例

使用示例

Query

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

Response

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

​

toTime

引入版本：v25.5.0

将输入值转换为 Time 类型。 支持从 String、FixedString、DateTime、DateTime64、Time64 或表示自午夜起经过秒数的数值类型进行转换。 超出该类型范围的数值 (-999:59:59 至 999:59:59，即 -3599999 至 3599999 秒) 将被限制在范围边界内；非有限浮点值 (NaN、inf、-inf) 无法转换，并会引发异常。 Time64 值会向负无穷方向取整到整秒，并同样被限制在该范围内。

在 v25.5 之前，toTime 是另一个函数，用于将日期时间转换为固定日期 (1970-01-02) ，同时保留 时间部分。该函数仍以 toTimeWithFixedDate 的名称提供。

将 use_legacy_to_time 设置为 1，也会使 toTime 名称仍绑定到旧版 函数；即对 toTime 的调用会解析为 toTimeWithFixedDate，而非此处所述的转换函数。 启用该设置时，请使用 CAST(x AS Time) 或 x::Time 转换为 Time 类型。 自 v26.7 起，该设置默认值为 0，但在 v25.6 至 v26.6 期间默认值为 1，因此以下示例会显式设置该值。

语法

toTime(x)

参数

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

返回值

返回转换后的值。Time

示例

DateTime64 转换为 Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime64('2025-04-15 14:30:25.123', 3))

Response

14:30:25

DateTime 转换为 Time

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime('2025-04-15 14:30:25'))

Response

14:30:25

将整数 (表示自纪元以来的秒数) 转换为时间

Query

SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime(52225, 'UTC'))

Response

14:30:25

​

toTime64

引入版本：v25.6.0

将输入值转换为 Time64 类型。 支持从 String、FixedString、DateTime64，或表示自午夜起经过秒数的数值类型进行转换。 可为时间值提供子秒级精度，最多支持 scale 位小数。

语法

toTime64(x, scale)

参数

• x — 要转换的输入值。String 或 FixedString 或 DateTime64 或 (U)Int* 或 Float*
• scale — 结果 Time64 的精度 (小数位数，0–9) 。(U)Int*

返回值

返回按请求的 scale 转换后的值。Time64

示例

将 String 转换为 Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64('14:30:25.123456', 6)

Response

14:30:25.123456

DateTime64 转换为 Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6), 6)

Response

14:30:25.123456

Float (自午夜起的秒数) 转换为 Time64

Query

SET enable_time_time64_type = 1;
SELECT toTime64(52225.123456, 6)

Response

14:30:25.123456

​

toTime64OrNull

引入版本：v25.6.0

将输入值转换为 Time64 类型的值；如果发生错误，则返回 NULL。 与 toTime64 类似，但在转换出错时会返回 NULL，而不是抛出异常。

另请参见：

• toTime64
• toTime64OrZero

语法

toTime64OrNull(x[, precision])

参数

• x — 具有子秒级精度的时间字符串表示形式。String
• precision — 可选。返回值的子秒级精度。UInt8

返回值

成功时返回 Time64 值，否则返回 NULL。Time64 或 NULL

示例

用法示例

Query

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

Response

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

​

toTime64OrZero

引入版本：v25.6.0

将输入值转换为 Time64 类型的值；如果参数无效，则返回零 Time64 值 (00:00:00) 。 与 toTime64 相同，但如果参数无效，则返回零 Time64 值。

另请参阅：

• toTime64。
• toTime64OrNull。

语法

toTime64OrZero(x[, precision])

参数

• x — 具有子秒级精度的时间字符串表示形式。String
• precision — 可选。返回值的子秒级精度。UInt8

返回值

如果成功，返回 Time64 值；否则返回指定精度下的零值 Time64 (00:00:00) 。Time64

示例

用法示例

Query

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

Response

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │              00:00:00.000 │
└────────────────────────────────┴───────────────────────────┘

​

toTimeOrNull

引入版本：v25.5.0

将输入值转换为 Time 类型的值；如果发生错误，则返回 NULL。 与 toTime 类似，但在转换出错时会返回 NULL，而不是抛出异常。

另请参见：

• toTime
• toTimeOrZero

语法

toTimeOrNull(x)

参数

• x — 时间的字符串表示形式。String

返回值

成功时返回 Time 值，否则返回 NULL。Time 或 NULL

示例

使用示例

Query

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

Response

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

​

toTimeOrZero

Introduced in: v25.5.0

将输入值转换为 Time 类型的值；如果出错，则返回 00:00:00。 与 toTime 类似，但在转换出错时会返回 00:00:00，而不是抛出异常。

Syntax

toTimeOrZero(x)

参数

• x — 时间的字符串表示形式。String

返回值

如果成功，返回 Time 值；否则返回 00:00:00。Time

示例

使用示例

Query

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

Response

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

​

toUInt128

引入版本：v1.1.0

将输入值转换为 UInt128 类型的值。 出错时会抛出异常。 该函数采用向零舍入，即会截断数字的小数位。

支持的参数：

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

不支持的参数：

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

如果输入值超出 UInt128 的表示范围，结果会发生上溢或下溢。 这不被视为错误。

另请参见：

• toUInt128OrZero。
• toUInt128OrNull。
• toUInt128OrDefault。

语法

toUInt128(expr)

参数

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

返回值

返回一个 128 位无符号整数值。UInt128

示例

用法示例

Query

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Response

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

​

toUInt128OrDefault

引入版本：v21.11.0

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

语法

toUInt128OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

Response

128

转换失败

Query

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

Response

0

​

toUInt128OrNull

引入版本：v21.6.0

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

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参阅：

• toUInt128。
• toUInt128OrZero。
• toUInt128OrDefault。

语法

toUInt128OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt128OrZero

引入版本：v1.1.0

与 toUInt128 类似，此函数会将输入值转换为 UInt128 类型的值，但如果发生错误则返回 0。

支持的参数：

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

不支持的参数 (返回 0)：

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

如果输入值超出 UInt128 的表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参见：

• toUInt128。
• toUInt128OrNull。
• toUInt128OrDefault。

语法

toUInt128OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

​

toUInt16

引入版本：v1.1.0

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

支持的参数：

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

不支持的参数：

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

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

该函数采用向零舍入，即会截断数字的小数位。

另请参见：

• toUInt16OrZero。
• toUInt16OrNull。
• toUInt16OrDefault。

语法

toUInt16(expr)

参数

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

返回值

返回一个 16 位无符号整数值。UInt16

示例

使用示例

Query

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Response

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

​

toUInt16OrDefault

Introduced in：v21.11.0

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

Syntax

toUInt16OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

Response

16

转换失败

Query

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

Response

0

​

toUInt16OrNull

Introduced in: v1.1.0

与 toUInt16 类似，此函数会将输入值转换为 UInt16 类型的值，但如果发生错误则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

See also:

• toUInt16。
• toUInt16OrZero。
• toUInt16OrDefault。

Syntax

toUInt16OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt16OrZero

引入于：v1.1.0

与 toUInt16 类似，此函数将输入值转换为 UInt16 类型的值，但在发生错误时会返回 0。

支持的参数：

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

不支持的参数 (返回 0) ：

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

如果输入值超出了 UInt16 的可表示范围，则结果会发生上溢或下溢。 这不视为错误。

另请参阅：

• toUInt16。
• toUInt16OrNull。
• toUInt16OrDefault。

语法

toUInt16OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

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

Response

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

​

toUInt256

在 v1.1.0 中引入

将输入值转换为 UInt256 类型的值。 出错时会抛出异常。 该函数采用向零舍入，也就是说会截断数字的小数位。

支持的参数：

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

不支持的参数：

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

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

另请参见：

• toUInt256OrZero。
• toUInt256OrNull。
• toUInt256OrDefault。

语法

toUInt256(expr)

参数

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

返回值

返回一个 256 位无符号整数。UInt256

示例

使用示例

Query

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Response

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

​

toUInt256OrDefault

引入版本：v21.11.0

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

语法

toUInt256OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

Response

0

转换失败

Query

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

Response

0

​

toUInt256OrNull

引入版本：v20.8.0

与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参阅：

• toUInt256。
• toUInt256OrZero。
• toUInt256OrDefault。

语法

toUInt256OrNull(x)

参数

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

返回值

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

示例

使用示例

Query

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt256OrZero

引入于：v20.8.0

与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回 0。

支持的参数：

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

不支持的参数 (返回 0) ：

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

如果输入值超出 UInt256 的可表示范围，结果会发生上溢或下溢。 这不视为错误。

另请参见：

• toUInt256。
• toUInt256OrNull。
• toUInt256OrDefault。

语法

toUInt256OrZero(x)

参数

• x — 字符串表示形式。String

返回值

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

示例

使用示例

Query

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

​

toUInt32

引入于：v1.1.0

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

支持的参数：

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

不支持的参数：

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

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

该函数使用向零舍入，即会截去数字的小数位。

另请参见：

• toUInt32OrZero。
• toUInt32OrNull。
• toUInt32OrDefault。

语法

toUInt32(expr)

参数

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

返回值

返回一个 32 位无符号整数。UInt32

示例

用法示例

Query

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Response

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

​

toUInt32OrDefault

Introduced in: v21.11.0

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

Syntax

toUInt32OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

Response

32

转换失败

Query

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

Response

0

​

toUInt32OrNull

引入于：v1.1.0

与 toUInt32 类似，此函数会将输入值转换为 UInt32 类型的值，但如果发生错误，则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参见：

• toUInt32。
• toUInt32OrZero。
• toUInt32OrDefault。

语法

toUInt32OrNull(x)

参数

• x — 字符串表示形式。String

返回值

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

示例

使用示例

Query

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

Response

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt32OrZero

引入版本：v1.1.0

与 toUInt32 类似，此函数将输入值转换为 UInt32 类型的值，但如果发生错误，则返回 0。

支持的参数：

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

不支持的参数 (返回 0) ：

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

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

另请参见：

• toUInt32。
• toUInt32OrNull。
• toUInt32OrDefault。

语法

toUInt32OrZero(x)

参数

• x — 字符串表示形式。String

返回值

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

示例

使用示例

Query

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

Response

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

​

toUInt64

引入版本：v1.1.0

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

支持的参数：

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

不支持的类型：

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

如果输入值超出 UInt64 的取值范围，结果会发生上溢或下溢。 这不视为错误。 例如：SELECT toUInt64(18446744073709551616) == 0;

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

另请参见：

• toUInt64OrZero。
• toUInt64OrNull。
• toUInt64OrDefault。

语法

toUInt64(expr)

参数

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

返回值

返回一个 64 位无符号整数值。UInt64

示例

使用示例

Query

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Response

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

​

toUInt64OrDefault

首次引入版本：v21.11.0

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

语法

toUInt64OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

Response

64

转换失败

Query

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

Response

0

​

toUInt64OrNull

引入于：v1.1.0

与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误则返回 NULL。

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参见：

• toUInt64。
• toUInt64OrZero。
• toUInt64OrDefault。

语法

toUInt64OrNull(x)

参数

• x — 字符串表示形式。String

返回值

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

示例

使用示例

Query

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt64OrZero

引入版本：v1.1.0

与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误，则返回 0。

支持的参数：

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

不支持的参数 (返回 0) ：

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

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

另请参见：

• toUInt64。
• toUInt64OrNull。
• toUInt64OrDefault。

语法

toUInt64OrZero(x)

参数

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

返回值

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

示例

使用示例

Query

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

​

toUInt8

Introduced in: v1.1.0

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

支持的参数：

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

不支持的参数：

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

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

该函数采用 向零舍入，即截断数字的小数位。

另请参见：

• toUInt8OrZero。
• toUInt8OrNull。
• toUInt8OrDefault。

语法

toUInt8(expr)

参数

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

返回值

返回 8 位无符号整数值。UInt8

示例

使用示例

Query

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Response

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

​

toUInt8OrDefault

Introduced in：v21.11.0

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

Syntax

toUInt8OrDefault(expr[, default])

参数

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

返回值

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

示例

转换成功

Query

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

Response

8

转换失败

Query

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

Response

0

​

toUInt8OrNull

引入版本：v1.1.0

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

支持的参数：

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

不支持的参数 (返回 NULL) ：

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

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

另请参见：

• toUInt8。
• toUInt8OrZero。
• toUInt8OrDefault。

语法

toUInt8OrNull(x)

参数

• x — 字符串表示形式。String

返回值

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

示例

使用示例

Query

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): ᴺᵁᴸᴸ

​

toUInt8OrZero

首次引入于：v1.1.0

与 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

示例

用法示例

Query

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

Response

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

​

toUUID

引入版本：v1.1.0

将 String 类型的值转换为 UUID 值。

语法

toUUID(string)

参数

• string — 字符串形式的 UUID。String 或 FixedString

返回值

根据 UUID 的字符串表示形式返回一个 UUID。UUID

示例

使用示例

Query

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

Response

┌─uuid─────────────────────────────────┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

​

toUUIDOrZero

Introduced in: v20.12.0

将输入值转换为 UUID 类型的值，但如果发生错误，则返回零 UUID。 与 toUUID 类似，但在转换出错时会返回零 UUID (00000000-0000-0000-0000-000000000000) ，而不是抛出异常。

支持的参数：

• 标准格式 UUID 的字符串表示形式 (8-4-4-4-12 个十六进制数字) 。
• 不带连字符的 UUID 字符串表示形式 (32 个十六进制数字) 。

不支持的参数 (返回零 UUID) ：

• 无效的字符串格式。
• 非字符串类型。

Syntax

toUUIDOrZero(x)

参数

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

返回值

成功时返回 UUID 值，否则返回零 UUID (00000000-0000-0000-0000-000000000000) 。UUID

示例

使用示例

Query

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

​

toUnixTimestamp64Micro

引入版本：v20.5.0

将 DateTime64 转换为具有固定微秒精度的 Int64 值。 输入值会根据其精度相应地进行放大或缩小。

输出值以 UTC 为基准，而不是以输入值的时区为基准。

语法

toUnixTimestamp64Micro(value)

参数

• value — 任意精度的 DateTime64 类型值。DateTime64

返回值

返回以微秒为单位的 Unix 时间戳。Int64

示例

使用示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

Response

┌─toUnixTimestamp64Micro(dt64)─┐
│             1739489491011123 │
└──────────────────────────────┘

​

toUnixTimestamp64Milli

引入版本：v20.5.0

将 DateTime64 转换为具有固定毫秒精度的 Int64 值。 输入值会根据其精度按相应比例放大或缩小。

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Milli(value)

参数

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

返回值

返回一个以毫秒为单位的 Unix 时间戳。Int64

示例

用法示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

Response

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

​

toUnixTimestamp64Nano

引入版本：v20.5.0

将 DateTime64 转换为具有固定纳秒精度的 Int64 值。 输入值会根据其精度相应放大或缩小。

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Nano(value)

参数

• value — 任意精度的 DateTime64 值。DateTime64

返回值

返回以纳秒为单位的 Unix 时间戳。Int64

示例

使用示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

Response

┌─toUnixTimestamp64Nano(dt64)─┐
│         1739489491011123456 │
└─────────────────────────────┘

​

toUnixTimestamp64Second

引入版本：v24.12.0

将 DateTime64 转换为具有固定秒级精度的 Int64 值。 输入值会根据其精度相应按比例放大或缩小。

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Second(value)

参数

• value — 任意精度的 DateTime64 类型值。DateTime64

返回值

返回以秒为单位的 Unix 时间戳。Int64

示例

使用示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

Response

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘