Set up docs MCP数据转换中的常见问题
ClickHouse 通常采用与 C++ 程序相同的行为。
to<type> 函数和 cast 在某些情况下的行为有所不同，例如对于 LowCardinality：cast 会移除 LowCardinality 特性，而 to<type> 函数不会。对于 Nullable 也是如此。此行为与 SQL 标准不兼容，但可以通过 cast_keep_nullable 设置进行更改。
示例：
SELECT
toTypeName(toLowCardinality('') AS val) AS source_type,
toTypeName(toString(val)) AS to_type_result_type,
toTypeName(CAST(val, 'String')) AS cast_result_type
┌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++ 中不同数值类型之间赋值相同的规则。
示例
SELECT
now() AS ts,
time_zone,
toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast │ 2023-09-08 20:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belgrade │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Berlin │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bratislava │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Brussels │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Bucharest │ 2023-09-08 22:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘另请参见 toUnixTimestamp 函数。
CAST
Introduced in：v1.1.0
将一个值转换为指定的数据类型。
与 reinterpret 函数不同，CAST 会尝试在目标类型中得到相同的值。
如果无法实现，则会引发异常。
Syntax
CAST(x, T)
or CAST(x AS T)
or x::T参数
返回值
返回转换为目标数据类型后的值。Any
示例
基本用法
SELECT CAST(42, 'String')┌─CAST(42, 'String')─┐
│ 42 │
└────────────────────┘使用 AS 语法
SELECT CAST('2025-01-01' AS Date)┌─CAST('2025-01-01', 'Date')─┐
│ 2025-01-01 │
└────────────────────────────┘使用 :: 语法
SELECT '123'::UInt32┌─CAST('123', 'UInt32')─┐
│ 123 │
└───────────────────────┘DATE
引入于：v21.2.0
将参数转换为 Date 数据类型。这是 toDate 的 MySQL 兼容别名，行为与 toDate 相同。
语法
DATE(expr)参数
返回值
返回 Date 值。Date
示例
基本用法
SELECT DATE('2023-01-01')2023-01-01accurateCast
引入版本：v1.1.0
将一个值转换为指定的数据类型。与 CAST 不同，accurateCast 会执行更严格的类型检查；如果转换会导致数据精度丢失，或无法进行转换，则会抛出异常。
与常规的 CAST 相比，该函数更安全，因为它可以防止精度丢失和无效转换。
语法
accurateCast(x, T)参数
返回值
返回转换为目标数据类型后的值。Any
示例
转换成功
SELECT accurateCast(42, 'UInt16')┌─accurateCast(42, 'UInt16')─┐
│ 42 │
└────────────────────────────┘字符串转为数字
SELECT accurateCast('123.45', 'Float64')┌─accurateCast('123.45', 'Float64')─┐
│ 123.45 │
└───────────────────────────────────┘accurateCastOrDefault
引入版本：v21.1.0
将值转换为指定的数据类型。
与 accurateCast 类似，但如果无法进行精确转换，则返回默认值，而不是抛出异常。
如果将默认值作为第二个参数传入，则该值必须属于目标类型。 如果未提供默认值，则使用目标类型的默认值。
语法
accurateCastOrDefault(x, T[, default_value])参数
x— 要转换的值。AnyT— 目标数据类型名称。const Stringdefault_value— 可选。如果转换失败，返回此默认值。Any
返回值
返回转换后的目标数据类型值；如果无法转换，则返回默认值。Any
示例
转换成功
SELECT accurateCastOrDefault(42, 'String')┌─accurateCastOrDefault(42, 'String')─┐
│ 42 │
└─────────────────────────────────────┘转换失败时使用显式默认值
SELECT accurateCastOrDefault('abc', 'UInt32', 999::UInt32)┌─accurateCastOrDefault('abc', 'UInt32', CAST('999', 'UInt32'))─┐
│ 999 │
└───────────────────────────────────────────────────────────────┘使用隐式默认值的转换失败
SELECT accurateCastOrDefault('abc', 'UInt32')┌─accurateCastOrDefault('abc', 'UInt32')─┐
│ 0 │
└────────────────────────────────────────┘accurateCastOrNull
引入版本：v1.1.0
将值转换为指定的数据类型。
与 accurateCast 类似，但如果无法精确完成转换，则返回 NULL，而不是抛出异常。
此函数结合了 accurateCast 的安全性以及更平稳的错误处理方式。
语法
accurateCastOrNull(x, T)参数
返回值
返回转换为目标数据类型后的值；如果无法转换，则返回 NULL。Any
示例
转换成功
SELECT accurateCastOrNull(42, 'String')┌─accurateCastOrNull(42, 'String')─┐
│ 42 │
└──────────────────────────────────┘转换失败则返回 NULL
SELECT accurateCastOrNull('abc', 'UInt32')┌─accurateCastOrNull('abc', 'UInt32')─┐
│ ᴺᵁᴸᴸ │
└─────────────────────────────────────┘formatRow
引入版本：v20.7.0
通过指定格式将任意表达式转换为字符串。
语法
formatRow(format, x, y, ...)参数
返回值
格式化后的字符串。 (对于文本格式，通常会以换行符结尾。) String
示例
基本用法
SELECT formatRow('CSV', number, 'good')
FROM numbers(3)┌─formatRow('CSV', number, 'good')─┐
│ 0,"good" ↴│
│ 1,"good" ↴│
│ 2,"good" ↴│
└──────────────────────────────────┘使用自定义格式
SELECT formatRow('CustomSeparated', number, 'good')
FROM numbers(3)
SETTINGS format_custom_result_before_delimiter='<prefix>\n', format_custom_result_after_delimiter='<suffix>'┌─formatRow('CustomSeparated', number, 'good')─┐
│ <prefix> ↴│
│↳0 good ↴│
│↳<suffix> │
│ <prefix> ↴│
│↳1 good ↴│
│↳<suffix> │
│ <prefix> ↴│
│↳2 good ↴│
│↳<suffix> │
└──────────────────────────────────────────────┘formatRowNoNewline
引入版本：v20.7.0
与 formatRow 相同，但会去掉每行末尾的换行符。
通过指定的格式将任意表达式转换为字符串，但会移除结果末尾的所有换行符。
语法
formatRowNoNewline(format, x, y, ...)参数
返回值
返回去除了换行符的格式化字符串。String
示例
基本用法
SELECT formatRowNoNewline('CSV', number, 'good')
FROM numbers(3)┌─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])参数
返回值
返回具有微秒精度的 DateTime64 值。DateTime64(6)
示例
使用示例
SELECT fromUnixTimestamp64Micro(1640995200123456)┌─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])参数
返回值
具有毫秒精度的 DateTime64 值。DateTime64(3)
示例
用法示例
SELECT fromUnixTimestamp64Milli(1640995200123)┌─fromUnixTimestamp64Milli(1640995200123)─┐
│ 2022-01-01 00:00:00.123 │
└─────────────────────────────────────────┘fromUnixTimestamp64Nano
引入版本：v20.5.0
将纳秒级 Unix 时间戳转换为具有纳秒精度的 DateTime64 值。
输入值会被视为纳秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 以来的纳秒数) 。
语法
fromUnixTimestamp64Nano(value[, timezone])参数
返回值
返回具有纳秒精度的 DateTime64 值。DateTime64(9)
示例
用法示例
SELECT fromUnixTimestamp64Nano(1640995200123456789)┌─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])参数
返回值
返回一个具有秒级精度的 DateTime64 值。DateTime64(0)
示例
用法示例
SELECT fromUnixTimestamp64Second(1640995200)┌─fromUnixTimestamp64Second(1640995200)─┐
│ 2022-01-01 00:00:00 │
└───────────────────────────────────────┘parseDateTime
引入版本：v23.3.0
根据 MySQL 日期格式字符串解析日期时间字符串。
此函数是 formatDateTime 的逆函数。
它使用格式 String 解析 String 参数，并返回 DateTime 类型。
语法
parseDateTime(time_string, format[, timezone])别名: TO_UNIXTIME
参数
time_string— 要解析为 DateTime 的字符串。Stringformat— 用于指定如何解析 time_string 的格式字符串。Stringtimezone— 可选。时区。String
返回值
根据 MySQL 风格的格式字符串，从输入字符串解析出的 DateTime。DateTime
示例
使用示例
SELECT parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')┌─parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│ 2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────┘parseDateTime32BestEffort
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 以 DateTime 类型返回。DateTime
示例
使用示例
SELECT parseDateTime32BestEffort('23/10/2025 12:12:57')
AS parseDateTime32BestEffort┌─parseDateTime32BestEffort─┐
│ 2025-10-23 12:12:57 │
└───────────────────────────┘带时区
SELECT parseDateTime32BestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul')
AS parseDateTime32BestEffort┌─parseDateTime32BestEffort─┐
│ 2025-08-18 10:22:16 │
└───────────────────────────┘Unix 时间戳
SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort┌─parseDateTime32BestEffort─┐
│ 2010-09-10 06:51:25 │
└───────────────────────────┘parseDateTime32BestEffortOrNull
引入版本：v20.9.0
与 parseDateTime32BestEffort 相同，但在遇到无法处理的日期格式时会返回 NULL。
语法
parseDateTime32BestEffortOrNull(time_string[, time_zone])参数
返回值
返回从字符串中解析出的 DateTime 对象；如果解析失败，则返回 NULL。DateTime
示例
使用示例
SELECT
parseDateTime32BestEffortOrNull('23/10/2025 12:12:57') AS valid,
parseDateTime32BestEffortOrNull('invalid date') AS invalid┌───────────────valid─┬─invalid─┐
│ 2025-10-23 12:12:57 │ ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘parseDateTime32BestEffortOrZero
引入版本：v20.9.0
与 parseDateTime32BestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。
语法
parseDateTime32BestEffortOrZero(time_string[, time_zone])参数
返回值
返回从字符串解析出的 DateTime 对象；如果解析失败，则返回零日期 (1970-01-01 00:00:00) 。DateTime
示例
使用示例
SELECT
parseDateTime32BestEffortOrZero('23/10/2025 12:12:57') AS valid,
parseDateTime32BestEffortOrZero('invalid date') AS invalid┌───────────────valid─┬─────────────invalid─┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘parseDateTime64
引入版本：v24.11.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。Stringformat— 用于指定如何解析 time_string 的格式字符串。Stringtimezone— 可选。时区。String
返回值
返回根据 MySQL 风格的格式字符串从输入字符串解析得到的 DateTime64。DateTime64
示例
用法示例
SELECT parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')┌─parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│ 2025-01-04 23:00:00.123000 │
└────────────────────────────────────────────────────────────────────┘parseDateTime64BestEffort
在 v20.1.0 中引入
与 parseDateTimeBestEffort 函数相同，但还支持解析毫秒和微秒，并返回 DateTime64 数据类型。
语法
parseDateTime64BestEffort(time_string[, precision[, time_zone]])参数
time_string— 包含待转换日期或日期时间的 String。Stringprecision— 可选。所需精度。3表示毫秒，6表示微秒。默认值：3。UInt8time_zone— 可选。时区。函数会根据该时区解析time_string。String
返回值
返回转换为 DateTime64 数据类型的 time_string。 DateTime64
示例
用法示例
SELECT parseDateTime64BestEffort('2025-01-01') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',3,'Asia/Istanbul') AS a, toTypeName(a) AS t
FORMAT PrettyCompactMonoBlock┌──────────────────────────a─┬─t──────────────────────────────┐
│ 2025-01-01 01:01:00.123000 │ DateTime64(3) │
│ 2025-01-01 00:00:00.000000 │ DateTime64(3) │
│ 2025-01-01 01:01:00.123460 │ DateTime64(6) │
│ 2025-12-31 22:01:00.123000 │ DateTime64(3, 'Asia/Istanbul') │
└────────────────────────────┴────────────────────────────────┘parseDateTime64BestEffortOrNull
引入版本：v20.1.0
与 parseDateTime64BestEffort 相同，不同之处在于，遇到无法处理的日期格式时会返回 NULL。
语法
parseDateTime64BestEffortOrNull(time_string[, precision[, time_zone]])参数
time_string— 包含要转换的日期或日期时间的 String。Stringprecision— 可选。所需精度。3表示毫秒，6表示微秒。默认值：3。UInt8time_zone— 可选。时区。函数会根据该时区解析time_string。String
返回值
返回转换后的 DateTime64 类型 time_string；如果输入无法解析，则返回 NULL。DateTime64 或 NULL
示例
用法示例
SELECT parseDateTime64BestEffortOrNull('2025-01-01 01:01:00.123') AS valid,
parseDateTime64BestEffortOrNull('invalid') AS invalid┌───────────────────valid─┬─invalid─┐
│ 2025-01-01 01:01:00.123 │ ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘parseDateTime64BestEffortOrZero
引入版本：v20.1.0
与 parseDateTime64BestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。
语法
parseDateTime64BestEffortOrZero(time_string[, precision[, time_zone]])参数
time_string— 包含要转换的日期或日期时间的 String。Stringprecision— 可选。所需精度。3表示毫秒，6表示微秒。默认值：3。UInt8time_zone— 可选。时区。函数会按照该时区解析time_string。String
返回值
返回转换后的 DateTime64 类型 time_string；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 00:00:00.000) 。DateTime64
示例
使用示例
SELECT parseDateTime64BestEffortOrZero('2025-01-01 01:01:00.123') AS valid,
parseDateTime64BestEffortOrZero('invalid') AS invalid┌───────────────────valid─┬─────────────────invalid─┐
│ 2025-01-01 01:01:00.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘parseDateTime64BestEffortUS
引入版本：v22.8.0
与 parseDateTime64BestEffort 相同，但在日期格式存在歧义时，此函数会优先采用美国日期格式 (MM/DD/YYYY 等) 。
语法
parseDateTime64BestEffortUS(time_string [, precision [, time_zone]])参数
time_string— 包含要转换的日期或日期时间的 String。Stringprecision— 可选。所需精度。3表示毫秒，6表示微秒。默认值：3。UInt8time_zone— 可选。时区。函数会根据该时区解析time_string。String
返回值
返回将 time_string 转换为 DateTime64 后的结果；对于有歧义的情况，优先按美国日期格式解析。DateTime64
示例
使用示例
SELECT parseDateTime64BestEffortUS('02/10/2025 12:30:45.123') AS us_format,
parseDateTime64BestEffortUS('15/08/2025 10:15:30.456') AS fallback_to_standard┌───────────────us_format─┬────fallback_to_standard─┐
│ 2025-02-10 12:30:45.123 │ 2025-08-15 10:15:30.456 │
└─────────────────────────┴─────────────────────────┘parseDateTime64BestEffortUSOrNull
引入版本：v22.8.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)
示例
使用示例
SELECT parseDateTime64BestEffortUSOrNull('02/10/2025 12:30:45.123') AS valid_us,
parseDateTime64BestEffortUSOrNull('invalid') AS invalid┌────────────────valid_us─┬─invalid─┐
│ 2025-02-10 12:30:45.123 │ ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘parseDateTime64BestEffortUSOrZero
引入版本：v22.8.0
与 parseDateTime64BestEffort 相同，不同之处在于，此函数在存在歧义时会优先使用美国日期格式 (MM/DD/YYYY 等) ，并且在遇到无法处理的日期格式时会返回零日期或零日期时间。
语法
parseDateTime64BestEffortUSOrZero(time_string [, precision [, time_zone]])参数
time_string— 包含要转换的日期或日期时间的 String。Stringprecision— 可选。所需精度。3表示毫秒，6表示微秒。默认值：3。UInt8time_zone— 可选。时区。该函数会按此时区解析time_string。String
返回值
返回按美国日期格式优先规则转换后的 time_string 的 DateTime64 值；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 00:00:00.000) 。DateTime64
示例
使用示例
SELECT parseDateTime64BestEffortUSOrZero('02/10/2025 12:30:45.123') AS valid_us,
parseDateTime64BestEffortUSOrZero('invalid') AS invalid┌────────────────valid_us─┬─────────────────invalid─┐
│ 2025-02-10 12:30:45.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘parseDateTime64InJodaSyntax
引入版本：v24.10.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 的字符串。Stringformat— Joda 语法格式字符串，用于指定如何解析 time_string。Stringtimezone— 可选。时区。String
返回值
返回根据 Joda 风格格式字符串从输入字符串解析出的 DateTime64。DateTime64
示例
使用示例
SELECT parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')┌─parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│ 2025-01-04 23:00:00.123 │
└───────────────────────────────────────────────────────────────────────────────────┘parseDateTime64InJodaSyntaxOrNull
Introduced in: v24.10.0
与 parseDateTime64InJodaSyntax 相同，但遇到无法解析的日期格式时会返回 NULL。
Syntax
parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])参数
time_string— 要解析为 DateTime64 的字符串。Stringformat— 采用 Joda 语法的格式字符串，用于指定如何解析 time_string。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析出的 DateTime64；如果解析失败，则返回 NULL。Nullable(DateTime64)
示例
使用示例
SELECT parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')┌─parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│ 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────────────────────────┘parseDateTime64InJodaSyntaxOrZero
引入版本：v24.10.0
与 parseDateTime64InJodaSyntax 相同，但在遇到无法解析的日期格式时会返回零日期。
语法
parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])参数
time_string— 要解析为 DateTime64 的字符串。Stringformat— 采用 Joda 语法的格式字符串，用于指定如何解析 time_string。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析出的 DateTime64；如果解析失败，则返回零值 DateTime64。DateTime64
示例
使用示例
SELECT parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')┌─parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│ 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────────────────────────┘parseDateTime64OrNull
引入于：v24.11.0
与 parseDateTime64 相同，但遇到无法解析的日期格式时会返回 NULL。
语法
parseDateTime64OrNull(time_string, format[, timezone])参数
time_string— 将被解析为 DateTime64 的字符串。Stringformat— 指定 time_string 解析方式的格式字符串。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析得到的 DateTime64；如果解析失败，则返回 NULL。Nullable(DateTime64)
示例
用法示例
SELECT parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')┌─parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│ 2025-01-04 23:00:00.123000 │
└──────────────────────────────────────────────────────────────────────────┘parseDateTime64OrZero
引入版本：v24.11.0
与 parseDateTime64 相同，但遇到无法解析的日期格式时会返回零日期。
语法
parseDateTime64OrZero(time_string, format[, timezone])参数
time_string— 要解析为 DateTime64 的字符串。Stringformat— 指定解析 time_string 方式的格式字符串。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析得到的 DateTime64；如果解析失败，则返回零值 DateTime64。DateTime64
示例
用法示例
SELECT parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')┌─parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│ 2025-01-04 23:00:00.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])参数
返回值
返回 DateTime 类型的 time_string。DateTime
示例
用法示例
SELECT parseDateTimeBestEffort('23/10/2025 12:12:57') AS parseDateTimeBestEffort┌─parseDateTimeBestEffort─┐
│ 2025-10-23 12:12:57 │
└─────────────────────────┘带有时区
SELECT parseDateTimeBestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul') AS parseDateTimeBestEffort┌─parseDateTimeBestEffort─┐
│ 2025-08-18 10:22:16 │
└─────────────────────────┘Unix 时间戳
SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort┌─parseDateTimeBestEffort─┐
│ 2025-01-01 00:00:00 │
└─────────────────────────┘parseDateTimeBestEffortOrNull
引入版本：v1.1.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 会以 DateTime 形式返回；如果输入无法解析，则返回 NULL。DateTime 或 NULL
示例
使用示例
SELECT parseDateTimeBestEffortOrNull('23/10/2025 12:12:57') AS valid,
parseDateTimeBestEffortOrNull('invalid') AS invalid┌───────────────valid─┬─invalid─┐
│ 2025-10-23 12:12:57 │ ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘parseDateTimeBestEffortOrZero
引入版本：v1.1.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 作为 DateTime 返回；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 或 1970-01-01 00:00:00) 。DateTime
示例
使用示例
SELECT parseDateTimeBestEffortOrZero('23/10/2025 12:12:57') AS valid,
parseDateTimeBestEffortOrZero('invalid') AS invalid┌───────────────valid─┬─────────────invalid─┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘parseDateTimeBestEffortUS
引入于：v1.1.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 解析为 DateTime 的结果；对于有歧义的情况，优先按照美国日期格式进行解析。DateTime
示例
使用示例
SELECT parseDateTimeBestEffortUS('02/10/2025') AS us_format,
parseDateTimeBestEffortUS('15/08/2025') AS fallback_to_standard┌───────────us_format─┬─fallback_to_standard─┐
│ 2025-02-10 00:00:00 │ 2025-08-15 00:00:00 │
└─────────────────────┴──────────────────────┘parseDateTimeBestEffortUSOrNull
引入版本：v1.1.0
与 parseDateTimeBestEffortUS 函数相同，不同之处在于：当遇到无法处理的日期格式时，它会返回 NULL。
对于 ISO 日期格式，此函数的行为与 parseDateTimeBestEffort 相同；但在存在歧义的情况下，会优先采用美国日期格式，并在解析出错时返回 NULL。
语法
parseDateTimeBestEffortUSOrNull(time_string[, time_zone])参数
返回值
将 time_string 按照美国日期格式优先规则解析为 DateTime 并返回；如果输入无法解析，则返回 NULL。DateTime 或 NULL
示例
用法示例
SELECT parseDateTimeBestEffortUSOrNull('02/10/2025') AS valid_us,
parseDateTimeBestEffortUSOrNull('invalid') AS invalid┌────────────valid_us─┬─invalid─┐
│ 2025-02-10 00:00:00 │ ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘parseDateTimeBestEffortUSOrZero
引入版本：v1.1.0
与 parseDateTimeBestEffortUS 函数相同，但当遇到无法处理的日期格式时，它会返回零日期 (1970-01-01) 或零日期时间 (1970-01-01 00:00:00) 。
对于 ISO 日期格式，此函数的行为与 parseDateTimeBestEffort 相同；但在存在歧义的情况下，会优先采用美国日期格式，并在解析错误时返回零值。
语法
parseDateTimeBestEffortUSOrZero(time_string[, time_zone])参数
返回值
以美国日期格式优先规则的方式将 time_string 解析为 DateTime 并返回；如果输入无法解析，则返回零日期/日期时间 (1970-01-01 或 1970-01-01 00:00:00) 。DateTime
示例
使用示例
SELECT parseDateTimeBestEffortUSOrZero('02/10/2025') AS valid_us,
parseDateTimeBestEffortUSOrZero('invalid') AS invalid┌────────────valid_us─┬─────────────invalid─┐
│ 2025-02-10 00:00:00 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘parseDateTimeInJodaSyntax
引入版本：v23.3.0
根据 Joda 日期格式字符串解析日期时间字符串。
此函数是 formatDateTimeInJodaSyntax 的逆操作。
它使用 Joda 风格的格式 String 解析 String 参数，并返回 DateTime 类型。
有关格式模式，请参阅 Joda Time 文档。
语法
parseDateTimeInJodaSyntax(time_string, format[, timezone])参数
time_string— 将被解析为 DateTime 的 String。Stringformat— Joda 语法格式字符串，用于指定如何解析 time_string。Stringtimezone— 可选。时区。String
返回值
根据 Joda 风格的格式字符串，从输入字符串解析得到的 DateTime。DateTime
示例
使用示例
SELECT parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')┌─parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│ 2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────────────┘parseDateTimeInJodaSyntaxOrNull
引入版本：v23.3.0
与 parseDateTimeInJodaSyntax 相同，但在遇到无法解析的日期格式时返回 NULL。
语法
parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])参数
time_string— 要被解析为 DateTime 的字符串。Stringformat— 采用 Joda 语法的格式字符串，用于指定如何解析 time_string。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串中解析得到的 DateTime；如果解析失败，则返回 NULL。Nullable(DateTime)
示例
使用示例
SELECT parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')┌─parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│ 2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────────────────────────┘parseDateTimeInJodaSyntaxOrZero
引入版本：v23.3.0
与 parseDateTimeInJodaSyntax 相同，但遇到无法解析的日期格式时会返回零日期。
语法
parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])参数
time_string— 要解析为 DateTime 的字符串。Stringformat— 采用 Joda 语法的格式字符串，用于指定如何解析 time_string。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析得到的 DateTime；如果解析失败，则返回零 DateTime。DateTime
示例
使用示例
SELECT parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')┌─parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│ 2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────────────────────────┘parseDateTimeOrNull
版本引入：v23.3.0
与 parseDateTime 相同，但遇到无法解析的日期格式时会返回 NULL。
语法
parseDateTimeOrNull(time_string, format[, timezone])别名: str_to_date
参数
time_string— 要解析为 DateTime 的字符串。Stringformat— 指定如何解析 time_string 的格式字符串。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析得到的 DateTime；如果解析失败，则返回 NULL。Nullable(DateTime)
示例
使用示例
SELECT parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')┌─parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│ 2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘parseDateTimeOrZero
在以下版本中引入：v23.3.0
与 parseDateTime 相同，但在遇到无法解析的日期格式时会返回零日期。
语法
parseDateTimeOrZero(time_string, format[, timezone])参数
time_string— 要解析为 DateTime 的字符串。Stringformat— 指定time_string解析方式的格式字符串。Stringtimezone— 可选。时区。String
返回值
返回从输入字符串解析得到的 DateTime；如果解析失败，则返回零 DateTime。DateTime
示例
用法示例
SELECT parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')┌─parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│ 2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘reinterpret
引入版本：v1.1.0
对给定的值 x，使用其在内存中的同一源字节序列，并将其重新解释为目标类型。
当目标类型为 String 时，仅当源 Array 的元素类型为定长且在内存中连续存放时才支持 (例如，Array(UInt8) 或 Array(FixedString(2))) ；其元素字节会按照其原生内存顺序原样复制，因此在任何架构上，都可以将结果重新解释回原始 Array 类型。元素为变长 (例如，Array(String)) 或 Nullable (例如，Array(Nullable(Int32))) 的数组不受支持。
语法
reinterpret(x, type)参数
返回值
目标类型的值。Any
示例
用法示例
SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
reinterpret(toInt8(1), 'Float32') AS int_to_float,
reinterpret('1', 'UInt32') AS string_to_int┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│ 255 │ 1e-45 │ 49 │
└─────────────┴──────────────┴───────────────┘Array 示例
SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626] │
└────────────────────────────┘Array 到 String 示例
SELECT hex(reinterpret([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8), 'String')) AS array_of_UInt8_to_string┌─array_of_UInt8_to_string─┐
│ 0102FF │
└──────────────────────────┘reinterpretAsDate
引入版本：v1.1.0
将输入值重新解释为 Date 值 (假设采用小端字节序) ，即自 Unix 纪元 1970-01-01 起经过的天数
语法
reinterpretAsDate(x)参数
返回值
日期。Date
示例
使用示例
SELECT reinterpretAsDate(65), reinterpretAsDate('A')┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│ 1970-03-07 │ 1970-03-07 │
└───────────────────────┴────────────────────────┘reinterpretAsDateTime
引入版本：v1.1.0
将输入值重新解释为 DateTime 值 (按小端字节序) ，即自 Unix 纪元 1970-01-01 开始以来的天数
语法
reinterpretAsDateTime(x)参数
返回值
日期和时间。DateTime
示例
用法示例
SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')┌─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 的字节的定长字符串。FixedString
示例
使用示例
-- 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')))┌─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
示例
使用示例
SELECT reinterpretAsUInt32(toFloat32(0.2)) AS x, reinterpretAsFloat32(x)┌──────────x─┬─reinterpretAsFloat32(x)─┐
│ 1045220557 │ 0.2 │
└────────────┴─────────────────────────┘reinterpretAsFloat64
在以下版本中引入：v1.1.0
将输入值重新解释为 Float64 类型的值。
与 CAST 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出未定义。
语法
reinterpretAsFloat64(x)参数
返回值
返回重新解释后的值 x。Float64
示例
用法示例
SELECT reinterpretAsUInt64(toFloat64(0.2)) AS x, reinterpretAsFloat64(x)┌───────────────────x─┬─reinterpretAsFloat64(x)─┐
│ 4596373779694328218 │ 0.2 │
└─────────────────────┴─────────────────────────┘reinterpretAsInt128
首次引入于：v1.1.0
将输入值重新解释为 Int128 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，输出结果将是未定义的。
语法
reinterpretAsInt128(x)参数
返回值
返回重新解释后的值 x。Int128
示例
用法示例
SELECT
toInt64(257) AS x,
toTypeName(x),
reinterpretAsInt128(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int64 │ 257 │ Int128 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsInt16
首次引入于：v1.1.0
将输入值重新解释为 Int16 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。
语法
reinterpretAsInt16(x)参数
返回值
返回重新解释后的值 x。Int16
示例
使用示例
SELECT
toInt8(257) AS x,
toTypeName(x),
reinterpretAsInt16(x) AS res,
toTypeName(res)┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ Int8 │ 1 │ Int16 │
└───┴───────────────┴─────┴─────────────────┘reinterpretAsInt256
引入版本：v1.1.0
将输入值重新解释为 Int256 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。
语法
reinterpretAsInt256(x)参数
返回值
返回重新解释后的值 x。Int256
示例
使用示例
SELECT
toInt128(257) AS x,
toTypeName(x),
reinterpretAsInt256(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int128 │ 257 │ Int256 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsInt32
引入版本：v1.1.0
将输入值重新解释为 Int32 类型的值。
与 CAST 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
语法
reinterpretAsInt32(x)参数
返回值
返回重新解释后的值 x。Int32
示例
用法示例
SELECT
toInt16(257) AS x,
toTypeName(x),
reinterpretAsInt32(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int16 │ 257 │ Int32 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsInt64
引入版本：v1.1.0
将输入值重新解释为 Int64 类型的值。
与 CAST 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
语法
reinterpretAsInt64(x)参数
返回值
返回重新解释后的值 x。Int64
示例
使用示例
SELECT
toInt32(257) AS x,
toTypeName(x),
reinterpretAsInt64(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int32 │ 257 │ Int64 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsInt8
引入版本：v1.1.0
将输入值重新解释为 Int8 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示该输入类型，则输出结果未定义。
语法
reinterpretAsInt8(x)参数
返回值
返回重新解释后的值 x。Int8
示例
用法示例
SELECT
toUInt8(257) AS x,
toTypeName(x),
reinterpretAsInt8(x) AS res,
toTypeName(res)┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8 │ 1 │ Int8 │
└───┴───────────────┴─────┴─────────────────┘reinterpretAsString
引入版本：v1.1.0
将输入值重新解释为字符串。
对于标量值，字节顺序会归一化为小端字节序，且末尾的空字节会被忽略。例如，对于值为 255 的 UInt32，该函数会返回一个仅包含单个字符的字符串。
对于由固定大小元素组成的 Array，元素字节会按其原生内存顺序原样复制，不会裁剪末尾的零字节，也不会归一化为小端字节序，因此结果可以在任何架构上重新解释回原始 Array 类型。
语法
reinterpretAsString(x)参数
返回值
包含表示 x 的字节序列的字符串。String
示例
用法示例
-- 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')))┌─hex(reinterpretAsString(toDateTime('1970-01-01 01:01:05')))─┬─hex(reinterpretAsString(toDate('1970-03-07')))─┐
│ 510E │ 41 │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘Array 转 String 示例
SELECT hex(reinterpretAsString([toUInt8(1), toUInt8(2), toUInt8(255)]::Array(UInt8))) AS array_of_UInt8_to_string┌─array_of_UInt8_to_string─┐
│ 0102FF │
└──────────────────────────┘reinterpretAsUInt128
首次引入于：v1.1.0
将输入值重新解释为 UInt128 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示该输入类型，则输出结果未定义。
语法
reinterpretAsUInt128(x)参数
返回值
返回重新解释后的值 x。UInt128
示例
使用示例
SELECT
toUInt64(257) AS x,
toTypeName(x),
reinterpretAsUInt128(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt64 │ 257 │ UInt128 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsUInt16
引入版本：v1.1.0
将输入值重新解释为 UInt16 类型的值。
与 CAST 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
语法
reinterpretAsUInt16(x)参数
返回值
返回重新解释后的值 x。UInt16
示例
用法示例
SELECT
toUInt8(257) AS x,
toTypeName(x),
reinterpretAsUInt16(x) AS res,
toTypeName(res)┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8 │ 1 │ UInt16 │
└───┴───────────────┴─────┴─────────────────┘reinterpretAsUInt256
Introduced in: v1.1.0
将输入值重新解释为 UInt256 类型的值。
与 CAST 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
Syntax
reinterpretAsUInt256(x)参数
返回值
返回重新解释后的值 x。UInt256
示例
用法示例
SELECT
toUInt128(257) AS x,
toTypeName(x),
reinterpretAsUInt256(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt128 │ 257 │ UInt256 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsUInt32
首次引入版本：v1.1.0
将输入值重新解释为 UInt32 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果是未定义的。
语法
reinterpretAsUInt32(x)参数
返回值
返回重新解释后的 x 值。UInt32
示例
使用示例
SELECT
toUInt16(257) AS x,
toTypeName(x),
reinterpretAsUInt32(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt16 │ 257 │ UInt32 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsUInt64
首次引入版本：v1.1.0
将输入值重新解释为 UInt64 类型的值。
与 CAST 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出未定义。
语法
reinterpretAsUInt64(x)参数
返回值
返回 x 重新解释后的值。UInt64
示例
使用示例
SELECT
toUInt32(257) AS x,
toTypeName(x),
reinterpretAsUInt64(x) AS res,
toTypeName(res)┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt32 │ 257 │ UInt64 │
└─────┴───────────────┴─────┴─────────────────┘reinterpretAsUInt8
Introduced in：v1.1.0
将输入值重新解释为 UInt8 类型的值。
与 CAST 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。
Syntax
reinterpretAsUInt8(x)参数
返回值
返回重新解释后的值 x。UInt8
示例
用法示例
SELECT
toInt8(-1) AS val,
toTypeName(val),
reinterpretAsUInt8(val) AS res,
toTypeName(res);┌─val─┬─toTypeName(val)─┬─res─┬─toTypeName(res)─┐
│ -1 │ Int8 │ 255 │ UInt8 │
└─────┴─────────────────┴─────┴─────────────────┘reinterpretAsUUID
首次引入版本：v1.1.0
接受一个 16 字节字符串，并将其中每个 8 字节半段按 little-endian 字节序解释后返回一个 UUID。如果字符串长度不足，函数会像在末尾补足所需数量的空字节一样处理；如果字符串长度超过 16 字节，则会忽略末尾多出的字节。
语法
reinterpretAsUUID(fixed_string)参数
fixed_string— 大端字节串。FixedString
返回值
UUID 类型的值。UUID
示例
字符串转换为 UUID
SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))┌─reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))─┐
│ 08090a0b-0c0d-0e0f-0001-020304050607 │
└───────────────────────────────────────────────────────────────────────┘toBFloat16
引入版本：v1.1.0
将输入值转换为 BFloat16 类型的值。 如果发生错误，会抛出异常。
另请参见：
语法
toBFloat16(expr)参数
expr— 返回数值或数字字符串表示形式的表达式。Expression
返回值
返回一个 16 位 brain-float 类型的值。BFloat16
示例
使用示例
SELECT
toBFloat16(toFloat32(42.7)),
toBFloat16(toFloat32('42.7')),
toBFloat16('42.7')
FORMAT Vertical;Row 1:
──────
toBFloat16(toFloat32(42.7)): 42.5
toBFloat16(toFloat32('42.7')): 42.5
toBFloat16('42.7'): 42.5toBFloat16OrNull
引入于：v1.1.0
将 String 输入值转换为 BFloat16 类型的值。 如果字符串不表示浮点值，则该函数返回 NULL。
支持的参数：
- 数值的字符串表示形式。
不支持的参数 (返回 NULL) ：
- 二进制和十六进制值的字符串表示形式。
- 数值。
另请参见：
语法
toBFloat16OrNull(x)参数
x— 数字的String字符串表示形式。String
返回值
返回一个 16 位 brain-float 值；否则返回 NULL。BFloat16 或 NULL
示例
用法示例
SELECT toBFloat16OrNull('0x5E'), -- unsupported arguments
toBFloat16OrNull('12.3'), -- typical use
toBFloat16OrNull('12.3456789') -- silent loss of precision\N 12.25 12.3125toBFloat16OrZero
引入版本：v1.1.0
将 String 输入值转换为 BFloat16 类型的值。 如果该字符串不表示浮点数值，则函数返回零。
支持的参数：
- 数值的字符串表示形式。
不支持的参数 (返回 0) ：
- 二进制和十六进制值的字符串表示形式。
- 数值。
另请参见：
语法
toBFloat16OrZero(x)参数
x— 数字的String表示形式。String
返回值
返回一个 16 位 brain-float 值；否则返回 0。BFloat16
示例
使用示例
SELECT toBFloat16OrZero('0x5E'), -- unsupported arguments
toBFloat16OrZero('12.3'), -- typical use
toBFloat16OrZero('12.3456789') -- silent loss of precision0 12.25 12.3125toBool
Introduced in：v22.2.0
将输入值转换为 Bool 类型。
语法
toBool(expr)参数
expr— 返回数值或字符串的表达式。对于字符串，可接受 'true' 或 'false' (不区分大小写) 。(U)Int*或Float*或String或Expression
返回值
根据参数的求值结果，返回 true 或 false。Bool
示例
用法示例
SELECT
toBool(toUInt8(1)),
toBool(toInt8(-1)),
toBool(toFloat32(1.01)),
toBool('true'),
toBool('false'),
toBool('FALSE')
FORMAT VerticalRow 1:
──────
toBool(toUInt8(1)): true
toBool(toInt8(-1)): true
toBool(toFloat32(1.01)): true
toBool('true'): true
toBool('false'): false
toBool('FALSE'): falsetoDate
引入版本：v1.1.0
将输入值转换为 Date 类型。
支持从 String、FixedString、DateTime 或数值类型转换。
语法
toDate(x)参数
x— 要转换的输入值。String或FixedString或DateTime或(U)Int*或Float*
返回值
返回转换后的输入值。Date
示例
将 String 转换为 Date
SELECT toDate('2025-04-15')2025-04-15将 DateTime 转换为 Date
SELECT toDate(toDateTime('2025-04-15 10:30:00'))2025-04-15整数转换为日期
SELECT toDate(20297)2025-07-28toDate32
引入版本：v21.9.0
将参数转换为 Date32 数据类型。
如果值超出 [0000-01-01, 9999-12-31] 范围，toDate32 会返回 Date32 支持的边界值。
如果参数类型为 Date，则会考虑其取值边界。
语法
toDate32(expr)参数
返回值
返回一个日历日期。Date32
示例
在取值范围内
SELECT toDate32('2025-01-01') AS value, toTypeName(value)
FORMAT VerticalRow 1:
──────
value: 2025-01-01
toTypeName(value): Date321900 年以前
SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT VerticalRow 1:
──────
value: 1899-01-01
toTypeName(value): Date32toDate32OrDefault
引入版本：v21.11.0
将参数转换为 Date32 数据类型。如果参数无法转换 (包括超出 Date32 范围的数值) ，该函数将返回默认值：如果指定了第二个参数，则返回该参数；否则返回 Date32 的历史默认值 1900-01-01 (而非其下界值 0000-01-01) 。如果参数的类型为 Date，则会考虑其边界。
请注意，与 toDate32 不同，该函数不会将超出范围的数值参数限制在 Date32 的边界值内；此类参数会被视为无法转换。
语法
toDate32OrDefault(expr[, default])参数
返回值
成功时返回 Date32 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 1900-01-01。Date32
示例
转换成功
SELECT toDate32OrDefault('1930-01-01', toDate32('2020-01-01'))1930-01-01转换失败
SELECT toDate32OrDefault('xx1930-01-01', toDate32('2020-01-01'))2020-01-01超出范围的数值
SELECT toDate32OrDefault(toUInt64(18446744073709551615), toDate32('2020-01-01'))2020-01-01toDate32OrNull
引入版本：v21.9.0
将输入值转换为 Date32 类型的值；如果参数无效，则返回 NULL。
与 toDate32 相同，但在参数无效时会返回 NULL。
语法
toDate32OrNull(x)参数
x— 日期的字符串表示形式。String
返回值
成功时返回 Date32 值，否则返回 NULL。Date32 或 NULL
示例
用法示例
SELECT toDate32OrNull('2025-01-01'), toDate32OrNull('invalid')┌─toDate32OrNull('2025-01-01')─┬─toDate32OrNull('invalid')─┐
│ 2025-01-01 │ ᴺᵁᴸᴸ │
└──────────────────────────────┴───────────────────────────┘toDate32OrZero
引入版本：v21.9.0
将输入值转换为 Date32 类型的值；如果收到无效参数，则返回默认值 1900-01-01。
与 toDate32 相同，但如果收到无效参数，则返回 1900-01-01。
请注意，1900-01-01 是无效输入的历史默认值，并非 Date32 的下界值；其下界值为 0000-01-01。
另请参见：
语法
toDate32OrZero(x)参数
x— 日期的字符串表示形式。String
返回值
成功时返回 Date32 值，否则返回无效输入的历史默认值 (1900-01-01) 。Date32
示例
使用示例
SELECT toDate32OrZero('2025-01-01'), toDate32OrZero('')┌─toDate32OrZero('2025-01-01')─┬─toDate32OrZero('')─┐
│ 2025-01-01 │ 1900-01-01 │
└──────────────────────────────┴────────────────────┘toDateOrDefault
引入版本：v21.11.0
与 toDate 类似，但如果转换失败，则返回默认值：若指定了第二个参数，则返回该参数；否则返回 Date 的下界值。
语法
toDateOrDefault(expr[, default])参数
返回值
如果转换成功，则返回 Date 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 1970-01-01。Date
示例
转换成功
SELECT toDateOrDefault('2022-12-30')2022-12-30转换失败
SELECT toDateOrDefault('', CAST('2023-01-01', 'Date'))2023-01-01toDateOrNull
首次引入版本：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
示例
用法示例
SELECT toDateOrNull('2025-12-30'), toDateOrNull('invalid')┌─toDateOrNull('2025-12-30')─┬─toDateOrNull('invalid')─┐
│ 2025-12-30 │ ᴺᵁᴸᴸ │
└────────────────────────────┴─────────────────────────┘toDateOrZero
引入版本：v1.1.0
将输入值转换为 Date 类型的值；如果传入的是无效参数，则返回 Date 的下界值。
与 toDate 相同，但如果传入的是无效参数，则返回 Date 的下界值。
另请参见：
语法
toDateOrZero(x)参数
x— 日期的字符串表示形式。String
返回值
成功时返回 Date 值，否则返回 Date 的下界值 (1970-01-01) 。Date
示例
用法示例
SELECT toDateOrZero('2025-12-30'), toDateOrZero('')┌─toDateOrZero('2025-12-30')─┬─toDateOrZero('')─┐
│ 2025-12-30 │ 1970-01-01 │
└────────────────────────────┴──────────────────┘toDateTime
引入于：v1.1.0
将输入值转换为 DateTime 类型。
语法
toDateTime(expr[, time_zone])参数
返回值
返回日期时间。DateTime
示例
使用示例
SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT VerticalRow 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'): 2025-01-01 00:00:00toDateTime32
引入于：v20.9.0
将输入值转换为 DateTime 类型。
支持从 String、FixedString、Date、Date32、Time、DateTime、DateTime64 或数值类型 ((U)Int8、(U)Int16、(U)Int32、(U)Int64、BFloat16、Float32、Float64) 转换。Decimal 和 Time64 值不受支持，会引发异常；Time 类型以及 (U)Int128/(U)Int256 等宽整数类型会发生回绕，而不会饱和。
DateTime32 是 DateTime 的别名，支持 1970-01-01 00:00:00 至 2106-02-07 06:28:15 范围内的日期时间。
从字符串或上述可饱和的数值类型转换时，超出此范围的值会被饱和到范围边界。非有限浮点值 (NaN、inf、-inf) 无法转换，会引发异常。
从 Date32 或 DateTime64 等其他日期时间类型转换时，遵循 date_time_overflow_behavior 设置：默认的 ignore 模式可能产生回绕值，saturate 会将值限制在范围边界内，而 throw 会引发异常。
语法
toDateTime32(x[, timezone])参数
x— 要转换的输入值。String、FixedString、(U)Int*、Float*、BFloat16、Date、Date32、Time、DateTime或DateTime64timezone— 可选。返回的DateTime值所使用的时区。String
返回值
返回转换后的输入值。DateTime
示例
从字符串转换
SELECT toDateTime32('2025-01-01 00:00:00') AS value, toTypeName(value);┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime │
└─────────────────────┴───────────────────┘从 Unix 时间戳转换
SELECT toDateTime32(1735689600, 'UTC') AS value, toTypeName(value);┌───────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00 │ DateTime('UTC') │
└─────────────────────┴───────────────────┘指定时区
SELECT toDateTime32('2025-01-01 00:00:00', 'Asia/Istanbul') AS value, toTypeName(value);┌───────────────value─┬─toTypeName(value)─────────┐
│ 2025-01-01 00:00:00 │ DateTime('Asia/Istanbul') │
└─────────────────────┴───────────────────────────┘toDateTime64
引入版本：v20.1.0
将输入值转换为 DateTime64 类型的值。
语法
toDateTime64(expr, scale[, timezone])参数
expr— 返回数值或数值字符串表示形式的表达式。Expressionscale— 时间粒度 (精度) ：10^(-scale) 秒。UInt8timezone— 可选。指定DateTime64对象的时区。String
返回值
返回具有子秒级精度的日历日期和时间。DateTime64
示例
值在范围内
SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);┌───────────────────value─┬─toTypeName(value)─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3) │
└─────────────────────────┴───────────────────┘作为指定精度的 Decimal
SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- Without the decimal point the value is still treated as Unix Timestamp in seconds
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);┌───────────────────value─┬─toTypeName(value)─┐
│ 2019-01-01 00:00:00.000 │ DateTime64(3) │
└─────────────────────────┴───────────────────┘
┌───────────────────value─┬─toTypeName(value)─┐
│ 9999-12-31 23:59:59.000 │ DateTime64(3) │
└─────────────────────────┴───────────────────┘指定时区
SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);┌───────────────────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 秒。UInt8timezone— 可选。时区。Stringdefault— 可选。解析失败时返回的默认值。DateTime64
返回值
成功时返回 DateTime64 类型的值；否则，如果传入了默认值则返回该默认值，若未传入则返回 1970-01-01 00:00:00.000。DateTime64
示例
成功转换
SELECT toDateTime64OrDefault('1976-10-18 00:00:00.30', 3)1976-10-18 00:00:00.300转换失败
SELECT toDateTime64OrDefault('1976-10-18 00:00:00 30', 3, 'UTC', toDateTime64('2001-01-01 00:00:00.00',3))2001-01-01 00:00:00.000toDateTime64OrNull
引入版本：v20.1.0
将输入值转换为 DateTime64 类型的值；如果接收到无效参数，则返回 NULL。
与 toDateTime64 相同，但如果接收到无效参数，则返回 NULL。
整数参数会被解释为以整秒表示的 Unix 时间戳；如果超出 DateTime64 类型的取值范围，则返回 NULL。
语法
toDateTime64OrNull(x[, precision[, timezone]])参数
x— 带有子秒级精度的日期时间字符串表示形式，或整数 Unix 时间戳。String或(U)Int8/16/32/64precision— 可选。返回值的子秒级精度。UInt8timezone— 可选。返回值的时区。String
返回值
如果成功，则返回 DateTime64 值；否则返回 NULL。DateTime64 或 NULL
示例
用法示例
SELECT toDateTime64OrNull('2025-12-30 13:44:17.123'), toDateTime64OrNull('invalid')┌─toDateTime64OrNull('2025-12-30 13:44:17.123')─┬─toDateTime64OrNull('invalid')─┐
│ 2025-12-30 13:44:17.123 │ ᴺᵁᴸᴸ │
└───────────────────────────────────────────────┴───────────────────────────────┘toDateTime64OrZero
引入版本：v20.1.0
将输入值转换为 DateTime64 类型的值；如果接收到无效参数，则返回 DateTime64 的下界值。 与 toDateTime64 相同，但在接收到无效参数时会返回 DateTime64 的下界值。
另请参见：
语法
toDateTime64OrZero(x)参数
x— 带有子秒级精度的日期时间字符串表示形式。String
返回值
成功时返回 DateTime64 值，否则返回 DateTime64 的下界值 (1970-01-01 00:00:00.000) 。DateTime64
示例
使用示例
SELECT toDateTime64OrZero('2025-12-30 13:44:17.123'), toDateTime64OrZero('invalid')┌─toDateTime64OrZero('2025-12-30 13:44:17.123')─┬─toDateTime64OrZero('invalid')─┐
│ 2025-12-30 13:44:17.123 │ 1970-01-01 00:00:00.000 │
└───────────────────────────────────────────────┴───────────────────────────────┘toDateTimeOrDefault
引入版本：v21.11.0
与 toDateTime 类似，但如果转换失败，则返回默认值：若指定了第三个参数，则返回该参数；否则返回 DateTime 的下界值。
语法
toDateTimeOrDefault(expr[, timezone, default])参数
expr— 返回数值或数值字符串表示形式的表达式。String或(U)Int*或Float*timezone— 可选。时区。Stringdefault— 可选。解析失败时返回的默认值。DateTime
返回值
成功时返回 DateTime 类型的值；否则如果传入了默认值，则返回该默认值；若未传入，则返回 1970-01-01 00:00:00。DateTime
示例
转换成功
SELECT toDateTimeOrDefault('2022-12-30 13:44:17')2022-12-30 13:44:17转换失败
SELECT toDateTimeOrDefault('', 'UTC', CAST('2023-01-01', 'DateTime(\'UTC\')'))2023-01-01 00:00:00toDateTimeOrNull
引入版本：v1.1.0
将输入值转换为 DateTime 类型的值；如果接收到无效参数，则返回 NULL。
与 toDateTime 相同，但在接收到无效参数时会返回 NULL。
整数参数会被解释为 Unix 时间戳；如果超出 DateTime 类型的取值范围，则返回 NULL。
语法
toDateTimeOrNull(x[, timezone])参数
x— 日期时间的字符串表示形式，或整数 Unix 时间戳。String或(U)Int8/16/32/64timezone— 可选。返回值的时区。String
返回值
成功时返回 DateTime 值，否则返回 NULL。DateTime 或 NULL
示例
用法示例
SELECT toDateTimeOrNull('2025-12-30 13:44:17'), toDateTimeOrNull('invalid')┌─toDateTimeOrNull('2025-12-30 13:44:17')─┬─toDateTimeOrNull('invalid')─┐
│ 2025-12-30 13:44:17 │ ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘带有时区的整数参数
SELECT toDateTimeOrNull(1583851242, 'Asia/Shanghai'), toDateTimeOrNull(4294967296)┌─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
示例
使用示例
SELECT toDateTimeOrZero('2025-12-30 13:44:17'), toDateTimeOrZero('invalid')┌─toDateTimeOrZero('2025-12-30 13:44:17')─┬─toDateTimeOrZero('invalid')─┐
│ 2025-12-30 13:44:17 │ 1970-01-01 00:00:00 │
└─────────────────────────────────────────┴─────────────────────────────┘toDecimal128
引入版本：v18.12.0
将输入值转换为标度为 S 的 Decimal(38, S) 类型值。
出错时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值或其字符串表示形式。
不支持的参数：
- Float* 类型的
NaN和Inf值，及其字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toDecimal128('0xc0fe', 1);。
语法
toDecimal128(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 取值范围为 0 到 38 的 scale 参数，用于指定数值的小数部分可以有多少位。UInt8
返回值
返回类型为 Decimal(38, S) 的值 Decimal128(S)
示例
用法示例
SELECT
toDecimal128(99, 1) AS a, toTypeName(a) AS type_a,
toDecimal128(99.67, 2) AS b, toTypeName(b) AS type_b,
toDecimal128('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT VerticalRow 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 字符串表示形式。StringS— 介于 0 到 38 之间的 scale 参数，用于指定数字的小数部分可包含的位数。UInt8default— 可选。如果解析为 Decimal128(S) 类型失败，则返回此默认值。Decimal128(S)
返回值
成功时返回 Decimal(38, S) 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Decimal128(S)
示例
转换成功
SELECT toDecimal128OrDefault(toString(1/42), 18)0.023809523809523808转换失败
SELECT toDecimal128OrDefault('Inf', 0, CAST('-1', 'Decimal128(0)'))-1toDecimal128OrNull
引入版本：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))。
另请参阅：
语法
toDecimal128OrNull(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 到 38 之间的 scale 参数，用于指定数值的小数部分可包含的位数。UInt8
返回值
成功时返回 Decimal(38, S) 值，否则返回 NULL。Decimal128(S) 或 NULL
示例
使用示例
SELECT toDecimal128OrNull('42.7', 2), toDecimal128OrNull('invalid', 2)┌─toDecimal128OrNull('42.7', 2)─┬─toDecimal128OrNull('invalid', 2)─┐
│ 42.7 │ ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘toDecimal128OrZero
引入版本：v20.1.0
将输入值转换为 Decimal(38, S) 类型的值；如果出错，则返回 0。
与 toDecimal128 类似，但在转换出错时返回 0，而不是抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值或其字符串表示形式。
不支持的参数 (返回 0) ：
- Float* 值
NaN和Inf，或其字符串表示形式 (不区分大小写) 。 - 二进制值和十六进制值的字符串表示形式。
语法
toDecimal128OrZero(expr, S)参数
expr— 返回数字或数值字符串表示形式的表达式。ExpressionS— 取值范围为 0 到 38 的 scale 参数，用于指定数字的小数部分最多可以有多少位。UInt8
返回值
成功时返回 Decimal(38, S) 值，否则返回 0。Decimal128(S)
示例
基本用法
SELECT toDecimal128OrZero('42.7', 2), toDecimal128OrZero('invalid', 2)┌─toDecimal128OrZero('42.7', 2)─┬─toDecimal128OrZero('invalid', 2)─┐
│ 42.7 │ 0 │
└───────────────────────────────┴──────────────────────────────────┘toDecimal256
引入版本：v20.8.0
将输入值转换为带有 S 标度的 Decimal(76, S) 类型的值。出错时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值或其字符串表示形式。
不支持的参数：
- Float* 值
NaN和Inf及其字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toDecimal256('0xc0fe', 1);。
语法
toDecimal256(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 到 76 之间的 scale 参数，指定数值的小数部分可包含的位数。UInt8
返回值
返回一个 Decimal(76, S) 类型的值。Decimal256(S)
示例
使用示例
SELECT
toDecimal256(99, 1) AS a, toTypeName(a) AS type_a,
toDecimal256(99.67, 2) AS b, toTypeName(b) AS type_b,
toDecimal256('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT VerticalRow 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表示形式。StringS— 介于 0 到 76 之间的 scale 参数，用于指定数字的小数部分可以有多少位。UInt8default— 可选。如果解析为 Decimal256(S) 类型失败，则返回该默认值。Decimal256(S)
返回值
成功时返回 Decimal(76, S) 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Decimal256(S)
示例
转换成功
SELECT toDecimal256OrDefault(toString(1/42), 76)0.023809523809523808转换失败
SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))-1toDecimal256OrNull
引入版本：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))。
另请参阅：
语法
toDecimal256OrNull(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 取值范围为 0 到 76 的 scale 参数，用于指定数值的小数部分最多可以有多少位。UInt8
返回值
成功时返回 Decimal(76, S) 值，否则返回 NULL。Decimal256(S) 或 NULL
示例
使用示例
SELECT toDecimal256OrNull('42.7', 2), toDecimal256OrNull('invalid', 2)┌─toDecimal256OrNull('42.7', 2)─┬─toDecimal256OrNull('invalid', 2)─┐
│ 42.7 │ ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘toDecimal256OrZero
引入版本：v20.8.0
将输入值转换为 Decimal(76, S) 类型的值，但如果发生错误则返回 0。
与 toDecimal256 类似，但在转换出错时返回 0，而不是抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值或其字符串表示形式。
不支持的参数 (返回 0) ：
- Float* 值
NaN和Inf，以及它们的字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式。
另请参阅：
语法
toDecimal256OrZero(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 到 76 之间的 scale 参数，用于指定数值的小数部分最多可包含多少位数字。UInt8
返回值
成功时返回 Decimal(76, S) 值，否则返回 0。Decimal256(S)
示例
用法示例
SELECT toDecimal256OrZero('42.7', 2), toDecimal256OrZero('invalid', 2)┌─toDecimal256OrZero('42.7', 2)─┬─toDecimal256OrZero('invalid', 2)─┐
│ 42.7 │ 0 │
└───────────────────────────────┴──────────────────────────────────┘toDecimal32
引入版本：v18.12.0
将输入值转换为 Decimal(9, S) 类型、标度为 S 的值。出错时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值或其字符串表示形式。
不支持的参数：
- Float* 值
NaN和Inf及其字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toDecimal32('0xc0fe', 1);。
语法
toDecimal32(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 取值范围为 0 到 9 的 scale 参数，用于指定数值的小数部分可以有多少位。UInt8
返回值
返回类型为 Decimal(9, S) 的值 Decimal32(S)
示例
使用示例
SELECT
toDecimal32(2, 1) AS a, toTypeName(a) AS type_a,
toDecimal32(4.2, 2) AS b, toTypeName(b) AS type_b,
toDecimal32('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT VerticalRow 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表示形式。StringS— 介于 0 到 9 之间的 scale 参数，用于指定数字的小数部分可有多少位。UInt8default— 可选。如果解析为 Decimal32(S) 类型失败，则返回此默认值。Decimal32(S)
返回值
成功时返回 Decimal(9, S) 类型的值；否则，如果传入了默认值则返回该值，未传入则返回 0。Decimal32(S)
示例
转换成功
SELECT toDecimal32OrDefault(toString(0.0001), 5)0.0001转换失败
SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))-1toDecimal32OrNull
引入版本：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))。
另请参见：
语法
toDecimal32OrNull(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 和 9 之间的 scale 参数，指定数值的小数部分可包含的位数。UInt8
返回值
成功时返回 Decimal(9, S) 值，否则返回 NULL。Decimal32(S) 或 NULL
示例
用法示例
SELECT toDecimal32OrNull('42.7', 2), toDecimal32OrNull('invalid', 2)┌─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，以及它们的字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式。
语法
toDecimal32OrZero(expr, S)参数
expr— 返回数值或数值的字符串表示形式的表达式。ExpressionS— 介于 0 到 9 之间的 scale 参数，用于指定数值的小数部分可以有多少位。UInt8
返回值
成功时返回 Decimal(9, S) 值，否则返回 0。Decimal32(S)
示例
用法示例
SELECT toDecimal32OrZero('42.7', 2), toDecimal32OrZero('invalid', 2)┌─toDecimal32OrZero('42.7', 2)─┬─toDecimal32OrZero('invalid', 2)─┐
│ 42.7 │ 0 │
└──────────────────────────────┴─────────────────────────────────┘toDecimal64
引入版本：v18.12.0
将输入值转换为标度为 S 的 Decimal(18, S) 类型值。
出错时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值或其字符串表示形式。
不支持的参数：
- Float* 类型的
NaN和Inf值，或其字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toDecimal64('0xc0fe', 1);。
语法
toDecimal64(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 到 18 之间的 scale 参数，用于指定数值的小数部分可以有多少位。UInt8
返回值
返回一个 Decimal 值。Decimal(18, S)
示例
使用示例
SELECT
toDecimal64(2, 1) AS a, toTypeName(a) AS type_a,
toDecimal64(4.2, 2) AS b, toTypeName(b) AS type_b,
toDecimal64('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT VerticalRow 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字符串表示形式。StringS— 介于 0 到 18 之间的 scale 参数，用于指定数字的小数部分最多可有多少位。UInt8default— 可选。如果无法解析为Decimal64(S)类型，则返回此默认值。Decimal64(S)
返回值
成功时返回 Decimal(18, S) 类型的值；否则，如果传入了默认值则返回默认值，未传入则返回 0。Decimal64(S)
示例
成功转换
SELECT toDecimal64OrDefault(toString(0.0001), 18)0.0001转换失败
SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))-1toDecimal64OrNull
引入版本：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))。
另请参见：
语法
toDecimal64OrNull(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 到 18 之间的 scale 参数，用于指定数值的小数部分可包含的位数。UInt8
返回值
成功时返回 Decimal(18, S) 值，否则返回 NULL。Decimal64(S) 或 NULL
示例
使用示例
SELECT toDecimal64OrNull('42.7', 2), toDecimal64OrNull('invalid', 2)┌─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值，或其字符串表示形式 (不区分大小写) 。 - 二进制和十六进制值的字符串表示形式。
另请参见：
语法
toDecimal64OrZero(expr, S)参数
expr— 返回数值或数值字符串表示形式的表达式。ExpressionS— 介于 0 到 18 之间的 scale 参数，用于指定数值的小数部分最多可以有多少位数字。UInt8
返回值
成功时返回 Decimal(18, S) 值，否则返回 0。Decimal64(S)
示例
使用示例
SELECT toDecimal64OrZero('42.7', 2), toDecimal64OrZero('invalid', 2)┌─toDecimal64OrZero('42.7', 2)─┬─toDecimal64OrZero('invalid', 2)─┐
│ 42.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或Decimalscale— 小数部分显示的位数。必要时会对结果进行四舍五入。UInt8
返回值
返回该数值的 String 表示形式，并且小数位数严格等于指定的位数。String
示例
对数值进行四舍五入并格式化
SELECT toDecimalString(2.1456, 2)┌─toDecimalString(2.1456, 2)─┐
│ 2.15 │
└────────────────────────────┘用零补齐
SELECT toDecimalString(5, 3)┌─toDecimalString(5, 3)─┐
│ 5.000 │
└───────────────────────┘不同数值类型
SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
toDecimalString(CAST(42.7 AS Float32), 4) AS float_val┌─decimal_val─┬─float_val─┐
│ 123.46 │ 42.7000 │
└─────────────┴───────────┘toFixedString
引入版本：v1.1.0
将 String 参数转换为 FixedString(N) 类型 (长度固定为 N 的字符串) 。
如果字符串的字节数小于 N，则会在右侧用空字节填充。 如果字符串的字节数大于 N，则会抛出异常。
语法
toFixedString(s, N)参数
s— 要转换的 String。StringN— 生成的 FixedString 的长度。const UInt*
返回值
返回长度为 N 的 FixedString。FixedString(N)
示例
使用示例
-- The padding is made of null bytes, so the result is shown with `hex`.
SELECT hex(toFixedString('foo', 8)) AS s;┌─s────────────────┐
│ 666F6F0000000000 │
└──────────────────┘toFloat32
引入版本：v1.1.0
将输入值转换为 Float32 类型的值。 如果出错，则会抛出异常。
支持的参数：
- (U)Int* 类型的值。
- (U)Int8/16/32/128/256 的字符串表示形式。
- Float* 类型的值，包括
NaN和Inf。 - Float* 的字符串表示形式，包括
NaN和Inf(不区分大小写) 。
不支持的参数：
- 二进制值和十六进制值的字符串表示形式，例如
SELECT toFloat32('0xc0fe');。
另请参见：
语法
toFloat32(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。Expression
返回值
返回一个 32 位浮点数。Float32
示例
使用示例
SELECT
toFloat32(42.7),
toFloat32('42.7'),
toFloat32('NaN')
FORMAT VerticalRow 1:
──────
toFloat32(42.7): 42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'): nantoFloat32OrDefault
引入版本：v21.11.0
与 toFloat32 类似，此函数会将输入值转换为 Float32 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toFloat32OrDefault(expr[, default])参数
返回值
成功时返回 Float32 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 0。Float32
示例
转换成功
SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))8转换失败
SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))0toFloat32OrNull
引入版本：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');。 - 无效的字符串格式。
另请参见：
语法
toFloat32OrNull(x)参数
x— 数值的字符串表示形式。String
返回值
成功时返回 32 位 Float 值，否则返回 NULL。Float32 或 NULL
示例
使用示例
SELECT
toFloat32OrNull('42.7'),
toFloat32OrNull('NaN'),
toFloat32OrNull('abc')
FORMAT VerticalRow 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'): nan
toFloat32OrNull('abc'): ᴺᵁᴸᴸtoFloat32OrZero
首次引入版本：v1.1.0
将输入值转换为 Float32 类型的值；如果发生错误，则返回 0。
与 toFloat32 类似，但在转换出错时会返回 0，而不是抛出异常。
另请参见：
语法
toFloat32OrZero(x)参数
x— 数字的字符串表示形式。String
返回值
成功时返回 32 位 Float 值，否则返回 0。Float32
示例
用法示例
SELECT
toFloat32OrZero('42.7'),
toFloat32OrZero('abc')
FORMAT VerticalRow 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'): 0toFloat64
引入版本：v1.1.0
将输入值转换为 Float64 类型的值。
发生错误时会抛出异常。
支持的参数：
- (U)Int* 类型的值。
- (U)Int8/16/32/128/256 的字符串表示形式。
- Float* 类型的值，包括
NaN和Inf。 - Float* 类型的字符串表示形式，包括
NaN和Inf(不区分大小写) 。
不支持的参数：
- 二进制和十六进制值的字符串表示形式，例如
SELECT toFloat64('0xc0fe');。
另请参阅：
语法
toFloat64(expr)参数
expr— 返回数字或数字的字符串表示形式的表达式。Expression
返回值
返回 64 位浮点值。Float64
示例
用法示例
SELECT
toFloat64(42.7),
toFloat64('42.7'),
toFloat64('NaN')
FORMAT VerticalRow 1:
──────
toFloat64(42.7): 42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'): nantoFloat64OrDefault
引入版本：v21.11.0
与 toFloat64 类似，此函数会将输入值转换为 Float64 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则发生错误时返回 0。
语法
toFloat64OrDefault(expr[, default])参数
返回值
成功时返回 Float64 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Float64
示例
转换成功
SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))8转换失败
SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))0toFloat64OrNull
引入版本：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');。 - 无效的字符串格式。
另请参阅：
语法
toFloat64OrNull(x)参数
x— 数值的字符串表示形式。String
返回值
成功时返回 64 位 Float 值，否则返回 NULL。 Float64 或 NULL
示例
使用示例
SELECT
toFloat64OrNull('42.7'),
toFloat64OrNull('NaN'),
toFloat64OrNull('abc')
FORMAT VerticalRow 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'): nan
toFloat64OrNull('abc'): ᴺᵁᴸᴸtoFloat64OrZero
引入于：v1.1.0
将输入值转换为 Float64 类型的值；如果发生错误，则返回 0。
与 toFloat64 类似，但在转换错误时会返回 0，而不是抛出异常。
另请参见：
语法
toFloat64OrZero(x)参数
x— 数值的字符串表示形式。String
返回值
成功时返回 64 位浮点值，否则返回 0。Float64
示例
使用示例
SELECT
toFloat64OrZero('42.7'),
toFloat64OrZero('abc')
FORMAT Vertical第 1 行：
──────
toFloat64OrZero('42.7'): 42.7
toFloat64OrZero('abc'): 0toInt128
首次引入于：v1.1.0
将输入值转换为 Int128 类型的值。 出错时会抛出异常。 该函数采用向零舍入，也就是说会截断数字的小数位。
支持的参数：
(U)Int*类型的值或其字符串表示形式。Float*类型的值。
不支持的参数：
Float*值的字符串表示形式，包括NaN和Inf。- 二进制和十六进制值的字符串表示形式，例如
SELECT toInt128('0xc0fe');。
另请参见：
语法
toInt128(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。Expression
返回值
返回一个 128 位整数值。Int128
示例
用法示例
SELECT
toInt128(-128),
toInt128(-128.8),
toInt128('-128')
FORMAT VerticalRow 1:
──────
toInt128(-128): -128
toInt128(-128.8): -128
toInt128('-128'): -128toInt128OrDefault
引入版本：v21.11.0
与 toInt128 类似，该函数会将输入值转换为 Int128 类型的值，但在发生错误时会返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toInt128OrDefault(expr[, default])参数
返回值
成功时返回 Int128 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 0。Int128
示例
成功转换
SELECT toInt128OrDefault('-128', CAST('-1', 'Int128'))-128转换失败
SELECT toInt128OrDefault('abc', CAST('-1', 'Int128'))-1toInt128OrNull
Introduced in: v20.8.0
与 toInt128 类似，此函数会将输入值转换为 Int128 类型的值，但在出错时返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt128OrNull('0xc0fe');。
See also:
语法
toInt128OrNull(x)参数
x— 数字的字符串表示形式。String
返回值
返回 Int128 类型的值；如果转换失败，则返回 NULL。Int128 或 NULL
示例
使用示例
SELECT
toInt128OrNull('-128'),
toInt128OrNull('abc')
FORMAT VerticalRow 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'): ᴺᵁᴸᴸtoInt128OrZero
引入版本：v20.8.0
将输入值转换为 Int128 类型，但如果发生错误则返回 0。
与 toInt128 类似，但返回 0 而不是抛出异常。
另请参见：
语法
toInt128OrZero(x)参数
返回值
返回转换后的输入值；如果转换失败，则返回 0。Int128
示例
使用示例
SELECT toInt128OrZero('123')123转换失败时返回 0
SELECT toInt128OrZero('abc')0toInt16
引入于：v1.1.0
将输入值转换为 Int16 类型的值。
发生错误时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 类型值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt16('0xc0fe');。
另请参阅：
语法
toInt16(expr)参数
expr— 返回数值或该数值的字符串表示形式的表达式。Expression
返回值
返回一个 16 位整数值。Int16
示例
用法示例
SELECT
toInt16(-16),
toInt16(-16.16),
toInt16('-16')
FORMAT VerticalRow 1:
──────
toInt16(-16): -16
toInt16(-16.16): -16
toInt16('-16'): -16toInt16OrDefault
引入版本：v21.11.0
与 toInt16 类似，此函数将输入值转换为 Int16 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toInt16OrDefault(expr[, default])参数
返回值
成功时返回 Int16 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Int16
示例
转换成功
SELECT toInt16OrDefault('-16', CAST('-1', 'Int16'))-16转换失败
SELECT toInt16OrDefault('abc', CAST('-1', 'Int16'))-1toInt16OrNull
引入版本：v1.1.0
与 toInt16 类似，此函数将输入值转换为 Int16 类型的值，但如果发生错误，则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt16OrNull('0xc0fe');。
另请参见：
语法
toInt16OrNull(x)参数
x— 数值的字符串表示形式。String
返回值
返回 Int16 类型的值；如果转换失败，则返回 NULL。Int16 或 NULL
示例
用法示例
SELECT
toInt16OrNull('-16'),
toInt16OrNull('abc')
FORMAT VerticalRow 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): ᴺᵁᴸᴸtoInt16OrZero
引入版本：v1.1.0
与 toInt16 类似，此函数会将输入值转换为 Int16 类型的值，但在发生错误时返回 0。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 0) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt16OrZero('0xc0fe');。
另请参见：
语法
toInt16OrZero(x)参数
x— 数值的字符串表示形式。String
返回值
返回 Int16 类型的值；如果转换失败，则返回 0。Int16
示例
使用示例
SELECT
toInt16OrZero('16'),
toInt16OrZero('abc')
FORMAT VerticalRow 1:
──────
toInt16OrZero('16'): 16
toInt16OrZero('abc'): 0toInt256
引入版本：v1.1.0
将输入值转换为 Int256 类型的值。 如果发生错误，会抛出异常。 该函数采用向零舍入，也就是说会截去数字的小数位。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt256('0xc0fe');。
另请参见：
语法
toInt256(expr)参数
expr— 返回数字或数字的字符串表示形式的表达式。表达式
返回值
返回一个 256 位整数值。Int256
示例
使用示例
SELECT
toInt256(-256),
toInt256(-256.256),
toInt256('-256')
FORMAT VerticalRow 1:
──────
toInt256(-256): -256
toInt256(-256.256): -256
toInt256('-256'): -256toInt256OrDefault
引入版本：v21.11.0
与 toInt256 类似，此函数会将输入值转换为 Int256 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toInt256OrDefault(expr[, default])参数
返回值
成功时返回 Int256 类型的值；否则，如果传入了默认值，则返回该默认值；若未传入，则返回 0。Int256
示例
转换成功
SELECT toInt256OrDefault('-256', CAST('-1', 'Int256'))-256转换失败
SELECT toInt256OrDefault('abc', CAST('-1', 'Int256'))-1toInt256OrNull
引入版本：v20.8.0
与 toInt256 类似，此函数会将输入值转换为 Int256 类型的值，但如果发生错误，则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL)：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt256OrNull('0xc0fe');。
另请参阅：
语法
toInt256OrNull(x)参数
x— 数字的字符串表示形式。String
返回值
返回 Int256 类型的值；如果转换失败，则返回 NULL。Int256 或 NULL
示例
使用示例
SELECT
toInt256OrNull('-256'),
toInt256OrNull('abc')
FORMAT VerticalRow 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'): ᴺᵁᴸᴸtoInt256OrZero
引入版本：v20.8.0
将输入值转换为 Int256 类型；如果发生错误，则返回 0。
与 toInt256 类似，但会返回 0，而不是抛出异常。
另请参见：
语法
toInt256OrZero(x)参数
返回值
返回转换后的输入值；如果转换失败，则返回 0。(Int256)
示例
用法示例
SELECT toInt256OrZero('123')123转换失败时返回 0
SELECT toInt256OrZero('abc')0toInt32
Introduced in: v1.1.0
将输入值转换为 Int32 类型的值。
出错时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 类型值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt32('0xc0fe');。
See also:
Syntax
toInt32(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。表达式
返回值
返回一个 32 位整数。Int32
示例
用法示例
SELECT
toInt32(-32),
toInt32(-32.32),
toInt32('-32')
FORMAT VerticalRow 1:
──────
toInt32(-32): -32
toInt32(-32.32): -32
toInt32('-32'): -32toInt32OrDefault
引入版本：v21.11.0
与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toInt32OrDefault(expr[, default])参数
返回值
成功时返回 Int32 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Int32
示例
转换成功
SELECT toInt32OrDefault('-32', CAST('-1', 'Int32'))-32转换失败
SELECT toInt32OrDefault('abc', CAST('-1', 'Int32'))-1toInt32OrNull
引入版本：v1.1.0
与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值，但如果发生错误则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL)：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt32OrNull('0xc0fe');。
另请参阅：
语法
toInt32OrNull(x)参数
x— 数字的字符串表示形式。String
返回值
返回 Int32 类型的值；如果转换失败，则返回 NULL。Int32 或 NULL
示例
用法示例
SELECT
toInt32OrNull('-32'),
toInt32OrNull('abc')
FORMAT VerticalRow 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): ᴺᵁᴸᴸtoInt32OrZero
引入版本：v1.1.0
与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值；如果发生错误，则返回 0。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 0)：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt32OrZero('0xc0fe');。
另请参阅：
语法
toInt32OrZero(x)参数
x— 数字的字符串表示形式。String
返回值
返回类型为 Int32 的值；如果转换失败，则返回 0。Int32
示例
使用示例
SELECT
toInt32OrZero('32'),
toInt32OrZero('abc')
FORMAT VerticalRow 1:
──────
toInt32OrZero('32'): 32
toInt32OrZero('abc'): 0toInt64
引入版本：v1.1.0
将输入值转换为 Int64 类型的值。
如果发生错误，则会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt64('0xc0fe');。
另请参见：
语法
toInt64(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。支持：类型为 (U)Int* 的值或其字符串表示形式，以及类型为 Float* 的值。不支持：Float* 值的字符串表示形式 (包括 NaN 和 Inf) ，以及二进制和十六进制值的字符串表示形式。表达式
返回值
返回一个 64 位整数值。Int64
示例
使用示例
SELECT
toInt64(-64),
toInt64(-64.64),
toInt64('-64')
FORMAT VerticalRow 1:
──────
toInt64(-64): -64
toInt64(-64.64): -64
toInt64('-64'): -64toInt64OrDefault
引入版本：v21.11.0
与 toInt64 类似，此函数会将输入值转换为 Int64 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则发生错误时返回 0。
语法
toInt64OrDefault(expr[, default])参数
返回值
成功时返回 Int64 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。Int64
示例
成功转换
SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))-64转换失败
SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))-1toInt64OrNull
引入版本：v1.1.0
与 toInt64 类似，此函数将输入值转换为 Int64 类型的值，但如果发生错误，则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt64OrNull('0xc0fe');。
另请参见：
语法
toInt64OrNull(x)参数
x— 数值的字符串表示形式。String
返回值
返回 Int64 类型的值；如果转换失败，则返回 NULL。Int64 或 NULL
示例
使用示例
SELECT
toInt64OrNull('-64'),
toInt64OrNull('abc')
FORMAT VerticalRow 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): ᴺᵁᴸᴸtoInt64OrZero
引入版本：v1.1.0
将输入值转换为 Int64 类型，但如果发生错误则返回 0。
与 toInt64 类似，不过它会返回 0，而不是抛出异常。
另请参见：
语法
toInt64OrZero(x)参数
返回值
返回转换后的输入值；如果转换失败，则返回 0。Int64
示例
使用示例
SELECT toInt64OrZero('123')123转换失败则返回零
SELECT toInt64OrZero('abc')0toInt8
引入版本：v1.1.0
将输入值转换为 Int8 类型的值。
出错时会抛出异常。
支持的参数：
(U)Int*类型的值或其字符串表示形式。Float*类型的值。
不支持的参数：
Float*值的字符串表示形式，包括NaN和Inf。- 二进制和十六进制值的字符串表示形式，例如
SELECT toInt8('0xc0fe');。
另请参见：
语法
toInt8(expr)参数
expr— 返回数值或数值的字符串表示形式的表达式。表达式
返回值
返回一个 8 位整数值。Int8
示例
使用示例
SELECT
toInt8(-8),
toInt8(-8.8),
toInt8('-8')
FORMAT VerticalRow 1:
──────
toInt8(-8): -8
toInt8(-8.8): -8
toInt8('-8'): -8toInt8OrDefault
首次引入版本：v21.11.0
与 toInt8 类似，此函数会将输入值转换为 Int8 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toInt8OrDefault(expr[, default])参数
返回值
如果成功，则返回 Int8 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 0。Int8
示例
转换成功
SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))-8转换失败
SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))-1toInt8OrNull
引入版本：v1.1.0
与 toInt8 类似，此函数会将输入值转换为 Int8 类型的值，但如果发生错误，则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制值和十六进制值的字符串表示形式，例如
SELECT toInt8OrNull('0xc0fe');。
另请参阅：
语法
toInt8OrNull(x)参数
x— 数值的字符串表示形式。String
返回值
返回 Int8 类型的值；如果转换失败，则返回 NULL。Int8 或 NULL
示例
使用示例
SELECT
toInt8OrNull('-8'),
toInt8OrNull('abc')
FORMAT VerticalRow 1:
──────
toInt8OrNull('-8'): -8
toInt8OrNull('abc'): ᴺᵁᴸᴸtoInt8OrZero
版本引入：v1.1.0
与 toInt8 类似，此函数会将输入值转换为 Int8 类型的值，但如果出错则返回 0。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 0)：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toInt8OrZero('0xc0fe');。
另请参见：
语法
toInt8OrZero(x)参数
x— 数值的字符串表示形式。String
返回值
返回 Int8 类型的值；如果转换失败，则返回 0。Int8
示例
使用示例
SELECT
toInt8OrZero('8'),
toInt8OrZero('abc')
FORMAT VerticalRow 1:
──────
toInt8OrZero('8'): 8
toInt8OrZero('abc'): 0toInterval
引入版本：v25.4.0
根据数值和单位字符串创建一个 Interval 值。
该函数提供了一种统一的方法：通过将单位指定为字符串参数，用同一个函数创建不同类型的时间间隔 (秒、分钟、小时、天、周、月、季度、年) 。 单位字符串不区分大小写。
这等同于调用 toIntervalSecond、toIntervalMinute、toIntervalDay 等特定类型的函数，
但允许通过字符串参数动态指定单位。
语法
toInterval(value, unit)参数
value— 表示单位数量的数值，可为任意数值类型。Int8或Int16或Int32或Int64或UInt8或UInt16或UInt32或UInt64或Float32或Float64unit— 时间单位。必须为常量字符串。有效值：'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
示例
创建不同单位的时间间隔
SELECT
toInterval(5, 'second') AS seconds,
toInterval(3, 'day') AS days,
toInterval(2, 'month') AS months┌─seconds─┬─days─┬─months─┐
│ 5 │ 3 │ 2 │
└─────────┴──────┴────────┘在日期算术中使用时间间隔
SELECT
now() AS current_time,
now() + toInterval(1, 'hour') AS one_hour_later,
now() - toInterval(7, 'day') AS week_ago┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00 │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘动态生成时间间隔
SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘toIntervalDay
在 v1.1.0 中引入
返回一个由 n 天组成、数据类型为 IntervalDay 的时间间隔。
语法
toIntervalDay(n)参数
返回值
返回 n 天的时间间隔。Interval
示例
使用示例
WITH
toDate('2025-06-15') AS date,
toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result┌─────result─┐
│ 2025-06-20 │
└────────────┘toIntervalHour
在 v1.1.0 中引入
返回一个表示 n 小时的时间间隔，数据类型为 IntervalHour。
语法
toIntervalHour(n)参数
返回值
返回一个 n 小时的时间间隔。Interval
示例
用法示例
WITH
toDate('2025-06-15') AS date,
toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘toIntervalMicrosecond
引入版本：v22.6.0
返回一个由 n 微秒组成的时间间隔，数据类型为 IntervalMicrosecond。
语法
toIntervalMicrosecond(n)参数
返回值
返回由 n 微秒构成的时间间隔。Interval
示例
使用示例
WITH
toDateTime('2025-06-15') AS date,
toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘toIntervalMillisecond
引入版本：v22.6.0
返回一个 n 毫秒的时间间隔，数据类型为 IntervalMillisecond。
语法
toIntervalMillisecond(n)参数
返回值
返回一个包含 n 毫秒的时间间隔。Interval
示例
使用示例
WITH
toDateTime('2025-06-15') AS date,
toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘toIntervalMinute
引入版本：v1.1.0
返回一个表示 n 分钟的时间间隔，数据类型为 IntervalMinute。
语法
toIntervalMinute(n)参数
返回值
返回 n 分钟的时间间隔。Interval
示例
用法示例
WITH
toDate('2025-06-15') AS date,
toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘toIntervalMonth
引入版本：v1.1.0
返回一个 n 个月的时间间隔，数据类型为 IntervalMonth。
语法
toIntervalMonth(n)参数
返回值
返回 n 个月的时间间隔。Interval
示例
使用示例
WITH
toDate('2025-06-15') AS date,
toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result┌─────result─┐
│ 2025-07-15 │
└────────────┘toIntervalNanosecond
引入版本：v22.6.0
返回一个 n 纳秒的时间间隔，数据类型为 IntervalNanosecond。
语法
toIntervalNanosecond(n)参数
返回值
返回 n 纳秒的时间间隔。Interval
示例
使用示例
WITH
toDateTime('2025-06-15') AS date,
toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘toIntervalQuarter
在 v1.1.0 中引入
返回一个由 n 个季度组成、数据类型为 IntervalQuarter 的时间间隔。
语法
toIntervalQuarter(n)参数
返回值
返回 n 个季度的时间间隔。Interval
示例
使用示例
WITH
toDate('2025-06-15') AS date,
toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result┌─────result─┐
│ 2025-09-15 │
└────────────┘toIntervalSecond
引入版本：v1.1.0
返回一个由 n 秒构成、数据类型为 IntervalSecond 的时间间隔。
语法
toIntervalSecond(n)参数
返回值
返回 n 秒的时间间隔。Interval
示例
使用示例
WITH
toDate('2025-06-15') AS date,
toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘toIntervalWeek
引入版本：v1.1.0
返回一个表示 n 周的时间间隔，数据类型为 IntervalWeek。
语法
toIntervalWeek(n)参数
返回值
返回 n 周的时间间隔。Interval
示例
用法示例
WITH
toDate('2025-06-15') AS date,
toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result┌─────result─┐
│ 2025-06-22 │
└────────────┘toIntervalYear
引入版本：v1.1.0
返回一个表示 n 年的时间间隔，数据类型为 IntervalYear。
语法
toIntervalYear(n)参数
返回值
返回一个 n 年的时间间隔。Interval
示例
使用示例
WITH
toDate('2024-06-15') AS date,
toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result┌─────result─┐
│ 2025-06-15 │
└────────────┘toLowCardinality
引入版本：v18.12.0
将输入参数转换为相同数据类型的 LowCardinality 版本。
语法
toLowCardinality(expr)参数
返回值
返回转换为 LowCardinality 数据类型后的输入值。LowCardinality
示例
使用示例
SELECT toLowCardinality('1')┌─toLowCardinality('1')─┐
│ 1 │
└───────────────────────┘toString
引入版本：v1.1.0
将值转换为其字符串表示形式。 对于 DateTime 类型的参数，该函数还可以接受第二个 String 类型参数，用于指定时区名称。
语法
toString(value[, timezone])参数
返回值
返回输入值的字符串表示形式。String
示例
使用示例
SELECT
now() AS ts,
time_zone,
toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast │ 2023-09-08 20:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘toStringCutToZero
引入版本：v1.1.0
接受一个 String 或 FixedString 类型的参数，并返回一个 String，该 String 是在第一个空字节处截断后的原始字符串副本。
空字节 (\0) 被视为字符串终止符。 当空字节用于标记有效内容的结尾时，此函数可用于处理 C 风格字符串或二进制数据。
语法
toStringCutToZero(s)参数
s— 要处理的 String 或 FixedString。String或FixedString
返回值
返回一个 String，包含第一个空字节之前的字符。String
示例
使用示例
SELECT
toStringCutToZero('hello'),
toStringCutToZero('hello\0world')┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\0world')─┐
│ hello │ hello │
└────────────────────────────┴───────────────────────────────────┘toTime
引入版本：v25.5.0
将输入值转换为 Time 类型。
支持从 String、FixedString、DateTime、DateTime64 或表示自午夜起经过秒数的数值类型进行转换。
超出该类型范围的数值 (-999:59:59 至 999:59:59，即 -3599999 至 3599999 秒) 将被限制在范围边界内；非有限浮点值 (NaN、inf、-inf) 无法转换，并会引发异常。
语法
toTime(x)参数
x— 要转换的输入值。String或FixedString或DateTime或DateTime64或(U)Int*或BFloat16或Float*
返回值
返回转换后的值。Time
示例
DateTime64 转换为 Time
SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime64('2025-04-15 14:30:25.123', 3))14:30:25DateTime 转换为 Time
SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime('2025-04-15 14:30:25'))14:30:25将整数 (表示自纪元以来的秒数) 转换为时间
SET enable_time_time64_type = 1;
SET use_legacy_to_time = 0;
SELECT toTime(toDateTime(52225, 'UTC'))14:30:25toTime64
引入版本：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
SET enable_time_time64_type = 1;
SELECT toTime64('14:30:25.123456', 6)14:30:25.123456DateTime64 转换为 Time64
SET enable_time_time64_type = 1;
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6), 6)14:30:25.123456Float (自午夜起的秒数) 转换为 Time64
SET enable_time_time64_type = 1;
SELECT toTime64(52225.123456, 6)14:30:25.123456toTime64OrNull
引入版本：v25.6.0
将输入值转换为 Time64 类型的值；如果发生错误，则返回 NULL。
与 toTime64 类似，但在转换出错时会返回 NULL，而不是抛出异常。
另请参见：
语法
toTime64OrNull(x)参数
x— 具有子秒级精度的时间字符串表示形式。String
返回值
成功时返回 Time64 值，否则返回 NULL。Time64 或 NULL
示例
用法示例
SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│ 12:30:45.123 │ ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘toTime64OrZero
引入版本：v25.6.0
将输入值转换为 Time64 类型的值；如果发生错误，则返回 00:00:00.000。
与 toTime64 类似，但在转换出错时会返回 00:00:00.000，而不是抛出异常。
语法
toTime64OrZero(x)参数
x— 具有子秒级精度的时间字符串表示形式。String
返回值
如果成功，返回 Time64 值；否则返回 00:00:00.000。Time64
示例
用法示例
SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│ 12:30:45.123 │ 00:00:00.000 │
└────────────────────────────────┴───────────────────────────┘toTimeOrNull
引入版本：v25.5.0
将输入值转换为 Time 类型的值；如果发生错误，则返回 NULL。
与 toTime 类似，但在转换出错时会返回 NULL，而不是抛出异常。
另请参见：
语法
toTimeOrNull(x)参数
x— 时间的字符串表示形式。String
返回值
成功时返回 Time 值，否则返回 NULL。Time 或 NULL
示例
使用示例
SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│ 12:30:45 │ ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘toTimeOrZero
Introduced in: v25.5.0
将输入值转换为 Time 类型的值；如果出错，则返回 00:00:00。
与 toTime 类似，但在转换出错时会返回 00:00:00，而不是抛出异常。
Syntax
toTimeOrZero(x)参数
x— 时间的字符串表示形式。String
返回值
如果成功，返回 Time 值；否则返回 00:00:00。Time
示例
使用示例
SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│ 12:30:45 │ 00:00:00 │
└──────────────────────────┴─────────────────────────┘toUInt128
引入版本：v1.1.0
将输入值转换为 UInt128 类型的值。
出错时会抛出异常。
该函数采用向零舍入，即会截断数字的小数位。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt128('0xc0fe');。
另请参见：
语法
toUInt128(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。表达式
返回值
返回一个 128 位无符号整数值。UInt128
示例
用法示例
SELECT
toUInt128(128),
toUInt128(128.8),
toUInt128('128')
FORMAT VerticalRow 1:
──────
toUInt128(128): 128
toUInt128(128.8): 128
toUInt128('128'): 128toUInt128OrDefault
引入版本：v21.11.0
与 toUInt128 类似，此函数会将输入值转换为 UInt128 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toUInt128OrDefault(expr[, default])参数
返回值
成功时返回 UInt128 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。UInt128
示例
转换成功
SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))128转换失败
SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))0toUInt128OrNull
引入版本：v21.6.0
与 toUInt128 类似，此函数将输入值转换为 UInt128 类型的值，但在发生错误时会返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt128OrNull('0xc0fe');。
另请参阅：
语法
toUInt128OrNull(x)参数
x— 数字的字符串表示形式。String
返回值
返回 UInt128 类型的值；如果转换失败，则返回 NULL。UInt128 或 NULL
示例
使用示例
SELECT
toUInt128OrNull('128'),
toUInt128OrNull('abc')
FORMAT VerticalRow 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): ᴺᵁᴸᴸtoUInt128OrZero
引入版本：v1.1.0
与 toUInt128 类似，此函数会将输入值转换为 UInt128 类型的值，但如果发生错误则返回 0。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 0)：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt128OrZero('0xc0fe');。
另请参见：
语法
toUInt128OrZero(x)参数
x— 数字的字符串表示形式。String
返回值
返回 UInt128 类型的值；如果转换失败，则返回 0。UInt128
示例
使用示例
SELECT
toUInt128OrZero('128'),
toUInt128OrZero('abc')
FORMAT VerticalRow 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0toUInt16
引入版本：v1.1.0
将输入值转换为 UInt16 类型的值。
发生错误时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt16('0xc0fe');。
另请参见：
语法
toUInt16(expr)参数
expr— 返回数值或数值的字符串表示形式的表达式。表达式
返回值
返回一个 16 位无符号整数值。UInt16
示例
使用示例
SELECT
toUInt16(16),
toUInt16(16.16),
toUInt16('16')
FORMAT VerticalRow 1:
──────
toUInt16(16): 16
toUInt16(16.16): 16
toUInt16('16'): 16toUInt16OrDefault
Introduced in：v21.11.0
与 toUInt16 类似，此函数会将输入值转换为 UInt16 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
Syntax
toUInt16OrDefault(expr[, default])参数
返回值
成功时返回 UInt16 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。UInt16
示例
转换成功
SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))16转换失败
SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))0toUInt16OrNull
Introduced in: v1.1.0
与 toUInt16 类似，此函数会将输入值转换为 UInt16 类型的值，但如果发生错误则返回 NULL。
支持的参数：
- (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt16OrNull('0xc0fe');。
See also:
Syntax
toUInt16OrNull(x)参数
x— 数字的字符串表示形式。String
返回值
返回 UInt16 类型的值；如果转换失败，则返回 NULL。UInt16 或 NULL
示例
使用示例
SELECT
toUInt16OrNull('16'),
toUInt16OrNull('abc')
FORMAT VerticalRow 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');。
另请参阅：
语法
toUInt16OrZero(x)参数
x— 数值的字符串表示形式。String
返回值
返回 UInt16 类型的值；如果转换失败，则返回 0。UInt16
示例
使用示例
SELECT
toUInt16OrZero('16'),
toUInt16OrZero('abc')
FORMAT VerticalRow 1:
──────
toUInt16OrZero('16'): 16
toUInt16OrZero('abc'): 0toUInt256
在 v1.1.0 中引入
将输入值转换为 UInt256 类型的值。 出错时会抛出异常。 该函数采用向零舍入，也就是说会截断数字的小数位。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt256('0xc0fe');。
另请参见：
语法
toUInt256(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。Expression
返回值
返回一个 256 位无符号整数。UInt256
示例
使用示例
SELECT
toUInt256(256),
toUInt256(256.256),
toUInt256('256')
FORMAT VerticalRow 1:
──────
toUInt256(256): 256
toUInt256(256.256): 256
toUInt256('256'): 256toUInt256OrDefault
引入版本：v21.11.0
与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则在发生错误时返回 0。
语法
toUInt256OrDefault(expr[, default])参数
返回值
成功时返回 UInt256 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。UInt256
示例
转换成功
SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))0转换失败
SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))0toUInt256OrNull
引入版本：v20.8.0
与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制值和十六进制值的字符串表示形式，例如
SELECT toUInt256OrNull('0xc0fe');。
另请参阅：
语法
toUInt256OrNull(x)参数
x— 数字的字符串表示形式。String
返回值
返回 UInt256 类型的值；如果转换失败，则返回 NULL。UInt256 或 NULL
示例
使用示例
SELECT
toUInt256OrNull('256'),
toUInt256OrNull('abc')
FORMAT VerticalRow 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): ᴺᵁᴸᴸtoUInt256OrZero
引入于：v20.8.0
与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回 0。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 0) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt256OrZero('0xc0fe');。
另请参见：
语法
toUInt256OrZero(x)参数
x— 字符串表示形式。String
返回值
返回 UInt256 类型的值；如果转换失败，则返回 0。UInt256
示例
使用示例
SELECT
toUInt256OrZero('256'),
toUInt256OrZero('abc')
FORMAT VerticalRow 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0toUInt32
引入于：v1.1.0
将输入值转换为 UInt32 类型的值。
如果出错，则会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制值和十六进制值的字符串表示形式，例如
SELECT toUInt32('0xc0fe');。
另请参见：
语法
toUInt32(expr)参数
expr— 返回数值或数值字符串表示形式的表达式。Expression
返回值
返回一个 32 位无符号整数。UInt32
示例
用法示例
SELECT
toUInt32(32),
toUInt32(32.32),
toUInt32('32')
FORMAT VerticalRow 1:
──────
toUInt32(32): 32
toUInt32(32.32): 32
toUInt32('32'): 32toUInt32OrDefault
Introduced in: v21.11.0
与 toUInt32 类似，此函数会将输入值转换为 UInt32 类型的值，但发生错误时会返回默认值。
如果未传入 default 值，则发生错误时返回 0。
Syntax
toUInt32OrDefault(expr[, default])参数
返回值
成功时返回 UInt32 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。UInt32
示例
转换成功
SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))32转换失败
SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))0toUInt32OrNull
引入于：v1.1.0
与 toUInt32 类似，此函数会将输入值转换为 UInt32 类型的值，但如果发生错误，则返回 NULL。
支持的参数：
- (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt32OrNull('0xc0fe');。
另请参见：
语法
toUInt32OrNull(x)参数
x— 字符串表示形式。String
返回值
返回 UInt32 类型的值；如果转换失败，则返回 NULL。UInt32 或 NULL
示例
使用示例
SELECT
toUInt32OrNull('32'),
toUInt32OrNull('abc')
FORMAT VerticalRow 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');。
另请参见：
语法
toUInt32OrZero(x)参数
x— 字符串表示形式。String
返回值
返回 UInt32 类型的值；如果转换失败，则返回 0。UInt32
示例
使用示例
SELECT
toUInt32OrZero('32'),
toUInt32OrZero('abc')
FORMAT VerticalRow 1:
──────
toUInt32OrZero('32'): 32
toUInt32OrZero('abc'): 0toUInt64
引入版本：v1.1.0
将输入值转换为 UInt64 类型的值。
发生错误时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的类型：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt64('0xc0fe');。
另请参见：
语法
toUInt64(expr)参数
expr— 返回数字或数字的字符串表示形式的表达式。Expression
返回值
返回一个 64 位无符号整数值。UInt64
示例
使用示例
SELECT
toUInt64(64),
toUInt64(64.64),
toUInt64('64')
FORMAT VerticalRow 1:
──────
toUInt64(64): 64
toUInt64(64.64): 64
toUInt64('64'): 64toUInt64OrDefault
首次引入版本：v21.11.0
与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则发生错误时返回 0。
语法
toUInt64OrDefault(expr[, default])参数
返回值
如果转换成功，返回 UInt64 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。UInt64
示例
转换成功
SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))64转换失败
SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))0toUInt64OrNull
引入于：v1.1.0
与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误则返回 NULL。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt64OrNull('0xc0fe');。
另请参见：
语法
toUInt64OrNull(x)参数
x— 字符串表示形式。String
返回值
返回 UInt64 类型的值；如果转换失败，则返回 NULL。UInt64 或 NULL
示例
使用示例
SELECT
toUInt64OrNull('64'),
toUInt64OrNull('abc')
FORMAT VerticalRow 1:
──────
toUInt64OrNull('64'): 64
toUInt64OrNull('abc'): ᴺᵁᴸᴸtoUInt64OrZero
引入版本：v1.1.0
与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误，则返回 0。
支持的参数：
- (U)Int* 的字符串表示形式。
不支持的参数 (返回 0) ：
- Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt64OrZero('0xc0fe');。
另请参见：
语法
toUInt64OrZero(x)参数
x— 数字的字符串表示形式。String
返回值
返回 UInt64 类型的值；如果转换失败，则返回 0。UInt64
示例
使用示例
SELECT
toUInt64OrZero('64'),
toUInt64OrZero('abc')
FORMAT VerticalRow 1:
──────
toUInt64OrZero('64'): 64
toUInt64OrZero('abc'): 0toUInt8
Introduced in: v1.1.0
将输入值转换为 UInt8 类型的值。
发生错误时会抛出异常。
支持的参数：
- (U)Int* 类型的值或其字符串表示形式。
- Float* 类型的值。
不支持的参数：
- Float* 类型值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt8('0xc0fe');。
另请参见：
语法
toUInt8(expr)参数
expr— 返回数字或数字的字符串表示形式的表达式。Expression
返回值
返回 8 位无符号整数值。UInt8
示例
使用示例
SELECT
toUInt8(8),
toUInt8(8.8),
toUInt8('8')
FORMAT VerticalRow 1:
──────
toUInt8(8): 8
toUInt8(8.8): 8
toUInt8('8'): 8toUInt8OrDefault
Introduced in：v21.11.0
与 toUInt8 类似，此函数会将输入值转换为 UInt8 类型的值，但如果发生错误，则返回默认值。
如果未传入 default 值，则发生错误时返回 0。
Syntax
toUInt8OrDefault(expr[, default])参数
返回值
成功时返回 UInt8 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 0。UInt8
示例
转换成功
SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))8转换失败
SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))0toUInt8OrNull
引入版本：v1.1.0
与 toUInt8 类似，此函数将输入值转换为 UInt8 类型的值，但在出错时返回 NULL。
支持的参数：
- (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 NULL) ：
- 普通 Float* 值的字符串表示形式，包括
NaN和Inf。 - 二进制和十六进制值的字符串表示形式，例如
SELECT toUInt8OrNull('0xc0fe');。
另请参见：
语法
toUInt8OrNull(x)参数
x— 字符串表示形式。String
返回值
返回类型为 UInt8 的值；如果转换失败，则返回 NULL。UInt8 或 NULL
示例
使用示例
SELECT
toUInt8OrNull('42'),
toUInt8OrNull('abc')
FORMAT VerticalRow 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');。
另请参阅：
语法
toUInt8OrZero(x)参数
x— 字符串表示形式。String
返回值
返回 UInt8 类型的值；如果转换失败，则返回 0。UInt8
示例
用法示例
SELECT
toUInt8OrZero('-8'),
toUInt8OrZero('abc')
FORMAT VerticalRow 1:
──────
toUInt8OrZero('-8'): 0
toUInt8OrZero('abc'): 0toUUID
引入版本：v1.1.0
将 String 类型的值转换为 UUID 值。
语法
toUUID(string)参数
string— 字符串形式的 UUID。String或FixedString
返回值
根据 UUID 的字符串表示形式返回一个 UUID。UUID
示例
使用示例
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid┌─uuid─────────────────────────────────┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘toUUIDOrZero
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
示例
使用示例
SELECT
toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
toUUIDOrZero('invalid-uuid') AS invalid_uuid┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘toUnixTimestamp64Micro
引入版本：v20.5.0
将 DateTime64 转换为具有固定微秒精度的 Int64 值。
输入值会根据其精度相应地进行放大或缩小。
语法
toUnixTimestamp64Micro(value)参数
value— 任意精度的 DateTime64 类型值。DateTime64
返回值
返回以微秒为单位的 Unix 时间戳。Int64
示例
使用示例
WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);┌─toUnixTimestamp64Micro(dt64)─┐
│ 1739489491011123 │
└──────────────────────────────┘toUnixTimestamp64Milli
引入版本：v20.5.0
将 DateTime64 转换为具有固定毫秒精度的 Int64 值。
输入值会根据其精度按相应比例放大或缩小。
语法
toUnixTimestamp64Milli(value)参数
value— 具有任意精度的 DateTime64 值。DateTime64
返回值
返回一个以毫秒为单位的 Unix 时间戳。Int64
示例
用法示例
WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);┌─toUnixTimestamp64Milli(dt64)─┐
│ 1739489491011 │
└──────────────────────────────┘toUnixTimestamp64Nano
引入版本：v20.5.0
将 DateTime64 转换为具有固定纳秒精度的 Int64 值。
输入值会根据其精度相应放大或缩小。
语法
toUnixTimestamp64Nano(value)参数
value— 任意精度的 DateTime64 值。DateTime64
返回值
返回以纳秒为单位的 Unix 时间戳。Int64
示例
使用示例
WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);┌─toUnixTimestamp64Nano(dt64)─┐
│ 1739489491011123456 │
└─────────────────────────────┘toUnixTimestamp64Second
引入版本：v24.12.0
将 DateTime64 转换为具有固定秒级精度的 Int64 值。
输入值会根据其精度相应按比例放大或缩小。
语法
toUnixTimestamp64Second(value)参数
value— 任意精度的 DateTime64 类型值。DateTime64
返回值
返回以秒为单位的 Unix 时间戳。Int64
示例
使用示例
WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);┌─toUnixTimestamp64Second(dt64)─┐
│ 1739489491 │
└───────────────────────────────┘