类型转换函数 - ClickHouse Documentation

数据转换中的常见问题

ClickHouse 通常采用与 C++ 程序相同的行为。 to<type> 函数和 cast 在某些情况下的行为有所不同，例如对于 LowCardinality：cast 会移除 LowCardinality 特性，而 to<type> 函数不会。对于 Nullable 也是如此。此行为与 SQL 标准不兼容，但可以通过 cast_keep_nullable 设置进行更改。

请注意，如果将某种数据类型的值转换为更小的数据类型 (例如从 Int64 转为 Int32) ，或者在不兼容的数据类型之间进行转换 (例如从 String 转为 Int) ，可能会导致数据丢失。请务必仔细检查结果是否符合预期。

示例：

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

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

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

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

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

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

`toString` 函数说明

toString 函数家族支持在数字、字符串 (但不包括定长字符串) 、日期和日期时间之间进行转换。所有这些函数都只接受一个参数。

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

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

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

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

例外情况是：如果将 UInt32、Int32、UInt64 或 Int64 数值类型转换为 Date，且该数值大于或等于 65536，则会将其解释为 Unix 时间戳 (而不是天数) ，并向下舍入为日期。这样就支持了常见的 toDate(unix_timestamp) 写法；否则这会报错，并且必须写成更繁琐的 toDate(toDateTime(unix_timestamp))。日期与日期时间之间的转换会以自然的方式进行：添加空时间部分，或去掉时间部分。数值类型之间的转换遵循与 C++ 中不同数值类型之间赋值相同的规则。示例

Query

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

Response

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

另请参见 toUnixTimestamp 函数。

CAST

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

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

参数

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

返回值 返回转换为目标数据类型后的值。Any 示例 基本用法

Query

SELECT CAST(42, 'String')

Response

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

使用 AS 语法

Query

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

Response

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

使用 :: 语法

Query

SELECT '123'::UInt32

Response

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

DATE

引入于：v21.2.0 将参数转换为 Date 数据类型。这是 toDate 的 MySQL 兼容别名，行为与 toDate 相同。语法

DATE(expr)

参数

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

返回值 返回 Date 值。Date 示例 基本用法

Query

SELECT DATE('2023-01-01')

Response

2023-01-01

accurateCast

引入版本：v1.1.0 将一个值转换为指定的数据类型。与 CAST 不同，accurateCast 会执行更严格的类型检查；如果转换会导致数据精度丢失，或无法进行转换，则会抛出异常。与常规的 CAST 相比，该函数更安全，因为它可以防止精度丢失和无效转换。语法

accurateCast(x, T)

参数

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

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

Query

SELECT accurateCast(42, 'UInt16')

Response

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

字符串转为数字

Query

SELECT accurateCast('123.45', 'Float64')

Response

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

accurateCastOrDefault

引入版本：v21.1.0 将值转换为指定的数据类型。与 accurateCast 类似，但如果无法进行精确转换，则返回默认值，而不是抛出异常。如果将默认值作为第二个参数传入，则该值必须属于目标类型。如果未提供默认值，则使用目标类型的默认值。语法

accurateCastOrDefault(x, T[, default_value])

参数

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

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

Query

SELECT accurateCastOrDefault(42, 'String')

Response

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

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

Query

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

Response

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

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

Query

SELECT accurateCastOrDefault('abc', 'UInt32')

Response

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

accurateCastOrNull

引入版本：v1.1.0 将值转换为指定的数据类型。与 accurateCast 类似，但如果无法精确完成转换，则返回 NULL，而不是抛出异常。此函数结合了 accurateCast 的安全性以及更平稳的错误处理方式。语法

accurateCastOrNull(x, T)

参数

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

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

Query

SELECT accurateCastOrNull(42, 'String')

Response

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

转换失败则返回 NULL

Query

SELECT accurateCastOrNull('abc', 'UInt32')

Response

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

formatRow

引入版本：v20.7.0 通过指定格式将任意表达式转换为字符串。

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

语法

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

参数

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

返回值 格式化后的字符串。 (对于文本格式，通常会以换行符结尾。) String 示例 基本用法

Query

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

Response

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

使用自定义格式

Query

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

Response

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

formatRowNoNewline

引入版本：v20.7.0 与 formatRow 相同，但会去掉每行末尾的换行符。通过指定的格式将任意表达式转换为字符串，但会移除结果末尾的所有换行符。语法

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

参数

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

返回值 返回去除了换行符的格式化字符串。String 示例 基本用法

Query

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

Response

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

fromUnixTimestamp64Micro

引入于：v20.5.0 将以微秒为单位的 Unix 时间戳转换为具有微秒精度的 DateTime64 值。输入值会被视为具有微秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 起经过的微秒数) 。语法

fromUnixTimestamp64Micro(value[, timezone])

参数

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

返回值 返回具有微秒精度的 DateTime64 值。DateTime64(6) 示例 使用示例

Query

SELECT fromUnixTimestamp64Micro(1640995200123456)

Response

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

fromUnixTimestamp64Milli

引入版本：v20.5.0 将以毫秒为单位的 Unix 时间戳转换为具有毫秒精度的 DateTime64 值。输入值会被视为毫秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 起经过的毫秒数) 。语法

fromUnixTimestamp64Milli(value[, timezone])

参数

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

返回值 具有毫秒精度的 DateTime64 值。DateTime64(3) 示例 用法示例

Query

SELECT fromUnixTimestamp64Milli(1640995200123)

Response

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

fromUnixTimestamp64Nano

引入版本：v20.5.0 将纳秒级 Unix 时间戳转换为具有纳秒精度的 DateTime64 值。输入值会被视为纳秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 以来的纳秒数) 。

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

语法

fromUnixTimestamp64Nano(value[, timezone])

参数

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

返回值 返回具有纳秒精度的 DateTime64 值。DateTime64(9) 示例 用法示例

Query

SELECT fromUnixTimestamp64Nano(1640995200123456789)

Response

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

fromUnixTimestamp64Second

引入版本：v24.12.0 将以秒为单位的 Unix 时间戳转换为秒精度的 DateTime64 值。输入值会被视为秒精度的 Unix 时间戳 (自 1970-01-01 00:00:00 UTC 起经过的秒数) 。语法

fromUnixTimestamp64Second(value[, timezone])

参数

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

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

Query

SELECT fromUnixTimestamp64Second(1640995200)

Response

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

parseDateTime

引入版本：v23.3.0 根据 MySQL 日期格式字符串解析日期时间字符串。此函数是 formatDateTime 的逆函数。它使用格式 String 解析 String 参数，并返回 DateTime 类型。语法

parseDateTime(time_string, format[, timezone])

别名: TO_UNIXTIME 参数

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

返回值 根据 MySQL 风格的格式字符串，从输入字符串解析出的 DateTime。DateTime 示例 使用示例

Query

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

Response

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

parseDateTime32BestEffort

Introduced in: v20.9.0 将日期和时间的字符串表示形式转换为 DateTime 数据类型。该函数可以解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 Date and Time Specification、ClickHouse 以及其他一些日期和时间格式。语法

parseDateTime32BestEffort(time_string[, time_zone])

参数

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

返回值 将 time_string 以 DateTime 类型返回。DateTime 示例 使用示例

Query

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

Response

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

带时区

Query

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

Response

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

Unix 时间戳

Query

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

Response

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

parseDateTime32BestEffortOrNull

引入版本：v20.9.0 与 parseDateTime32BestEffort 相同，但在遇到无法处理的日期格式时会返回 NULL。语法

parseDateTime32BestEffortOrNull(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTime32BestEffortOrZero

引入版本：v20.9.0 与 parseDateTime32BestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。语法

parseDateTime32BestEffortOrZero(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTime64

引入版本：v24.11.0 按照 MySQL 日期格式字符串，解析带有子秒级精度的日期时间字符串。对于 DateTime64，此函数是 formatDateTime 的逆操作。它使用格式 String 解析一个 String 参数。返回 DateTime64 类型，可表示 1900 年到 2299 年之间、具有子秒级精度的日期时间值。语法

parseDateTime64(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTime64BestEffort

在 v20.1.0 中引入与 parseDateTimeBestEffort 函数相同，但还支持解析毫秒和微秒，并返回 DateTime64 数据类型。语法

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

参数

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

返回值 返回转换为 DateTime64 数据类型的 time_string。 DateTime64 示例 用法示例

Query

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

Response

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

parseDateTime64BestEffortOrNull

引入版本：v20.1.0 与 parseDateTime64BestEffort 相同，不同之处在于，遇到无法处理的日期格式时会返回 NULL。语法

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

参数

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

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

Query

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

Response

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

parseDateTime64BestEffortOrZero

引入版本：v20.1.0 与 parseDateTime64BestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。语法

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

参数

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

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

Query

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

Response

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

parseDateTime64BestEffortUS

引入版本：v22.8.0 与 parseDateTime64BestEffort 相同，但在日期格式存在歧义时，此函数会优先采用美国日期格式 (MM/DD/YYYY 等) 。语法

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

参数

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

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

Query

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

Response

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

parseDateTime64BestEffortUSOrNull

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

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

参数

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

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

Query

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

Response

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

parseDateTime64BestEffortUSOrZero

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

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

参数

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

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

Query

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

Response

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

parseDateTime64InJodaSyntax

引入版本：v24.10.0 根据 Joda 日期格式字符串，解析具有子秒级精度的日期和时间字符串。对于 DateTime64，此函数是 formatDateTimeInJodaSyntax 的逆操作。它使用 Joda 风格的格式 String 解析一个 String 类型的参数。返回 DateTime64 类型，可表示 1900 年至 2299 年间且具有子秒级精度的日期和时间。有关格式模式，请参阅 Joda Time documentation。语法

parseDateTime64InJodaSyntax(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTime64InJodaSyntaxOrNull

Introduced in: v24.10.0 与 parseDateTime64InJodaSyntax 相同，但遇到无法解析的日期格式时会返回 NULL。 Syntax

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTime64InJodaSyntaxOrZero

引入版本：v24.10.0 与 parseDateTime64InJodaSyntax 相同，但在遇到无法解析的日期格式时会返回零日期。语法

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTime64OrNull

引入于：v24.11.0 与 parseDateTime64 相同，但遇到无法解析的日期格式时会返回 NULL。语法

parseDateTime64OrNull(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTime64OrZero

引入版本：v24.11.0 与 parseDateTime64 相同，但遇到无法解析的日期格式时会返回零日期。语法

parseDateTime64OrZero(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTimeBestEffort

版本引入：v1.1.0 将 String 字符串表示形式中的日期和时间转换为 DateTime 数据类型。该函数可解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 日期和时间规范、ClickHouse 格式以及其他一些日期和时间格式。支持的非标准格式：

包含 9..10 位 Unix 时间戳的字符串。
包含日期和时间部分的字符串：YYYYMMDDhhmmss、DD/MM/YYYY hh:mm:ss、DD-MM-YY hh:mm、YYYY-MM-DD hh:mm:ss 等。
包含日期但不含时间部分的字符串：YYYY、YYYYMM、YYYY*MM、DD/MM/YYYY、DD-MM-YY 等。
包含日期和时间的字符串：DD、DD hh、DD hh:mm。在这种情况下，MM 会替换为 01。
包含日期、时间及时区偏移信息的字符串：YYYY-MM-DD hh:mm:ss ±h:mm 等。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

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

parseDateTimeBestEffort(time_string[, time_zone])

参数

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

返回值 返回 DateTime 类型的 time_string。DateTime 示例 用法示例

Query

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

Response

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

带有时区

Query

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

Response

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

Unix 时间戳

Query

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

Response

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

parseDateTimeBestEffortOrNull

引入版本：v1.1.0 与 parseDateTimeBestEffort 相同，不同之处在于当遇到无法处理的日期格式时，它会返回 NULL。该函数可解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 日期和时间规范、ClickHouse 的日期和时间格式以及其他一些格式。支持的非标准格式：

包含 9 到 10 位 Unix 时间戳的字符串。
包含日期和时间部分的字符串：YYYYMMDDhhmmss、DD/MM/YYYY hh:mm:ss、DD-MM-YY hh:mm、YYYY-MM-DD hh:mm:ss 等。
包含日期但不包含时间部分的字符串：YYYY、YYYYMM、YYYY*MM、DD/MM/YYYY、DD-MM-YY 等。
包含日和时间的字符串：DD、DD hh、DD hh:mm。在这种情况下，MM 会被替换为 01。
包含日期、时间和时区偏移信息的字符串：YYYY-MM-DD hh:mm:ss ±h:mm 等。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

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

parseDateTimeBestEffortOrNull(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTimeBestEffortOrZero

引入版本：v1.1.0 与 parseDateTimeBestEffort 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。该函数可解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 日期和时间规范、ClickHouse 格式以及其他一些日期和时间格式。支持的非标准格式：

包含 9 到 10 位 Unix 时间戳的字符串。
包含日期和时间部分的字符串：YYYYMMDDhhmmss、DD/MM/YYYY hh:mm:ss、DD-MM-YY hh:mm、YYYY-MM-DD hh:mm:ss 等。
包含日期但不包含时间部分的字符串：YYYY、YYYYMM、YYYY*MM、DD/MM/YYYY、DD-MM-YY 等。
包含日期和时间的字符串：DD、DD hh、DD hh:mm。在这种情况下，MM 会被替换为 01。
包含日期、时间和时区偏移信息的字符串：YYYY-MM-DD hh:mm:ss ±h:mm 等。
syslog 时间戳：Mmm dd hh:mm:ss。例如，Jun 9 14:20:32。

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

parseDateTimeBestEffortOrZero(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTimeBestEffortUS

引入于：v1.1.0 对于 ISO 日期格式 (例如 YYYY-MM-DD hh:mm:ss) 以及其他能够明确识别出月份和日期组件的日期格式 (例如 YYYYMMDDhhmmss、YYYY-MM、DD hh 或 YYYY-MM-DD hh:mm:ss ±h:mm) ，此函数的行为与 parseDateTimeBestEffort 相同。如果无法明确识别月份和日期组件，例如 MM/DD/YYYY、MM-DD-YYYY 或 MM-DD-YY，则会优先按美国日期格式解析，而不是按 DD/MM/YYYY、DD-MM-YYYY 或 DD-MM-YY 解析。不过，上一条有一个例外：如果月份值大于 12 且小于等于 31，此函数会回退到 parseDateTimeBestEffort 的行为，例如 15/08/2020 会被解析为 2020-08-15。语法

parseDateTimeBestEffortUS(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTimeBestEffortUSOrNull

引入版本：v1.1.0 与 parseDateTimeBestEffortUS 函数相同，不同之处在于：当遇到无法处理的日期格式时，它会返回 NULL。对于 ISO 日期格式，此函数的行为与 parseDateTimeBestEffort 相同；但在存在歧义的情况下，会优先采用美国日期格式，并在解析出错时返回 NULL。语法

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTimeBestEffortUSOrZero

引入版本：v1.1.0 与 parseDateTimeBestEffortUS 函数相同，但当遇到无法处理的日期格式时，它会返回零日期 (1970-01-01) 或零日期时间 (1970-01-01 00:00:00) 。对于 ISO 日期格式，此函数的行为与 parseDateTimeBestEffort 相同；但在存在歧义的情况下，会优先采用美国日期格式，并在解析错误时返回零值。语法

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

参数

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

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

Query

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

Response

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

parseDateTimeInJodaSyntax

引入版本：v23.3.0 根据 Joda 日期格式字符串解析日期时间字符串。此函数是 formatDateTimeInJodaSyntax 的逆操作。它使用 Joda 风格的格式 String 解析 String 参数，并返回 DateTime 类型。有关格式模式，请参阅 Joda Time 文档。语法

parseDateTimeInJodaSyntax(time_string, format[, timezone])

参数

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

返回值 根据 Joda 风格的格式字符串，从输入字符串解析得到的 DateTime。DateTime 示例 使用示例

Query

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

Response

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

parseDateTimeInJodaSyntaxOrNull

引入版本：v23.3.0 与 parseDateTimeInJodaSyntax 相同，但在遇到无法解析的日期格式时返回 NULL。语法

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTimeInJodaSyntaxOrZero

引入版本：v23.3.0 与 parseDateTimeInJodaSyntax 相同，但遇到无法解析的日期格式时会返回零日期。语法

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

parseDateTimeOrNull

版本引入：v23.3.0 与 parseDateTime 相同，但遇到无法解析的日期格式时会返回 NULL。语法

parseDateTimeOrNull(time_string, format[, timezone])

别名: str_to_date 参数

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

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

Query

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

Response

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

parseDateTimeOrZero

在以下版本中引入：v23.3.0 与 parseDateTime 相同，但在遇到无法解析的日期格式时会返回零日期。语法

parseDateTimeOrZero(time_string, format[, timezone])

参数

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

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

Query

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

Response

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

reinterpret

引入版本：v1.1.0 对给定的值 x，使用其在内存中的同一源字节序列，并将其重新解释为目标类型。语法

reinterpret(x, type)

参数

x — 任意类型。Any
type — 目标类型。若为数组，则其元素类型必须为定长类型。String

返回值 目标类型的值。Any 示例 用法示例

Query

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

Response

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

Array 示例

Query

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

Response

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

reinterpretAsDate

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

reinterpretAsDate(x)

参数

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

返回值 日期。Date 示例 使用示例

Query

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

Response

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

reinterpretAsDateTime

引入版本：v1.1.0 将输入值重新解释为 DateTime 值 (按小端字节序) ，即自 Unix 纪元 1970-01-01 开始以来的天数语法

reinterpretAsDateTime(x)

参数

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

返回值 日期和时间。DateTime 示例 用法示例

Query

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

Response

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

reinterpretAsFixedString

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

reinterpretAsFixedString(x)

参数

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

返回值 包含表示 x 的字节的定长字符串。FixedString 示例 使用示例

Query

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

Response

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

reinterpretAsFloat32

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

reinterpretAsFloat32(x)

参数

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

返回值 返回重新解释后的值 x。Float32 示例 使用示例

Query

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

Response

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

reinterpretAsFloat64

在以下版本中引入：v1.1.0 将输入值重新解释为 Float64 类型的值。与 CAST 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出未定义。语法

reinterpretAsFloat64(x)

参数

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

返回值 返回重新解释后的值 x。Float64 示例 用法示例

Query

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

Response

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

reinterpretAsInt128

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

reinterpretAsInt128(x)

参数

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

返回值 返回重新解释后的值 x。Int128 示例 用法示例

Query

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

Response

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

reinterpretAsInt16

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

reinterpretAsInt16(x)

参数

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

返回值 返回重新解释后的值 x。Int16 示例 使用示例

Query

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

Response

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

reinterpretAsInt256

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

reinterpretAsInt256(x)

参数

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

返回值 返回重新解释后的值 x。Int256 示例 使用示例

Query

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

Response

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

reinterpretAsInt32

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

reinterpretAsInt32(x)

参数

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

返回值 返回重新解释后的值 x。Int32 示例 用法示例

Query

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

Response

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

reinterpretAsInt64

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

reinterpretAsInt64(x)

参数

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

返回值 返回重新解释后的值 x。Int64 示例 使用示例

Query

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

Response

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

reinterpretAsInt8

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

reinterpretAsInt8(x)

参数

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

返回值 返回重新解释后的值 x。Int8 示例 用法示例

Query

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

Response

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

reinterpretAsString

引入版本：v1.1.0 将输入值重新解释为字符串 (假设采用小端字节序) 。末尾的空字节会被忽略。例如，对于值为 255 的 UInt32，该函数会返回一个仅包含单个字符的字符串。语法

reinterpretAsString(x)

参数

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

返回值 包含表示 x 的字节序列的字符串。String 示例 用法示例

Query

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

Response

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

reinterpretAsUInt128

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

reinterpretAsUInt128(x)

参数

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

返回值 返回重新解释后的值 x。UInt128 示例 使用示例

Query

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

Response

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

reinterpretAsUInt16

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

reinterpretAsUInt16(x)

参数

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

返回值 返回重新解释后的值 x。UInt16 示例 用法示例

Query

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

Response

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

reinterpretAsUInt256

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

reinterpretAsUInt256(x)

参数

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

返回值 返回重新解释后的值 x。UInt256 示例 用法示例

Query

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

Response

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

reinterpretAsUInt32

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

reinterpretAsUInt32(x)

参数

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

返回值 返回重新解释后的 x 值。UInt32 示例 使用示例

Query

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

Response

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

reinterpretAsUInt64

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

reinterpretAsUInt64(x)

参数

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

返回值 返回 x 重新解释后的值。UInt64 示例 使用示例

Query

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

Response

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

reinterpretAsUInt8

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

reinterpretAsUInt8(x)

参数

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

返回值 返回重新解释后的值 x。UInt8 示例 用法示例

Query

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

Response

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

reinterpretAsUUID

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

reinterpretAsUUID(fixed_string)

参数

fixed_string — 大端字节串。FixedString

返回值 UUID 类型的值。UUID 示例 字符串转换为 UUID

Query

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

Response

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

toBFloat16

引入版本：v1.1.0 将输入值转换为 BFloat16 类型的值。如果发生错误，会抛出异常。另请参见：

toBFloat16OrZero。
toBFloat16OrNull。

语法

toBFloat16(expr)

参数

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

返回值 返回一个 16 位 brain-float 类型的值。BFloat16 示例 使用示例

Query

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

Response

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

toBFloat16OrNull

引入于：v1.1.0 将 String 输入值转换为 BFloat16 类型的值。如果字符串不表示浮点值，则该函数返回 NULL。支持的参数：

数值的字符串表示形式。

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

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

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

另请参见：

toBFloat16.
toBFloat16OrZero.

语法

toBFloat16OrNull(x)

参数

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

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

Query

SELECT toBFloat16OrNull('0x5E'), -- 不支持的参数
       toBFloat16OrNull('12.3'), -- 典型用法
       toBFloat16OrNull('12.3456789') -- 精度静默丢失

Response

\N
12.25
12.3125

toBFloat16OrZero

引入版本：v1.1.0 将 String 输入值转换为 BFloat16 类型的值。如果该字符串不表示浮点数值，则函数返回零。支持的参数：

数值的字符串表示形式。

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

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

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

另请参见：

toBFloat16.
toBFloat16OrNull.

语法

toBFloat16OrZero(x)

参数

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

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

Query

SELECT toBFloat16OrZero('0x5E'), -- 不支持的参数
       toBFloat16OrZero('12.3'), -- 典型用法
       toBFloat16OrZero('12.3456789') -- 静默精度损失

Response

0
12.25
12.3125

toBool

Introduced in：v22.2.0 将输入值转换为 Bool 类型。语法

toBool(expr)

参数

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

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

Query

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

Response

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

toDate

引入版本：v1.1.0 将输入值转换为 Date 类型。支持从 String、FixedString、DateTime 或数值类型转换。语法

toDate(x)

参数

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

返回值 返回转换后的输入值。Date 示例 将 String 转换为 Date

Query

SELECT toDate('2025-04-15')

Response

2025-04-15

将 DateTime 转换为 Date

Query

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

Response

2025-04-15

整数转换为日期

Query

SELECT toDate(20297)

Response

2025-07-28

toDate32

引入版本：v21.9.0 将参数转换为 Date32 数据类型。如果值超出范围，toDate32 会返回 Date32 支持的边界值。如果参数类型为 Date，则会考虑其取值边界。语法

toDate32(expr)

参数

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

返回值 返回一个日历日期。Date32 示例 在取值范围内

Query

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

Response

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

超出取值范围

Query

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

Response

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

toDate32OrDefault

引入版本：v21.11.0 将参数转换为 Date32 数据类型。如果该值超出范围，toDate32OrDefault 会返回 Date32 支持的下限值。如果参数的类型为 Date，则会考虑其边界。如果接收到无效参数，则返回默认值。语法

toDate32OrDefault(expr[, default])

参数

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

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

Query

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

Response

1930-01-01

转换失败

Query

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

Response

2020-01-01

toDate32OrNull

引入版本：v21.9.0 将输入值转换为 Date32 类型的值；如果参数无效，则返回 NULL。与 toDate32 相同，但在参数无效时会返回 NULL。语法

toDate32OrNull(x)

参数

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

返回值 成功时返回 Date32 值，否则返回 NULL。Date32 或 NULL 示例 用法示例

Query

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

Response

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

toDate32OrZero

引入版本：v21.9.0 将输入值转换为 Date32 类型的值；如果收到无效参数，则返回 Date32 的下界值。与 toDate32 相同，但如果收到无效参数，则返回 Date32 的下界值。另请参见：

toDate32
toDate32OrNull
toDate32OrDefault

语法

toDate32OrZero(x)

参数

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

返回值 成功时返回 Date32 值，否则返回 Date32 的下界值 (1900-01-01) 。Date32 示例 使用示例

Query

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

Response

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

toDateOrDefault

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

toDateOrDefault(expr[, default])

参数

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

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

Query

SELECT toDateOrDefault('2022-12-30')

Response

2022-12-30

转换失败

Query

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

Response

2023-01-01

toDateOrNull

首次引入版本：v1.1.0 将输入值转换为 Date 类型的值；如果参数无效，则返回 NULL。与 toDate 相同，但在参数无效时返回 NULL。语法

toDateOrNull(x)

参数

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

返回值 成功时返回 Date 值，否则返回 NULL。Date 或 NULL 示例 用法示例

Query

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

Response

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

toDateOrZero

引入版本：v1.1.0 将输入值转换为 Date 类型的值；如果传入的是无效参数，则返回 Date 的下界值。与 toDate 相同，但如果传入的是无效参数，则返回 Date 的下界值。另请参见：

toDate
toDateOrNull
toDateOrDefault

语法

toDateOrZero(x)

参数

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

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

Query

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

Response

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

toDateTime

引入于：v1.1.0 将输入值转换为 DateTime 类型。

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

语法

toDateTime(expr[, time_zone])

参数

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

返回值 返回日期时间。DateTime 示例 使用示例

Query

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

Response

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

toDateTime32

Introduced in: v20.9.0 将输入值转换为 DateTime 类型。支持从 String、FixedString、Date、Date32、DateTime 或数值类型 ((U)Int*、Float*、Decimal) 转换。与 DateTime 相比，DateTime32 的取值范围更大，支持 1900-01-01 至 2299-12-31 的日期。 Syntax

toDateTime32(x[, timezone])

参数

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

返回值 返回转换后的输入值。DateTime 示例 值在范围内

Query

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

Response

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

作为指定精度的 Decimal 值

Query

SELECT toDateTime64(1735689600.000, 3) AS value, toTypeName(value);
-- 没有小数点时，该值仍被视为以秒为单位的 Unix 时间戳
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

Response

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

指定时区

Query

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

Response

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

toDateTime64

引入版本：v20.1.0 将输入值转换为 DateTime64 类型的值。语法

toDateTime64(expr, scale[, timezone])

参数

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

返回值 返回具有子秒级精度的日历日期和时间。DateTime64 示例 值在范围内

Query

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

Response

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

作为指定精度的 Decimal

Query

SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- 没有小数点时，该值仍被视为以秒为单位的 Unix 时间戳
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);

Response

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

指定时区

Query

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

Response

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

toDateTime64OrDefault

引入版本：v21.11.0 与 toDateTime64 类似，此函数会将输入值转换为 DateTime64 类型的值，但如果收到无效参数，则返回 DateTime64 的默认值或提供的默认值。语法

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

参数

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

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

Query

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

Response

1976-10-18 00:00:00.300

转换失败

Query

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

Response

2000-12-31 23:00:00.000

toDateTime64OrNull

引入版本：v20.1.0 将输入值转换为 DateTime64 类型的值；如果接收到无效参数，则返回 NULL。与 toDateTime64 相同，但如果接收到无效参数，则返回 NULL。语法

toDateTime64OrNull(x)

参数

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

返回值 如果成功，则返回 DateTime64 值；否则返回 NULL。DateTime64 或 NULL 示例 用法示例

Query

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

Response

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

toDateTime64OrZero

引入版本：v20.1.0 将输入值转换为 DateTime64 类型的值；如果接收到无效参数，则返回 DateTime64 的下界值。与 toDateTime64 相同，但在接收到无效参数时会返回 DateTime64 的下界值。另请参见：

toDateTime64。
toDateTime64OrNull。
toDateTime64OrDefault。

语法

toDateTime64OrZero(x)

参数

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

返回值 成功时返回 DateTime64 值，否则返回 DateTime64 的下界值 (1970-01-01 00:00:00.000) 。DateTime64 示例 使用示例

Query

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

Response

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

toDateTimeOrDefault

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

toDateTimeOrDefault(expr[, timezone, default])

参数

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

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

Query

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

Response

2022-12-30 13:44:17

转换失败

Query

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

Response

2023-01-01 00:00:00

toDateTimeOrNull

引入版本：v1.1.0 将输入值转换为 DateTime 类型的值；如果接收到无效参数，则返回 NULL。与 toDateTime 相同，但在接收到无效参数时会返回 NULL。语法

toDateTimeOrNull(x)

参数

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

返回值 成功时返回 DateTime 值，否则返回 NULL。DateTime 或 NULL 示例 用法示例

Query

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

Response

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

toDateTimeOrZero

引入版本：v1.1.0 将输入值转换为 DateTime 类型的值；如果收到无效参数，则返回 DateTime 的下界值。与 toDateTime 相同，但如果收到无效参数，则返回 DateTime 的下界值。语法

toDateTimeOrZero(x)

参数

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

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

Query

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

Response

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

toDecimal128

引入版本：v18.12.0 将输入值转换为标度为 S 的 Decimal(38, S) 类型值。出错时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

语法

toDecimal128(expr, S)

参数

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

返回值 返回类型为 Decimal(38, S) 的值 Decimal128(S) 示例 用法示例

Query

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

Response

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

toDecimal128OrDefault

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

toDecimal128OrDefault(expr, S[, default])

参数

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

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

Query

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

Response

0.023809523809523808

转换失败

Query

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

Response

-1

toDecimal128OrNull

引入版本：v20.1.0 将输入值转换为 Decimal(38, S) 类型的值；如果出错，则返回 NULL。与 toDecimal128 类似，但在转换出错时返回 NULL，而不是抛出异常。支持的参数：

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

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

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

另请参阅：

toDecimal128。
toDecimal128OrZero。
toDecimal128OrDefault。

语法

toDecimal128OrNull(expr, S)

参数

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

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

Query

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

Response

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

toDecimal128OrZero

引入版本：v20.1.0 将输入值转换为 Decimal(38, S) 类型的值；如果出错，则返回 0。与 toDecimal128 类似，但在转换出错时返回 0，而不是抛出异常。支持的参数：

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

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

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

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

语法

toDecimal128OrZero(expr, S)

参数

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

返回值 成功时返回 Decimal(38, S) 值，否则返回 0。Decimal128(S) 示例 基本用法

Query

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

Response

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

toDecimal256

引入版本：v20.8.0 将输入值转换为带有 S 标度的 Decimal(76, S) 类型的值。出错时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

语法

toDecimal256(expr, S)

参数

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

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

Query

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

Response

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

toDecimal256OrDefault

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

toDecimal256OrDefault(expr, S[, default])

参数

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

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

Query

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

Response

0.023809523809523808

转换失败

Query

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

Response

-1

toDecimal256OrNull

引入版本：v20.8.0 将输入值转换为 Decimal(76, S) 类型的值，但如果出错则返回 NULL。与 toDecimal256 类似，但在转换出错时返回 NULL，而不是抛出异常。支持的参数：

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

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

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

另请参阅：

toDecimal256。
toDecimal256OrZero。
toDecimal256OrDefault。

语法

toDecimal256OrNull(expr, S)

参数

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

返回值 成功时返回 Decimal(76, S) 值，否则返回 NULL。Decimal256(S) 或 NULL 示例 使用示例

Query

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

Response

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

toDecimal256OrZero

引入版本：v20.8.0 将输入值转换为 Decimal(76, S) 类型的值，但如果发生错误则返回 0。与 toDecimal256 类似，但在转换出错时返回 0，而不是抛出异常。支持的参数：

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

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

Float* 值 NaN 和 Inf，以及它们的字符串表示形式 (不区分大小写) 。
二进制和十六进制值的字符串表示形式。

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

另请参阅：

toDecimal256。
toDecimal256OrNull。
toDecimal256OrDefault。

语法

toDecimal256OrZero(expr, S)

参数

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

返回值 成功时返回 Decimal(76, S) 值，否则返回 0。Decimal256(S) 示例 用法示例

Query

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

Response

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

toDecimal32

引入版本：v18.12.0 将输入值转换为 Decimal(9, S) 类型、标度为 S 的值。出错时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

语法

toDecimal32(expr, S)

参数

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

返回值 返回类型为 Decimal(9, S) 的值 Decimal32(S) 示例 使用示例

Query

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

Response

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

toDecimal32OrDefault

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

toDecimal32OrDefault(expr, S[, default])

参数

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

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

Query

SELECT toDecimal32OrDefault(toString(0.0001), 5)

Response

0.0001

转换失败

Query

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

Response

-1

toDecimal32OrNull

引入版本：v20.1.0 将输入值转换为 Decimal(9, S) 类型的值；如果发生错误，则返回 NULL。与 toDecimal32 类似，但在转换出错时会返回 NULL，而不是抛出异常。支持的参数：

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

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

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

另请参见：

toDecimal32。
toDecimal32OrZero。
toDecimal32OrDefault。

语法

toDecimal32OrNull(expr, S)

参数

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

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

Query

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

Response

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

toDecimal32OrZero

引入版本：v20.1.0 将输入值转换为 Decimal(9, S) 类型的值，但如果发生错误则返回 0。与 toDecimal32 类似，但在转换出错时会返回 0，而不是抛出异常。支持的参数：

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

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

Float* 值 NaN 和 Inf，以及它们的字符串表示形式 (不区分大小写) 。
二进制和十六进制值的字符串表示形式。

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

语法

toDecimal32OrZero(expr, S)

参数

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

返回值 成功时返回 Decimal(9, S) 值，否则返回 0。Decimal32(S) 示例 用法示例

Query

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

Response

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

toDecimal64

引入版本：v18.12.0 将输入值转换为标度为 S 的 Decimal(18, S) 类型值。出错时会抛出异常。支持的参数：

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

不支持的参数：

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

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

转换会截去多余的数字；处理 Float32/Float64 输入时，由于这些操作是通过浮点指令执行的，结果可能会出现意外情况。例如：toDecimal64(1.15, 2) 等于 1.14，因为在浮点运算中，1.15 * 100 的结果是 114.99。你可以改用 String 输入，这样操作将使用底层整数类型：toDecimal64('1.15', 2) = 1.15

语法

toDecimal64(expr, S)

参数

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

返回值 返回一个 Decimal 值。Decimal(18, S) 示例 使用示例

Query

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

Response

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

toDecimal64OrDefault

首次引入版本：v21.11.0 与 toDecimal64 类似，此函数会将输入值转换为 Decimal(18, S) 类型的值，但如果发生错误，则返回默认值。语法

toDecimal64OrDefault(expr, S[, default])

参数

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

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

Query

SELECT toDecimal64OrDefault(toString(0.0001), 18)

Response

0.0001

转换失败

Query

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

Response

-1

toDecimal64OrNull

引入版本：v20.1.0 将输入值转换为 Decimal(18, S) 类型的值；如果出错，则返回 NULL。与 toDecimal64 类似，但在转换出错时返回 NULL，而不是抛出异常。支持的参数：

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

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

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

另请参见：

toDecimal64。
toDecimal64OrZero。
toDecimal64OrDefault。

语法

toDecimal64OrNull(expr, S)

参数

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

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

Query

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

Response

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

toDecimal64OrZero

引入版本：v20.1.0 将输入值转换为 Decimal(18, S) 类型的值，但如果发生错误则返回 0。与 toDecimal64 类似，但在转换错误时返回 0，而不是抛出异常。支持的参数：

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

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

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

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

另请参见：

toDecimal64。
toDecimal64OrNull。
toDecimal64OrDefault。

语法

toDecimal64OrZero(expr, S)

参数

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

返回值 成功时返回 Decimal(18, S) 值，否则返回 0。Decimal64(S) 示例 使用示例

Query

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

Response

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

toDecimalString

引入版本：v23.3.0 将数值转换为具有指定小数位数的 String。该函数会将输入值四舍五入到指定的小数位数。如果输入值的小数位数少于指定值，则结果会用 0 补齐，以达到指定的确切小数位数。语法

toDecimalString(number, scale)

参数

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

返回值 返回该数值的 String 表示形式，并且小数位数严格等于指定的位数。String 示例 对数值进行四舍五入并格式化

Query

SELECT toDecimalString(2.1456, 2)

Response

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

用零补齐

Query

SELECT toDecimalString(5, 3)

Response

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

不同数值类型

Query

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

Response

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

toFixedString

引入版本：v1.1.0 将 String 参数转换为 FixedString(N) 类型 (长度固定为 N 的字符串) 。如果字符串的字节数小于 N，则会在右侧用空字节填充。如果字符串的字节数大于 N，则会抛出异常。语法

toFixedString(s, N)

参数

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

返回值 返回长度为 N 的 FixedString。FixedString(N) 示例 使用示例

Query

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

Response

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

toFloat32

引入版本：v1.1.0 将输入值转换为 Float32 类型的值。如果出错，则会抛出异常。支持的参数：

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

不支持的参数：

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

另请参见：

toFloat32OrZero。
toFloat32OrNull。
toFloat32OrDefault。

语法

toFloat32(expr)

参数

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

返回值 返回一个 32 位浮点数。Float32 示例 使用示例

Query

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

Response

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

toFloat32OrDefault

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

toFloat32OrDefault(expr[, default])

参数

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

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

Query

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

Response

转换失败

Query

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

Response

toFloat32OrNull

引入版本：v1.1.0 将输入值转换为 Float32 类型的值；如果出错，则返回 NULL。与 toFloat32 类似，但在转换出错时会返回 NULL，而不是抛出异常。支持的参数：

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

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

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

另请参见：

toFloat32。
toFloat32OrZero。
toFloat32OrDefault。

语法

toFloat32OrNull(x)

参数

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

返回值 成功时返回 32 位 Float 值，否则返回 NULL。Float32 或 NULL 示例 使用示例

Query

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

Response

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

toFloat32OrZero

首次引入版本：v1.1.0 将输入值转换为 Float32 类型的值；如果发生错误，则返回 0。与 toFloat32 类似，但在转换出错时会返回 0，而不是抛出异常。另请参见：

toFloat32。
toFloat32OrNull。
toFloat32OrDefault。

语法

toFloat32OrZero(x)

参数

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

返回值 成功时返回 32 位 Float 值，否则返回 0。Float32 示例 用法示例

Query

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

Response

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

toFloat64

引入版本：v1.1.0 将输入值转换为 Float64 类型的值。发生错误时会抛出异常。支持的参数：

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

不支持的参数：

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

另请参阅：

toFloat64OrZero。
toFloat64OrNull。
toFloat64OrDefault。

语法

toFloat64(expr)

参数

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

返回值 返回 64 位浮点值。Float64 示例 用法示例

Query

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

Response

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

toFloat64OrDefault

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

toFloat64OrDefault(expr[, default])

参数

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

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

Query

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

Response

转换失败

Query

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

Response

toFloat64OrNull

引入版本：v1.1.0 将输入值转换为 Float64 类型的值；如果发生错误，则返回 NULL。与 toFloat64 类似，但在转换出错时会返回 NULL，而不是抛出异常。支持的参数：

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

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

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

另请参阅：

toFloat64。
toFloat64OrZero。
toFloat64OrDefault。

语法

toFloat64OrNull(x)

参数

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

返回值 成功时返回 64 位 Float 值，否则返回 NULL。 Float64 或 NULL 示例 使用示例

Query

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

Response

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

toFloat64OrZero

引入于：v1.1.0 将输入值转换为 Float64 类型的值；如果发生错误，则返回 0。与 toFloat64 类似，但在转换错误时会返回 0，而不是抛出异常。另请参见：

toFloat64。
toFloat64OrNull。
toFloat64OrDefault。

语法

toFloat64OrZero(x)

参数

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

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

Query

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

Response

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

toInt128

首次引入于：v1.1.0 将输入值转换为 Int128 类型的值。出错时会抛出异常。该函数采用向零舍入，也就是说会截断数字的小数位。支持的参数：

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

不支持的参数：

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

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

另请参见：

toInt128OrZero。
toInt128OrNull。
toInt128OrDefault。

语法

toInt128(expr)

参数

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

返回值 返回一个 128 位整数值。Int128 示例 用法示例

Query

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

Response

第 1 行：
──────
toInt128(-128):   -128
toInt128(-128.8): -128
toInt128('-128'): -128

toInt128OrDefault

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

toInt128OrDefault(expr[, default])

参数

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

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

Query

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

Response

-128

转换失败

Query

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

Response

-1

toInt128OrNull

Introduced in: v20.8.0 与 toInt128 类似，此函数会将输入值转换为 Int128 类型的值，但在出错时返回 NULL。支持的参数：

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

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

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

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

toInt128OrZero

引入版本：v20.8.0 将输入值转换为 Int128 类型，但如果发生错误则返回 0。与 toInt128 类似，但返回 0 而不是抛出异常。另请参见：

toInt128。
toInt128OrNull。
toInt128OrDefault。

语法

toInt128OrZero(x)

参数

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

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

Query

SELECT toInt128OrZero('123')

Response

转换失败时返回 0

Query

SELECT toInt128OrZero('abc')

Response

toInt16

引入于：v1.1.0 将输入值转换为 Int16 类型的值。发生错误时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

另请参阅：

toInt16OrZero。
toInt16OrNull。
toInt16OrDefault。

语法

toInt16(expr)

参数

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

返回值 返回一个 16 位整数值。Int16 示例 用法示例

Query

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

Response

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

toInt16OrDefault

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

toInt16OrDefault(expr[, default])

参数

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

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

Query

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

Response

-16

转换失败

Query

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

Response

-1

toInt16OrNull

引入版本：v1.1.0 与 toInt16 类似，此函数将输入值转换为 Int16 类型的值，但如果发生错误，则返回 NULL。支持的参数：

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

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

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

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

另请参见：

toInt16。
toInt16OrZero。
toInt16OrDefault。

语法

toInt16OrNull(x)

参数

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

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

Query

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

Response

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

toInt16OrZero

引入版本：v1.1.0 与 toInt16 类似，此函数会将输入值转换为 Int16 类型的值，但在发生错误时返回 0。支持的参数：

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

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

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

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

另请参见：

toInt16。
toInt16OrNull。
toInt16OrDefault。

语法

toInt16OrZero(x)

参数

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

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

Query

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

Response

第 1 行:
──────
toInt16OrZero('16'): 16
toInt16OrZero('abc'): 0

toInt256

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

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

不支持的参数：

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

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

另请参见：

toInt256OrZero。
toInt256OrNull。
toInt256OrDefault。

语法

toInt256(expr)

参数

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

返回值 返回一个 256 位整数值。Int256 示例 使用示例

Query

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

Response

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

toInt256OrDefault

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

toInt256OrDefault(expr[, default])

参数

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

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

Query

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

Response

-256

转换失败

Query

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

Response

-1

toInt256OrNull

引入版本：v20.8.0 与 toInt256 类似，此函数会将输入值转换为 Int256 类型的值，但如果发生错误，则返回 NULL。支持的参数：

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

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

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

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

另请参阅：

toInt256。
toInt256OrZero。
toInt256OrDefault。

语法

toInt256OrNull(x)

参数

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

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

Query

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

Response

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

toInt256OrZero

引入版本：v20.8.0 将输入值转换为 Int256 类型；如果发生错误，则返回 0。与 toInt256 类似，但会返回 0，而不是抛出异常。另请参见：

toInt256。
toInt256OrNull。
toInt256OrDefault。

语法

toInt256OrZero(x)

参数

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

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

Query

SELECT toInt256OrZero('123')

Response

转换失败时返回 0

Query

SELECT toInt256OrZero('abc')

Response

toInt32

Introduced in: v1.1.0 将输入值转换为 Int32 类型的值。出错时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

toInt32OrDefault

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

toInt32OrDefault(expr[, default])

参数

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

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

Query

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

Response

-32

转换失败

Query

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

Response

-1

toInt32OrNull

引入版本：v1.1.0 与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值，但如果发生错误则返回 NULL。支持的参数：

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

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

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

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

另请参阅：

toInt32。
toInt32OrZero。
toInt32OrDefault。

语法

toInt32OrNull(x)

参数

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

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

Query

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

Response

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

toInt32OrZero

引入版本：v1.1.0 与 toInt32 类似，此函数会将输入值转换为 Int32 类型的值；如果发生错误，则返回 0。支持的参数：

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

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

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

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

另请参阅：

toInt32。
toInt32OrNull。
toInt32OrDefault。

语法

toInt32OrZero(x)

参数

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

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

Query

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

Response

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

toInt64

引入版本：v1.1.0 将输入值转换为 Int64 类型的值。如果发生错误，则会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

另请参见：

toInt64OrZero。
toInt64OrNull。
toInt64OrDefault。

语法

toInt64(expr)

参数

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

返回值 返回一个 64 位整数值。Int64 示例 使用示例

Query

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

Response

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

toInt64OrDefault

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

toInt64OrDefault(expr[, default])

参数

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

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

Query

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

Response

-64

转换失败

Query

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

Response

-1

toInt64OrNull

引入版本：v1.1.0 与 toInt64 类似，此函数将输入值转换为 Int64 类型的值，但如果发生错误，则返回 NULL。支持的参数：

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

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

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

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

另请参见：

toInt64。
toInt64OrZero。
toInt64OrDefault。

语法

toInt64OrNull(x)

参数

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

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

Query

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

Response

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

toInt64OrZero

引入版本：v1.1.0 将输入值转换为 Int64 类型，但如果发生错误则返回 0。与 toInt64 类似，不过它会返回 0，而不是抛出异常。另请参见：

toInt64。
toInt64OrNull。
toInt64OrDefault。

语法

toInt64OrZero(x)

参数

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

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

Query

SELECT toInt64OrZero('123')

Response

转换失败则返回零

Query

SELECT toInt64OrZero('abc')

Response

toInt8

引入版本：v1.1.0 将输入值转换为 Int8 类型的值。出错时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

另请参见：

toInt8OrZero。
toInt8OrNull。
toInt8OrDefault。

语法

toInt8(expr)

参数

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

返回值 返回一个 8 位整数值。Int8 示例 使用示例

Query

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

Response

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

toInt8OrDefault

首次引入版本：v21.11.0 与 toInt8 类似，此函数会将输入值转换为 Int8 类型的值，但如果发生错误，则返回默认值。如果未传入 default 值，则在发生错误时返回 0。语法

toInt8OrDefault(expr[, default])

参数

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

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

Query

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

Response

-8

转换失败

Query

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

Response

-1

toInt8OrNull

引入版本：v1.1.0 与 toInt8 类似，此函数会将输入值转换为 Int8 类型的值，但如果发生错误，则返回 NULL。支持的参数：

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

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

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

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

另请参阅：

toInt8。
toInt8OrZero。
toInt8OrDefault。

语法

toInt8OrNull(x)

参数

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

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

Query

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

Response

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

toInt8OrZero

版本引入：v1.1.0 与 toInt8 类似，此函数会将输入值转换为 Int8 类型的值，但如果出错则返回 0。支持的参数：

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

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

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

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

另请参见：

toInt8。
toInt8OrNull。
toInt8OrDefault。

语法

toInt8OrZero(x)

参数

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

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

Query

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

Response

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

toInterval

引入版本：v25.4.0 根据数值和单位字符串创建一个 Interval 值。该函数提供了一种统一的方法：通过将单位指定为字符串参数，用同一个函数创建不同类型的时间间隔 (秒、分钟、小时、天、周、月、季度、年) 。单位字符串不区分大小写。这等同于调用 toIntervalSecond、toIntervalMinute、toIntervalDay 等特定类型的函数，但允许通过字符串参数动态指定单位。语法

toInterval(value, unit)

参数

value — 表示单位数量的数值，可为任意数值类型。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64
unit — 时间单位。必须为常量字符串。有效值：‘nanosecond’、‘microsecond’、‘millisecond’、‘second’、‘minute’、‘hour’、‘day’、‘week’、‘month’、‘quarter’、‘year’。String

返回值 返回指定类型的 Interval 值。结果类型取决于 unit：IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter 或 IntervalYear。Interval 示例 创建不同单位的时间间隔

Query

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

Response

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

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

Query

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

Response

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

动态生成时间间隔

Query

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

Response

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

toIntervalDay

在 v1.1.0 中引入返回一个由 n 天组成、数据类型为 IntervalDay 的时间间隔。语法

toIntervalDay(n)

参数

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

返回值 返回 n 天的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalHour

在 v1.1.0 中引入返回一个表示 n 小时的时间间隔，数据类型为 IntervalHour。语法

toIntervalHour(n)

参数

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

返回值 返回一个 n 小时的时间间隔。Interval 示例 用法示例

Query

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

Response

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

toIntervalMicrosecond

引入版本：v22.6.0 返回一个由 n 微秒组成的时间间隔，数据类型为 IntervalMicrosecond。语法

toIntervalMicrosecond(n)

参数

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

返回值 返回由 n 微秒构成的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalMillisecond

引入版本：v22.6.0 返回一个 n 毫秒的时间间隔，数据类型为 IntervalMillisecond。语法

toIntervalMillisecond(n)

参数

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

返回值 返回一个包含 n 毫秒的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalMinute

引入版本：v1.1.0 返回一个表示 n 分钟的时间间隔，数据类型为 IntervalMinute。语法

toIntervalMinute(n)

参数

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

返回值 返回 n 分钟的时间间隔。Interval 示例 用法示例

Query

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

Response

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

toIntervalMonth

引入版本：v1.1.0 返回一个 n 个月的时间间隔，数据类型为 IntervalMonth。语法

toIntervalMonth(n)

参数

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

返回值 返回 n 个月的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalNanosecond

引入版本：v22.6.0 返回一个 n 纳秒的时间间隔，数据类型为 IntervalNanosecond。语法

toIntervalNanosecond(n)

参数

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

返回值 返回 n 纳秒的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalQuarter

在 v1.1.0 中引入返回一个由 n 个季度组成、数据类型为 IntervalQuarter 的时间间隔。语法

toIntervalQuarter(n)

参数

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

返回值 返回 n 个季度的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalSecond

引入版本：v1.1.0 返回一个由 n 秒构成、数据类型为 IntervalSecond 的时间间隔。语法

toIntervalSecond(n)

参数

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

返回值 返回 n 秒的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toIntervalWeek

引入版本：v1.1.0 返回一个表示 n 周的时间间隔，数据类型为 IntervalWeek。语法

toIntervalWeek(n)

参数

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

返回值 返回 n 周的时间间隔。Interval 示例 用法示例

Query

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

Response

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

toIntervalYear

引入版本：v1.1.0 返回一个表示 n 年的时间间隔，数据类型为 IntervalYear。语法

toIntervalYear(n)

参数

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

返回值 返回一个 n 年的时间间隔。Interval 示例 使用示例

Query

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

Response

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

toLowCardinality

引入版本：v18.12.0 将输入参数转换为相同数据类型的 LowCardinality 版本。

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

语法

toLowCardinality(expr)

参数

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

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

Query

SELECT toLowCardinality('1')

Response

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

toString

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

toString(value[, timezone])

参数

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

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

Query

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

Response

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

toStringCutToZero

引入版本：v1.1.0 接受一个 String 或 FixedString 类型的参数，并返回一个 String，该 String 是在第一个空字节处截断后的原始字符串副本。空字节 (\0) 被视为字符串终止符。当空字节用于标记有效内容的结尾时，此函数可用于处理 C 风格字符串或二进制数据。语法

toStringCutToZero(s)

参数

s — 要处理的 String 或 FixedString。String 或 FixedString

返回值 返回一个 String，包含第一个空字节之前的字符。String 示例 使用示例

Query

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

Response

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

toTime

引入版本：v1.1.0 将输入值转换为 Time 类型。支持从 String、FixedString、DateTime 或表示自午夜起经过秒数的数值类型进行转换。语法

toTime(x)

参数

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

返回值 返回转换后的值。Time 示例 String 转换为 Time

Query

SELECT toTime('14:30:25')

Response

14:30:25

DateTime 转换为 Time

Query

SELECT toTime(toDateTime('2025-04-15 14:30:25'))

Response

14:30:25

将整数转换为时间

Query

SELECT toTime(52225)

Response

14:30:25

toTime64

引入版本：v25.6.0 将输入值转换为 Time64 类型。支持从 String、FixedString、DateTime64，或表示自午夜起微秒数的数值类型进行转换。为时间值提供微秒级精度。语法

toTime64(x)

参数

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

返回值 返回转换后的输入值，精度为微秒。Time64(6) 示例 String 转换为 Time64

Query

SELECT toTime64('14:30:25.123456')

Response

14:30:25.123456

DateTime64 转换为 Time64

Query

SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))

Response

14:30:25.123456

整数转换为 Time64

Query

SELECT toTime64(52225123456)

Response

14:30:25.123456

toTime64OrNull

引入版本：v25.6.0 将输入值转换为 Time64 类型的值；如果发生错误，则返回 NULL。与 toTime64 类似，但在转换出错时会返回 NULL，而不是抛出异常。另请参见：

toTime64
toTime64OrZero

语法

toTime64OrNull(x)

参数

x — 具有子秒级精度的时间字符串表示形式。String

返回值 成功时返回 Time64 值，否则返回 NULL。Time64 或 NULL 示例 用法示例

Query

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

Response

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

toTime64OrZero

引入版本：v25.6.0 将输入值转换为 Time64 类型的值；如果发生错误，则返回 00:00:00.000。与 toTime64 类似，但在转换出错时会返回 00:00:00.000，而不是抛出异常。语法

toTime64OrZero(x)

参数

x — 具有子秒级精度的时间字符串表示形式。String

返回值 如果成功，返回 Time64 值；否则返回 00:00:00.000。Time64 示例 用法示例

Query

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

Response

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘

toTimeOrNull

引入版本：v1.1.0 将输入值转换为 Time 类型的值；如果发生错误，则返回 NULL。与 toTime 类似，但在转换出错时会返回 NULL，而不是抛出异常。另请参见：

toTime
toTimeOrZero

语法

toTimeOrNull(x)

参数

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

返回值 成功时返回 Time 值，否则返回 NULL。Time 或 NULL 示例 使用示例

Query

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

Response

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

toTimeOrZero

Introduced in: v1.1.0 将输入值转换为 Time 类型的值；如果出错，则返回 00:00:00。与 toTime 类似，但在转换出错时会返回 00:00:00，而不是抛出异常。 Syntax

toTimeOrZero(x)

参数

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

返回值 如果成功，返回 Time 值；否则返回 00:00:00。Time 示例 使用示例

Query

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

Response

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

toUInt128

引入版本：v1.1.0 将输入值转换为 UInt128 类型的值。出错时会抛出异常。该函数采用向零舍入，即会截断数字的小数位。支持的参数：

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

不支持的参数：

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

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

另请参见：

toUInt128OrZero。
toUInt128OrNull。
toUInt128OrDefault。

语法

toUInt128(expr)

参数

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

返回值 返回一个 128 位无符号整数值。UInt128 示例 用法示例

Query

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Response

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

toUInt128OrDefault

引入版本：v21.11.0 与 toUInt128 类似，此函数会将输入值转换为 UInt128 类型的值，但如果发生错误，则返回默认值。如果未传入 default 值，则在发生错误时返回 0。语法

toUInt128OrDefault(expr[, default])

参数

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

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

Query

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

Response

转换失败

Query

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

Response

toUInt128OrNull

引入版本：v21.6.0 与 toUInt128 类似，此函数将输入值转换为 UInt128 类型的值，但在发生错误时会返回 NULL。支持的参数：

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

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

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

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

另请参阅：

toUInt128。
toUInt128OrZero。
toUInt128OrDefault。

语法

toUInt128OrNull(x)

参数

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

返回值 返回 UInt128 类型的值；如果转换失败，则返回 NULL。UInt128 或 NULL 示例 使用示例

Query

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

toUInt128OrZero

引入版本：v1.1.0 与 toUInt128 类似，此函数会将输入值转换为 UInt128 类型的值，但如果发生错误则返回 0。支持的参数：

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

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

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

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

另请参见：

toUInt128。
toUInt128OrNull。
toUInt128OrDefault。

语法

toUInt128OrZero(x)

参数

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

返回值 返回 UInt128 类型的值；如果转换失败，则返回 0。UInt128 示例 使用示例

Query

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

toUInt16

引入版本：v1.1.0 将输入值转换为 UInt16 类型的值。发生错误时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

另请参见：

toUInt16OrZero。
toUInt16OrNull。
toUInt16OrDefault。

语法

toUInt16(expr)

参数

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

返回值 返回一个 16 位无符号整数值。UInt16 示例 使用示例

Query

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Response

第 1 行:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

toUInt16OrDefault

Introduced in：v21.11.0 与 toUInt16 类似，此函数会将输入值转换为 UInt16 类型的值，但如果发生错误，则返回默认值。如果未传入 default 值，则在发生错误时返回 0。 Syntax

toUInt16OrDefault(expr[, default])

参数

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

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

Query

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

Response

转换失败

Query

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

Response

toUInt16OrNull

Introduced in: v1.1.0 与 toUInt16 类似，此函数会将输入值转换为 UInt16 类型的值，但如果发生错误则返回 NULL。支持的参数：

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

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

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

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

toUInt16OrZero

引入于：v1.1.0 与 toUInt16 类似，此函数将输入值转换为 UInt16 类型的值，但在发生错误时会返回 0。支持的参数：

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

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

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

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

另请参阅：

toUInt16。
toUInt16OrNull。
toUInt16OrDefault。

语法

toUInt16OrZero(x)

参数

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

返回值 返回 UInt16 类型的值；如果转换失败，则返回 0。UInt16 示例 使用示例

Query

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

Response

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

toUInt256

在 v1.1.0 中引入将输入值转换为 UInt256 类型的值。出错时会抛出异常。该函数采用向零舍入，也就是说会截断数字的小数位。支持的参数：

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

不支持的参数：

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

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

另请参见：

toUInt256OrZero。
toUInt256OrNull。
toUInt256OrDefault。

语法

toUInt256(expr)

参数

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

返回值 返回一个 256 位无符号整数。UInt256 示例 使用示例

Query

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Response

行 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

toUInt256OrDefault

引入版本：v21.11.0 与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回默认值。如果未传入 default 值，则在发生错误时返回 0。语法

toUInt256OrDefault(expr[, default])

参数

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

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

Query

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

Response

转换失败

Query

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

Response

toUInt256OrNull

引入版本：v20.8.0 与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回 NULL。支持的参数：

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

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

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

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

另请参阅：

toUInt256。
toUInt256OrZero。
toUInt256OrDefault。

语法

toUInt256OrNull(x)

参数

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

返回值 返回 UInt256 类型的值；如果转换失败，则返回 NULL。UInt256 或 NULL 示例 使用示例

Query

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

toUInt256OrZero

引入于：v20.8.0 与 toUInt256 类似，此函数会将输入值转换为 UInt256 类型的值，但如果发生错误，则返回 0。支持的参数：

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

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

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

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

另请参见：

toUInt256。
toUInt256OrNull。
toUInt256OrDefault。

语法

toUInt256OrZero(x)

参数

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

返回值 返回 UInt256 类型的值；如果转换失败，则返回 0。UInt256 示例 使用示例

Query

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

toUInt32

引入于：v1.1.0 将输入值转换为 UInt32 类型的值。如果出错，则会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

另请参见：

toUInt32OrZero。
toUInt32OrNull。
toUInt32OrDefault。

语法

toUInt32(expr)

参数

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

返回值 返回一个 32 位无符号整数。UInt32 示例 用法示例

Query

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Response

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

toUInt32OrDefault

Introduced in: v21.11.0 与 toUInt32 类似，此函数会将输入值转换为 UInt32 类型的值，但发生错误时会返回默认值。如果未传入 default 值，则发生错误时返回 0。 Syntax

toUInt32OrDefault(expr[, default])

参数

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

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

Query

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

Response

转换失败

Query

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

Response

toUInt32OrNull

引入于：v1.1.0 与 toUInt32 类似，此函数会将输入值转换为 UInt32 类型的值，但如果发生错误，则返回 NULL。支持的参数：

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

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

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

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

另请参见：

toUInt32。
toUInt32OrZero。
toUInt32OrDefault。

语法

toUInt32OrNull(x)

参数

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

返回值 返回 UInt32 类型的值；如果转换失败，则返回 NULL。UInt32 或 NULL 示例 使用示例

Query

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

Response

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

toUInt32OrZero

引入版本：v1.1.0 与 toUInt32 类似，此函数会将输入值转换为 UInt32 类型的值，但如果发生错误，则返回 0。支持的参数：

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

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

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

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

另请参见：

toUInt32。
toUInt32OrNull。
toUInt32OrDefault。

语法

toUInt32OrZero(x)

参数

x — 数值的 String 表示形式。String

返回值 返回 UInt32 类型的值；如果转换失败，则返回 0。UInt32 示例 使用示例

Query

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

Response

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

toUInt64

引入版本：v1.1.0 将输入值转换为 UInt64 类型的值。发生错误时会抛出异常。支持的参数：

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

不支持的类型：

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

如果输入值超出 UInt64 的取值范围，结果会发生上溢或下溢。这不视为错误。例如：SELECT toUInt64(18446744073709551616) == 0;

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

另请参见：

toUInt64OrZero。
toUInt64OrNull。
toUInt64OrDefault。

语法

toUInt64(expr)

参数

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

返回值 返回一个 64 位无符号整数值。UInt64 示例 使用示例

Query

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Response

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

toUInt64OrDefault

首次引入版本：v21.11.0 与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误，则返回默认值。如果未传入 default 值，则发生错误时返回 0。语法

toUInt64OrDefault(expr[, default])

参数

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

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

Query

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

Response

转换失败

Query

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

Response

toUInt64OrNull

引入于：v1.1.0 与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误则返回 NULL。支持的参数：

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

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

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

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

另请参见：

toUInt64。
toUInt64OrZero。
toUInt64OrDefault。

语法

toUInt64OrNull(x)

参数

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

返回值 返回 UInt64 类型的值；如果转换失败，则返回 NULL。UInt64 或 NULL 示例 使用示例

Query

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

toUInt64OrZero

引入版本：v1.1.0 与 toUInt64 类似，此函数会将输入值转换为 UInt64 类型的值，但如果发生错误，则返回 0。支持的参数：

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

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

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

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

另请参见：

toUInt64。
toUInt64OrNull。
toUInt64OrDefault。

语法

toUInt64OrZero(x)

参数

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

返回值 返回 UInt64 类型的值；如果转换失败，则返回 0。UInt64 示例 使用示例

Query

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

toUInt8

Introduced in: v1.1.0 将输入值转换为 UInt8 类型的值。发生错误时会抛出异常。支持的参数：

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

不支持的参数：

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

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

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

另请参见：

toUInt8OrZero。
toUInt8OrNull。
toUInt8OrDefault。

语法

toUInt8(expr)

参数

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

返回值 返回 8 位无符号整数值。UInt8 示例 使用示例

Query

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Response

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

toUInt8OrDefault

Introduced in：v21.11.0 与 toUInt8 类似，此函数会将输入值转换为 UInt8 类型的值，但如果发生错误，则返回默认值。如果未传入 default 值，则发生错误时返回 0。 Syntax

toUInt8OrDefault(expr[, default])

参数

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

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

Query

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

Response

转换失败

Query

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

Response

toUInt8OrNull

引入版本：v1.1.0 与 toUInt8 类似，此函数将输入值转换为 UInt8 类型的值，但在出错时返回 NULL。支持的参数：

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

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

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

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

另请参见：

toUInt8。
toUInt8OrZero。
toUInt8OrDefault。

语法

toUInt8OrNull(x)

参数

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

返回值 返回类型为 UInt8 的值；如果转换失败，则返回 NULL。UInt8 或 NULL 示例 使用示例

Query

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Response

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

toUInt8OrZero

首次引入于：v1.1.0 与 toUInt8 类似，此函数将输入值转换为 UInt8 类型的值，但在发生错误时返回 0。支持的参数：

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

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

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

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

另请参阅：

toUInt8。
toUInt8OrNull。
toUInt8OrDefault。

语法

toUInt8OrZero(x)

参数

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

返回值 返回 UInt8 类型的值；如果转换失败，则返回 0。UInt8 示例 用法示例

Query

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

Response

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

toUUID

引入版本：v1.1.0 将 String 类型的值转换为 UUID 值。语法

toUUID(string)

参数

string — 字符串形式的 UUID。String 或 FixedString

返回值 根据 UUID 的字符串表示形式返回一个 UUID。UUID 示例 使用示例

Query

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

Response

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrZero

Introduced in: v20.12.0 将输入值转换为 UUID 类型的值，但如果发生错误，则返回零 UUID。与 toUUID 类似，但在转换出错时会返回零 UUID (00000000-0000-0000-0000-000000000000) ，而不是抛出异常。支持的参数：

标准格式 UUID 的字符串表示形式 (8-4-4-4-12 个十六进制数字) 。
不带连字符的 UUID 字符串表示形式 (32 个十六进制数字) 。

不支持的参数 (返回零 UUID) ：

无效的字符串格式。
非字符串类型。

Syntax

toUUIDOrZero(x)

参数

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

返回值 成功时返回 UUID 值，否则返回零 UUID (00000000-0000-0000-0000-000000000000) 。UUID 示例 使用示例

Query

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

Response

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

toUnixTimestamp64Micro

引入版本：v20.5.0 将 DateTime64 转换为具有固定微秒精度的 Int64 值。输入值会根据其精度相应地进行放大或缩小。

输出值以 UTC 为基准，而不是以输入值的时区为基准。

语法

toUnixTimestamp64Micro(value)

参数

value — 任意精度的 DateTime64 类型值。DateTime64

返回值 返回以微秒为单位的 Unix 时间戳。Int64 示例 使用示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

Response

┌─toUnixTimestamp64Micro(dt64)─┐
│               1739489491011123 │
└────────────────────────────────┘

toUnixTimestamp64Milli

引入版本：v20.5.0 将 DateTime64 转换为具有固定毫秒精度的 Int64 值。输入值会根据其精度按相应比例放大或缩小。

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Milli(value)

参数

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

返回值 返回一个以毫秒为单位的 Unix 时间戳。Int64 示例 用法示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

Response

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

toUnixTimestamp64Nano

引入版本：v20.5.0 将 DateTime64 转换为具有固定纳秒精度的 Int64 值。输入值会根据其精度相应放大或缩小。

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Nano(value)

参数

value — 任意精度的 DateTime64 值。DateTime64

返回值 返回以纳秒为单位的 Unix 时间戳。Int64 示例 使用示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

Response

┌─toUnixTimestamp64Nano(dt64)────┐
│            1739489491011123456 │
└────────────────────────────────┘

toUnixTimestamp64Second

引入版本：v24.12.0 将 DateTime64 转换为具有固定秒级精度的 Int64 值。输入值会根据其精度相应按比例放大或缩小。

输出值是相对于 UTC 的，而不是相对于输入值的时区。

语法

toUnixTimestamp64Second(value)

参数

value — 任意精度的 DateTime64 类型值。DateTime64

返回值 返回以秒为单位的 Unix 时间戳。Int64 示例 使用示例

Query

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

Response

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘

最后修改于 2026年6月19日

ULIDs用于处理 ULID 的函数文档

​数据转换中的常见问题

​toString 函数说明

​关于 toDate/toDateTime 函数的说明

​CAST

​DATE

​accurateCast

​accurateCastOrDefault

​accurateCastOrNull

​formatRow

​formatRowNoNewline

​fromUnixTimestamp64Micro

​fromUnixTimestamp64Milli

​fromUnixTimestamp64Nano

​fromUnixTimestamp64Second

​parseDateTime

​parseDateTime32BestEffort

​parseDateTime32BestEffortOrNull

​parseDateTime32BestEffortOrZero

​parseDateTime64

​parseDateTime64BestEffort

​parseDateTime64BestEffortOrNull

​parseDateTime64BestEffortOrZero

​parseDateTime64BestEffortUS

​parseDateTime64BestEffortUSOrNull

​parseDateTime64BestEffortUSOrZero

​parseDateTime64InJodaSyntax

​parseDateTime64InJodaSyntaxOrNull

​parseDateTime64InJodaSyntaxOrZero

​parseDateTime64OrNull

​parseDateTime64OrZero

​parseDateTimeBestEffort

​parseDateTimeBestEffortOrNull

​parseDateTimeBestEffortOrZero

​parseDateTimeBestEffortUS

​parseDateTimeBestEffortUSOrNull

​parseDateTimeBestEffortUSOrZero

​parseDateTimeInJodaSyntax

​parseDateTimeInJodaSyntaxOrNull

​parseDateTimeInJodaSyntaxOrZero

​parseDateTimeOrNull

​parseDateTimeOrZero

​reinterpret

​reinterpretAsDate

​reinterpretAsDateTime

​reinterpretAsFixedString

​reinterpretAsFloat32

​reinterpretAsFloat64

​reinterpretAsInt128

​reinterpretAsInt16

​reinterpretAsInt256

​reinterpretAsInt32

​reinterpretAsInt64

​reinterpretAsInt8

​reinterpretAsString

​reinterpretAsUInt128

​reinterpretAsUInt16

​reinterpretAsUInt256

​reinterpretAsUInt32

​reinterpretAsUInt64

​reinterpretAsUInt8

​reinterpretAsUUID

​toBFloat16

​toBFloat16OrNull

​toBFloat16OrZero

​toBool

​toDate

​toDate32

​toDate32OrDefault

​toDate32OrNull

​toDate32OrZero

​toDateOrDefault

​toDateOrNull

​toDateOrZero

​toDateTime

​toDateTime32

​toDateTime64

​toDateTime64OrDefault

​toDateTime64OrNull

​toDateTime64OrZero

​toDateTimeOrDefault

数据转换中的常见问题

`toString` 函数说明

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

CAST

DATE

accurateCast

accurateCastOrDefault

accurateCastOrNull

formatRow

formatRowNoNewline

fromUnixTimestamp64Micro

fromUnixTimestamp64Milli

fromUnixTimestamp64Nano

fromUnixTimestamp64Second

parseDateTime

parseDateTime32BestEffort

parseDateTime32BestEffortOrNull

parseDateTime32BestEffortOrZero

parseDateTime64

parseDateTime64BestEffort

parseDateTime64BestEffortOrNull

parseDateTime64BestEffortOrZero

parseDateTime64BestEffortUS

parseDateTime64BestEffortUSOrNull

parseDateTime64BestEffortUSOrZero

parseDateTime64InJodaSyntax

parseDateTime64InJodaSyntaxOrNull

parseDateTime64InJodaSyntaxOrZero

parseDateTime64OrNull

parseDateTime64OrZero

parseDateTimeBestEffort

parseDateTimeBestEffortOrNull

parseDateTimeBestEffortOrZero

parseDateTimeBestEffortUS

parseDateTimeBestEffortUSOrNull

parseDateTimeBestEffortUSOrZero

parseDateTimeInJodaSyntax

parseDateTimeInJodaSyntaxOrNull

parseDateTimeInJodaSyntaxOrZero

parseDateTimeOrNull

parseDateTimeOrZero

reinterpret

reinterpretAsDate

reinterpretAsDateTime

reinterpretAsFixedString

reinterpretAsFloat32

reinterpretAsFloat64

reinterpretAsInt128

reinterpretAsInt16

reinterpretAsInt256

reinterpretAsInt32

reinterpretAsInt64

reinterpretAsInt8

reinterpretAsString

reinterpretAsUInt128

reinterpretAsUInt16

reinterpretAsUInt256

reinterpretAsUInt32

reinterpretAsUInt64

reinterpretAsUInt8

reinterpretAsUUID

toBFloat16

toBFloat16OrNull

toBFloat16OrZero

toBool

toDate

toDate32

toDate32OrDefault

toDate32OrNull

toDate32OrZero

toDateOrDefault

toDateOrNull

toDateOrZero

toDateTime

toDateTime32

toDateTime64

toDateTime64OrDefault

toDateTime64OrNull

toDateTime64OrZero

toDateTimeOrDefault