类型转换函数

数据转换的常见问题

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++ 中不同数值类型之间的赋值相同的规则。

示例

查询

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

结果

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

另请参阅 toUnixTimestamp 函数。

CAST

引入于：v1.1

将值转换为指定的数据类型。与 reinterpret 函数不同，CAST 尝试在目标类型中生成相同的值。如果不可能，则会引发异常。

语法

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

参数

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

返回值

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

示例

基本用法

SELECT CAST(42, 'String')

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

使用 AS 语法

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

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

使用 :: 语法

SELECT '123'::UInt32

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

accurateCast

引入于：v1.1

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

此函数比常规 CAST 更安全，因为它防止了精度损失和无效转换。

语法

accurateCast(x, T)

参数

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

返回值

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

示例

成功转换

SELECT accurateCast(42, 'UInt16')

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

字符串转换为数字

SELECT accurateCast('123.45', 'Float64')

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

accurateCastOrDefault

引入于：v21.1

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

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

语法

accurateCastOrDefault(x, T[, default_value])

参数

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

返回值

返回转换为目标数据类型的值，或者如果转换不可能则返回默认值。 Any

示例

成功转换

SELECT accurateCastOrDefault(42, 'String')

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

使用显式默认值转换失败

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

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

使用隐式默认值转换失败

SELECT accurateCastOrDefault('abc', 'UInt32')

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

accurateCastOrNull

引入于：v1.1

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

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

语法

accurateCastOrNull(x, T)

参数

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

返回值

返回转换为目标数据类型的值，或者如果转换不可能则返回 NULL。 Any

示例

成功转换

SELECT accurateCastOrNull(42, 'String')

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

转换失败返回 NULL

SELECT accurateCastOrNull('abc', 'UInt32')

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

formatRow

引入于：v20.7

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

注意

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

语法

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

参数

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

返回值

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

示例

基本用法

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

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

使用自定义格式

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

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

formatRowNoNewline

引入于：v20.7

与 formatRow 相同，但会删除每一行的换行符。

通过给定的格式将任意表达式转换为字符串，但会删除结果中的任何尾随换行符。

语法

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

参数

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

返回值

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

示例

基本用法

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

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

fromUnixTimestamp64Micro

引入于：v20.5

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

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

语法

fromUnixTimestamp64Micro(value[, timezone])

参数

value — 微秒中的 Unix 时间戳。 Int64
timezone — 可选。返回值的时区。 String

返回值

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

示例

使用示例

SELECT fromUnixTimestamp64Micro(1640995200123456)

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

fromUnixTimestamp64Milli

引入于：v20.5

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

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

语法

fromUnixTimestamp64Milli(value[, timezone])

参数

value — 毫秒中的 Unix 时间戳。 Int64
timezone — 可选。返回值的时区。 String

返回值

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

示例

使用示例

SELECT fromUnixTimestamp64Milli(1640995200123)

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

fromUnixTimestamp64Nano

引入于：v20.5

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

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

注意

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

语法

fromUnixTimestamp64Nano(value[, timezone])

参数

value — 纳秒中的 Unix 时间戳。 Int64
timezone — 可选。返回值的时区。 String

返回值

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

示例

使用示例

SELECT fromUnixTimestamp64Nano(1640995200123456789)

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

fromUnixTimestamp64Second

引入于：v24.12

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

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

语法

fromUnixTimestamp64Second(value[, timezone])

参数

value — 秒中的 Unix 时间戳。 Int64
timezone — 可选。返回值的时区。 String

返回值

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

示例

使用示例

SELECT fromUnixTimestamp64Second(1640995200)

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

parseDateTime

引入于: v23.3

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

此函数是 formatDateTime 的反函数。它使用格式字符串解析 String 参数。返回 DateTime 类型。

语法

parseDateTime(time_string, format[, timezone])

别名：TO_UNIXTIME

参数

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

返回值

返回根据 MySQL 样式格式字符串解析的 DateTime。 DateTime

示例

使用示例

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

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

parseDateTime32BestEffort

引入于：v20.9

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

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

语法

parseDateTime32BestEffort(time_string[, time_zone])

参数

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

返回值

返回作为 DateTime 的 time_string。 DateTime

示例

使用示例

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

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

使用时区

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

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

Unix 时间戳

SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort

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

parseDateTime32BestEffortOrNull

引入于：v20.9

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

语法

parseDateTime32BestEffortOrNull(time_string[, time_zone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime32BestEffortOrZero

引入于：v20.9

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

语法

parseDateTime32BestEffortOrZero(time_string[, time_zone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64

引入于：v24.11

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

此函数是 DateTime64 的 formatDateTime 的反函数。它使用格式字符串解析 String 参数。返回一个 DateTime64 类型，可以表示从 1900 年到 2299 年具有亚秒精度的日期。

语法

parseDateTime64(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64BestEffort

引入于: v20.1

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

语法

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

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64BestEffortOrNull

引入于: v20.1

与 parseDateTime64BestEffort 相同，但当遇到无法处理的日期格式时，它返回 NULL。

语法

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

参数

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

返回值

返回将 time_string 转换为 DateTime64 的结果，如果输入无法解析则返回 NULL。 DateTime64 或 NULL

示例

使用示例

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

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

parseDateTime64BestEffortOrZero

引入于: v20.1

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

语法

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

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64BestEffortUS

引入于：v22.8

与 parseDateTime64BestEffort 相同，但如果存在歧义，此函数更喜欢美国日期格式 (MM/DD/YYYY 等)。

语法

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

参数

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

返回值

返回将 time_string 转换为 DateTime64 的结果，在歧义情况下使用美国日期格式偏好。 DateTime64

示例

使用示例

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

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

parseDateTime64BestEffortUSOrNull

引入于：v22.8

与 parseDateTime64BestEffort 相同，但如果存在歧义，此函数更喜欢美国日期格式 (MM/DD/YYYY 等)，并且当遇到无法处理的日期格式时，它返回 NULL。

语法

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

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64BestEffortUSOrZero

引入于：v22.8

与 parseDateTime64BestEffort 相同，但如果存在歧义，此函数更喜欢美国日期格式 (MM/DD/YYYY 等)，并且当遇到无法处理的日期格式时，它返回零日期或零日期时间。

语法

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

参数

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

返回值

返回将 time_string 转换为 DateTime64 的结果，使用美国格式偏好，如果输入无法解析则返回零日期/时间 (1970-01-01 00:00:00.000)。 DateTime64

示例

使用示例

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

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

parseDateTime64InJodaSyntax

引入于：v24.10

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

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

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

语法

parseDateTime64InJodaSyntax(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64InJodaSyntaxOrNull

引入于：v24.10

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

语法

parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64InJodaSyntaxOrZero

引入于：v24.10

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

语法

parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64OrNull

引入于：v24.11

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

语法

parseDateTime64OrNull(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTime64OrZero

引入于：v24.11

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

语法

parseDateTime64OrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeBestEffort

引入于：v1.1

将 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
time_zone — 可选。根据 time_string 解析的时间区。 String

返回值

返回作为 DateTime 的 time_string。 DateTime

示例

使用示例

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

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

使用时区

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

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

Unix 时间戳

SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort

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

parseDateTimeBestEffortOrNull

引入于：v1.1

与 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
time_zone — 可选。根据 time_string 解析的时间区。 String

返回值

返回 time_string 作为 DateTime，如果输入无法解析则返回 NULL。 DateTime 或 NULL

示例

使用示例

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

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

parseDateTimeBestEffortOrZero

引入于：v1.1

与 parseDateTimeBestEffort 相同，但当遇到无法处理的日期格式时，它返回零日期或零日期时间。该函数解析 ISO 8601、RFC 1123 - 5.2.14 RFC-822 日期和时间规范、ClickHouse 的和其他一些日期和时间格式。

支持的非标准格式

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

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

语法

parseDateTimeBestEffortOrZero(time_string[, time_zone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeBestEffortUS

引入于：v1.1

此函数对于 ISO 日期格式的行为类似于 parseDateTimeBestEffort，例如 YYYY-MM-DD hh:mm:ss，以及其他可以明确提取月份和日期组件的日期格式，例如 YYYYMMDDhhmmss、YYYY-MM、DD hh 或 YYYY-MM-DD hh:mm:ss ±h:mm。如果无法明确提取月份和日期组件，例如 MM/DD/YYYY、MM-DD-YYYY 或 MM-DD-YY，则它优先使用美国日期格式，而不是 DD/MM/YYYY、DD-MM-YYYY 或 DD-MM-YY。作为前述语句的例外，如果月份大于 12 且小于或等于 31，则此函数回退到 parseDateTimeBestEffort 的行为，例如 15/08/2020 将被解析为 2020-08-15。

语法

parseDateTimeBestEffortUS(time_string[, time_zone])

参数

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

返回值

以美国日期格式偏好处理模糊情况，将 time_string 作为 DateTime 返回。 DateTime

示例

使用示例

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

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

parseDateTimeBestEffortUSOrNull

引入于：v1.1

与 parseDateTimeBestEffortUS 函数相同，但如果遇到无法处理的日期格式，则返回 NULL。

此函数对于 ISO 日期格式的行为类似于 parseDateTimeBestEffort，但在模糊情况下优先使用美国日期格式，并且在解析错误时返回 NULL。

语法

parseDateTimeBestEffortUSOrNull(time_string[, time_zone])

参数

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

返回值

以美国格式偏好将 time_string 作为 DateTime 返回，如果无法解析输入，则返回 NULL。 DateTime 或 NULL

示例

使用示例

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

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

parseDateTimeBestEffortUSOrZero

引入于：v1.1

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

此函数对于 ISO 日期格式的行为类似于 parseDateTimeBestEffort，但在模糊情况下优先使用美国日期格式，并且在解析错误时返回零值。

语法

parseDateTimeBestEffortUSOrZero(time_string[, time_zone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeInJodaSyntax

引入于: v23.3

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

此函数是 formatDateTimeInJodaSyntax 的反函数。它使用 Joda 样式的格式字符串解析 String 参数。返回 DateTime 类型。

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

语法

parseDateTimeInJodaSyntax(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeInJodaSyntaxOrNull

引入于: v23.3

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

语法

parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeInJodaSyntaxOrZero

引入于: v23.3

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

语法

parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeOrNull

引入于: v23.3

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

语法

parseDateTimeOrNull(time_string, format[, timezone])

别名: str_to_date

参数

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

返回值

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

示例

使用示例

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

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

parseDateTimeOrZero

引入于: v23.3

与 parseDateTime 相同，但如果遇到无法解析的日期格式，则返回零日期。

语法

parseDateTimeOrZero(time_string, format[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

reinterpret

引入于：v1.1

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

语法

reinterpret(x, type)

参数

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

返回值

目标类型值。 Any

示例

使用示例

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

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

数组示例

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

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

reinterpretAsDate

引入于：v1.1

将输入值重新解释为 Date 值（假定小端字节序），即自 Unix epoch 1970-01-01 以来的天数。

语法

reinterpretAsDate(x)

参数

x — 自 Unix Epoch 以来的天数。 (U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

Date。 Date

示例

使用示例

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

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

reinterpretAsDateTime

引入于：v1.1

将输入值重新解释为 DateTime 值（假定小端字节序），即自 Unix epoch 1970-01-01 以来的秒数。

语法

reinterpretAsDateTime(x)

参数

x — 自 Unix Epoch 以来的秒数。 (U)Int* 或 Float* 或 Date 或 DateTime 或 UUID 或 String 或 FixedString

返回值

日期和时间。 DateTime

示例

使用示例

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

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

reinterpretAsFixedString

引入于：v1.1

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

语法

reinterpretAsFixedString(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsFloat32

引入于：v1.1

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

语法

reinterpretAsFloat32(x)

参数

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

返回值

返回重新解释的值 x。 Float32

示例

使用示例

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

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

reinterpretAsFloat64

引入于：v1.1

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

语法

reinterpretAsFloat64(x)

参数

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

返回值

返回重新解释的值 x。 Float64

示例

使用示例

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

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

reinterpretAsInt128

引入于：v1.1

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

语法

reinterpretAsInt128(x)

参数

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

返回值

返回重新解释的值 x。 Int128

示例

使用示例

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

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

reinterpretAsInt16

引入于：v1.1

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

语法

reinterpretAsInt16(x)

参数

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

返回值

返回重新解释的值 x。 Int16

示例

使用示例

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

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

reinterpretAsInt256

引入于：v1.1

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

语法

reinterpretAsInt256(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsInt32

引入于：v1.1

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

语法

reinterpretAsInt32(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsInt64

引入于：v1.1

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

语法

reinterpretAsInt64(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsInt8

引入于：v1.1

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

语法

reinterpretAsInt8(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsString

引入于：v1.1

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

语法

reinterpretAsString(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUInt128

引入于：v1.1

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

语法

reinterpretAsUInt128(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUInt16

引入于：v1.1

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

语法

reinterpretAsUInt16(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUInt256

引入于：v1.1

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

语法

reinterpretAsUInt256(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUInt32

引入于：v1.1

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

语法

reinterpretAsUInt32(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUInt64

引入于：v1.1

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

语法

reinterpretAsUInt64(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUInt8

引入于：v1.1

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

语法

reinterpretAsUInt8(x)

参数

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

返回值

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

示例

使用示例

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

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

reinterpretAsUUID

引入于：v1.1

接受一个 16 字节的字符串，并以小端字节序解释每个 8 字节的半部分，返回一个 UUID。如果字符串不够长，则该函数将假定字符串用必要的空字节填充到末尾。如果字符串长于 16 字节，则忽略末尾的额外字节。

语法

reinterpretAsUUID(fixed_string)

参数

fixed_string — 大端字节字符串。 FixedString

返回值

UUID 类型值。 UUID

示例

字符串到 UUID

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

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

toBFloat16

引入于：v1.1

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

参见

toBFloat16OrZero.
toBFloat16OrNull.

语法

toBFloat16(expr)

参数

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

返回值

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

示例

使用示例

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

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

toBFloat16OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toBFloat16.
toBFloat16OrZero.

语法

toBFloat16OrNull(x)

参数

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

返回值

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

示例

使用示例

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

\N
12.25
12.3125

toBFloat16OrZero

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toBFloat16.
toBFloat16OrNull.

语法

toBFloat16OrZero(x)

参数

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

返回值

返回一个 16 位脑浮点值，否则为 0。 BFloat16

示例

使用示例

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

0
12.25
12.3125

toBool

引入于：v22.2

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

语法

toBool(expr)

参数

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

返回值

根据参数的评估结果返回 true 或 false。 Bool

示例

使用示例

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

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

toDate

引入于：v1.1

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

语法

toDate(x)

参数

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

返回值

返回转换后的输入值。 Date

示例

字符串到日期转换

SELECT toDate('2025-04-15')

2025-04-15

DateTime 到日期转换

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

2025-04-15

整数到日期转换

SELECT toDate(20297)

2025-07-28

toDate32

引入于: v21.9

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

语法

toDate32(expr)

参数

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

返回值

返回日历日期。 Date32

示例

在范围内

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

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

超出范围

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

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

toDate32OrDefault

引入于：v21.11

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

语法

toDate32OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 Date32

返回值

如果成功，则返回 Date32 类型的值，否则返回传递的默认值或 1900-01-01。 Date32

示例

成功转换

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

1930-01-01

转换失败

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

2020-01-01

toDate32OrNull

引入于: v21.9

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

语法

toDate32OrNull(x)

参数

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

返回值

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

示例

使用示例

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

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

toDate32OrZero

引入于: v21.9

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

参见

toDate32
toDate32OrNull
toDate32OrDefault

语法

toDate32OrZero(x)

参数

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

返回值

如果成功，则返回 Date32 值，否则返回 Date32 的下边界 (1900-01-01)。 Date32

示例

使用示例

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

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

toDateOrDefault

引入于：v21.11

类似于 toDate，但如果失败，则返回默认值，该值是第二个参数（如果指定），或者 Date 的下边界。

语法

toDateOrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 Date

返回值

如果成功，则返回 Date 类型的值，否则返回传递的默认值或 1970-01-01（如果未传递）。 Date

示例

成功转换

SELECT toDateOrDefault('2022-12-30')

2022-12-30

转换失败

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

2023-01-01

toDateOrNull

引入于：v1.1

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

语法

toDateOrNull(x)

参数

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

返回值

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

示例

使用示例

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

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

toDateOrZero

引入于：v1.1

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

参见

toDate
toDateOrNull
toDateOrDefault

语法

toDateOrZero(x)

参数

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

返回值

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

示例

使用示例

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

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

toDateTime

引入于：v1.1

将输入值转换为 DateTime 类型。

注意

如果 expr 是数字，则将其解释为自 Unix Epoch 开始的秒数（作为 Unix 时间戳）。如果 expr 是 String，则可以将其解释为 Unix 时间戳或日期/日期与时间的字符串表示形式。因此，由于歧义，明确禁止解析短数字字符串的表示形式（最多 4 位），例如，字符串 '1999' 既可以是年份（日期/日期时间的不完整字符串表示形式），也可以是 Unix 时间戳。允许更长的数字字符串。

语法

toDateTime(expr[, time_zone])

参数

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

返回值

返回日期时间。 DateTime

示例

使用示例

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

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

toDateTime32

引入于：v20.9

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

语法

toDateTime32(x[, timezone])

参数

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

返回值

返回转换后的输入值。 DateTime

示例

该值在范围内

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

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

作为具有精度的十进制数

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

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

使用时区

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

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

toDateTime64

引入于: v20.1

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

语法

toDateTime64(expr, scale[, timezone])

参数

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

返回值

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

示例

该值在范围内

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

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

作为具有精度的十进制数

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

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

使用时区

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

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

toDateTime64OrDefault

引入于：v21.11

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

语法

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

参数

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

返回值

如果成功，则返回 DateTime64 类型的值，否则返回传递的默认值或 1970-01-01 00:00:00.000（如果未传递）。 DateTime64

示例

成功转换

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

1976-10-18 00:00:00.300

转换失败

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

2000-12-31 23:00:00.000

toDateTime64OrNull

引入于: v20.1

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

语法

toDateTime64OrNull(x)

参数

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

返回值

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

示例

使用示例

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

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

toDateTime64OrZero

引入于: v20.1

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

参见

toDateTime64.
toDateTime64OrNull.
toDateTime64OrDefault.

语法

toDateTime64OrZero(x)

参数

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

返回值

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

示例

使用示例

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

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

toDateTimeOrDefault

引入于：v21.11

类似于 toDateTime，但如果失败，则返回默认值，该值是第三个参数（如果指定），或者 DateTime 的下边界。

语法

toDateTimeOrDefault(expr[, timezone, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
timezone — 可选。时区。 String
default — 可选。如果解析不成功，则返回的默认值。 DateTime

返回值

如果成功，则返回 DateTime 类型的值，否则返回传递的默认值或 1970-01-01 00:00:00（如果未传递）。 DateTime

示例

成功转换

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

2022-12-30 13:44:17

转换失败

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

2023-01-01 00:00:00

toDateTimeOrNull

引入于：v1.1

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

语法

toDateTimeOrNull(x)

参数

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

返回值

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

示例

使用示例

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

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

toDateTimeOrZero

引入于：v1.1

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

语法

toDateTimeOrZero(x)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal128

引入于：v18.12

将输入值转换为具有比例因子 S 的 Decimal(38, S) 类型的值。如果发生错误，则抛出异常。

支持的参数

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

不支持的参数

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

注意

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

注意

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

语法

toDecimal128(expr, S)

参数

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

返回值

如果成功，则返回 Decimal(38, S) 类型的值 Decimal128(S)

示例

使用示例

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

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

toDecimal128OrDefault

引入于：v21.11

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

语法

toDecimal128OrDefault(expr, S[, default])

参数

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

返回值

如果成功，则返回 Decimal(38, S) 类型的值，否则返回传递的默认值或 0（如果未传递）。 Decimal128(S)

示例

成功转换

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

0.023809523809523808

转换失败

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

-1

toDecimal128OrNull

引入于: v20.1

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

支持的参数

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

不支持的参数（返回 NULL）

类型为 Float* 的值 NaN 和 Inf 的字符串表示形式（不区分大小写）。
二进制和十六进制值的字符串表示形式。
超过 Decimal128 边界：(-1*10^(38 - S), 1*10^(38 - S)) 的值。

参见

toDecimal128.
toDecimal128OrZero.
toDecimal128OrDefault.

语法

toDecimal128OrNull(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal128OrZero

引入于: v20.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

如果输入值超过 Decimal128 的边界：(-1*10^(38 - S), 1*10^(38 - S))，则该函数返回 0。

语法

toDecimal128OrZero(expr, S)

参数

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

返回值

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

示例

基本用法

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

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

toDecimal256

引入于：v20.8

将输入值转换为具有比例因子 S 的 Decimal(76, S) 类型的值。如果发生错误，则抛出异常。

支持的参数

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

不支持的参数

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

注意

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

注意

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

语法

toDecimal256(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal256OrDefault

引入于：v21.11

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

语法

toDecimal256OrDefault(expr, S[, default])

参数

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

返回值

如果成功，则返回 Decimal(76, S) 类型的值，否则返回传递的默认值或 0（如果未传递）。 Decimal256(S)

示例

成功转换

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

0.023809523809523808

转换失败

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

-1

toDecimal256OrNull

引入于：v20.8

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

支持的参数

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

不支持的参数（返回 NULL）

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

参见

toDecimal256.
toDecimal256OrZero.
toDecimal256OrDefault.

语法

toDecimal256OrNull(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal256OrZero

引入于：v20.8

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

支持的参数

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

不支持的参数（返回 0）

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

注意

如果输入值超过 Decimal256 的边界：(-1*10^(76 - S), 1*10^(76 - S))，则该函数返回 0。

参见

toDecimal256.
toDecimal256OrNull.
toDecimal256OrDefault.

语法

toDecimal256OrZero(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal32

引入于：v18.12

将输入值转换为具有比例因子 S 的 Decimal(9, S) 类型的值。如果发生错误，则抛出异常。

支持的参数

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

不支持的参数

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

注意

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

注意

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

语法

toDecimal32(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal32OrDefault

引入于：v21.11

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

语法

toDecimal32OrDefault(expr, S[, default])

参数

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

返回值

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

示例

成功转换

SELECT toDecimal32OrDefault(toString(0.0001), 5)

0.0001

转换失败

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

-1

toDecimal32OrNull

引入于: v20.1

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

支持的参数

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

不支持的参数（返回 NULL）

类型为 Float* 的值 NaN 和 Inf 的字符串表示形式（不区分大小写）。
二进制和十六进制值的字符串表示形式。
超过 Decimal32 边界：(-1*10^(9 - S), 1*10^(9 - S)) 的值。

参见

toDecimal32.
toDecimal32OrZero.
toDecimal32OrDefault.

语法

toDecimal32OrNull(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal32OrZero

引入于: v20.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

如果输入值超过 Decimal32 的边界：(-1*10^(9 - S), 1*10^(9 - S))，则该函数返回 0。

语法

toDecimal32OrZero(expr, S)

参数

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

返回值

如果成功，则返回 Decimal(9, S) 值，否则返回 0。 Decimal32(S)

示例

使用示例

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

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

toDecimal64

引入于：v18.12

将输入值转换为类型为 Decimal(18, S) 且刻度为 S 的值。如果发生错误，则抛出异常。

支持的参数

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

不支持的参数

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

注意

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

注意

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

语法

toDecimal64(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal64OrDefault

引入于：v21.11

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

语法

toDecimal64OrDefault(expr, S[, default])

参数

expr — 数字的字符串表示形式。 String
S — 介于 0 和 18 之间的刻度参数，指定数字的小数部分可以有多少位。 UInt8
default — 可选。如果解析为 Decimal64(S) 类型不成功，则返回的默认值。 Decimal64(S)

返回值

如果成功，则返回 Decimal(18, S) 值，否则返回传递的默认值或 0（如果未传递）。 Decimal64(S)

示例

成功转换

SELECT toDecimal64OrDefault(toString(0.0001), 18)

0.0001

转换失败

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

-1

toDecimal64OrNull

引入于: v20.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

参见

toDecimal64.
toDecimal64OrZero.
toDecimal64OrDefault.

语法

toDecimal64OrNull(expr, S)

参数

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

返回值

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

示例

使用示例

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

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

toDecimal64OrZero

引入于: v20.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toDecimal64.
toDecimal64OrNull.
toDecimal64OrDefault.

语法

toDecimal64OrZero(expr, S)

参数

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

返回值

如果成功，则返回 Decimal(18, S) 值，否则返回 0。 Decimal64(S)

示例

使用示例

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

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

toDecimalString

引入于: v23.3

将数值转换为具有指定小数位数的字符串。

该函数将输入值四舍五入到指定的位数。如果输入值的小数位数少于请求的位数，则结果将用零填充以达到指定的精确小数位数。

语法

toDecimalString(number, scale)

参数

number — 要转换为字符串的数值。可以是任何数值类型 (Int, UInt, Float, Decimal)。 Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64 或 Decimal
scale — 要在小数部分显示的位数。如果需要，结果将四舍五入。 UInt8

返回值

返回具有指定小数位数的数字的字符串表示形式。 String

示例

四舍五入并格式化数字

SELECT toDecimalString(2.1456, 2)

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

用零填充

SELECT toDecimalString(5, 3)

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

不同的数值类型

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

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

toFixedString

引入于：v1.1

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

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

语法

toFixedString(s, N)

参数

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

返回值

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

示例

使用示例

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

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

toFloat32

引入于：v1.1

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

支持的参数

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

不支持的参数

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

参见

toFloat32OrZero.
toFloat32OrNull.
toFloat32OrDefault.

语法

toFloat32(expr)

参数

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

返回值

返回一个 32 位浮点值。 Float32

示例

使用示例

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

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

toFloat32OrDefault

引入于：v21.11

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

语法

toFloat32OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 Float32

返回值

如果成功，则返回 Float32 类型的值，否则返回传递的默认值或 0（如果未传递）。 Float32

示例

成功转换

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

转换失败

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

toFloat32OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

参见

toFloat32.
toFloat32OrZero.
toFloat32OrDefault.

语法

toFloat32OrNull(x)

参数

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

返回值

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

示例

使用示例

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

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

toFloat32OrZero

引入于：v1.1

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

参见

toFloat32.
toFloat32OrNull.
toFloat32OrDefault.

语法

toFloat32OrZero(x)

参数

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

返回值

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

示例

使用示例

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

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

toFloat64

引入于：v1.1

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

支持的参数

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

不支持的参数

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

参见

toFloat64OrZero.
toFloat64OrNull.
toFloat64OrDefault.

语法

toFloat64(expr)

参数

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

返回值

返回一个 64 位浮点值。 Float64

示例

使用示例

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

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

toFloat64OrDefault

引入于：v21.11

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

语法

toFloat64OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 Float64

返回值

如果成功，则返回 Float64 类型的值，否则返回传递的默认值或 0（如果未传递）。 Float64

示例

成功转换

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

转换失败

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

toFloat64OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

参见

toFloat64.
toFloat64OrZero.
toFloat64OrDefault.

语法

toFloat64OrNull(x)

参数

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

返回值

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

示例

使用示例

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

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

toFloat64OrZero

引入于：v1.1

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

参见

toFloat64.
toFloat64OrNull.
toFloat64OrDefault.

语法

toFloat64OrZero(x)

参数

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

返回值

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

示例

使用示例

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

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

toInt128

引入于：v1.1

将输入值转换为 Int128 类型的值。如果发生错误，则抛出异常。该函数使用向零舍入，这意味着它会截断数字的小数部分。

支持的参数

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

不支持的参数

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

注意

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

参见

toInt128OrZero.
toInt128OrNull.
toInt128OrDefault.

语法

toInt128(expr)

参数

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

返回值

返回一个 128 位整数值。 Int128

示例

使用示例

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

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

toInt128OrDefault

引入于：v21.11

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

语法

toInt128OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回一个 Int128 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 Int128

示例

成功转换

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

-128

转换失败

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

-1

toInt128OrNull

引入于：v20.8

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toInt128.
toInt128OrZero.
toInt128OrDefault.

语法

toInt128OrNull(x)

参数

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

返回值

返回一个 Int128 类型的值，否则如果转换不成功，则返回 NULL。 Int128 或 NULL

示例

使用示例

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

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

toInt128OrZero

引入于：v20.8

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

参见

toInt128.
toInt128OrNull.
toInt128OrDefault.

语法

toInt128OrZero(x)

参数

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

返回值

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

示例

使用示例

SELECT toInt128OrZero('123')

转换失败返回零

SELECT toInt128OrZero('abc')

toInt16

引入于：v1.1

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

支持的参数

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

不支持的参数

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

注意

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

注意

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

参见

toInt16OrZero.
toInt16OrNull.
toInt16OrDefault.

语法

toInt16(expr)

参数

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

返回值

返回一个 16 位整数值。 Int16

示例

使用示例

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

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

toInt16OrDefault

引入于：v21.11

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

语法

toInt16OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回一个 Int16 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 Int16

示例

成功转换

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

-16

转换失败

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

-1

toInt16OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toInt16.
toInt16OrZero.
toInt16OrDefault.

语法

toInt16OrNull(x)

参数

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

返回值

返回一个 Int16 类型的值，否则如果转换不成功，则返回 NULL。 Int16 或 NULL

示例

使用示例

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

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

toInt16OrZero

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toInt16.
toInt16OrNull.
toInt16OrDefault.

语法

toInt16OrZero(x)

参数

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

返回值

返回一个 Int16 类型的值，否则如果转换不成功，则返回 0。 Int16

示例

使用示例

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

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

toInt256

引入于：v1.1

将输入值转换为 Int256 类型的值。如果发生错误，则抛出异常。该函数使用向零舍入，这意味着它会截断数字的小数部分。

支持的参数

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

不支持的参数

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

注意

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

参见

toInt256OrZero.
toInt256OrNull.
toInt256OrDefault.

语法

toInt256(expr)

参数

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

返回值

返回一个 256 位整数值。 Int256

示例

使用示例

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

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

toInt256OrDefault

引入于：v21.11

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

语法

toInt256OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回一个 Int256 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 Int256

示例

成功转换

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

-256

转换失败

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

-1

toInt256OrNull

引入于：v20.8

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toInt256.
toInt256OrZero.
toInt256OrDefault.

语法

toInt256OrNull(x)

参数

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

返回值

返回一个 Int256 类型的值，否则如果转换不成功，则返回 NULL。 Int256 或 NULL

示例

使用示例

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

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

toInt256OrZero

引入于：v20.8

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

参见

toInt256.
toInt256OrNull.
toInt256OrDefault.

语法

toInt256OrZero(x)

参数

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

返回值

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

示例

使用示例

SELECT toInt256OrZero('123')

转换失败返回零

SELECT toInt256OrZero('abc')

toInt32

引入于：v1.1

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

支持的参数

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

不支持的参数

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

注意

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

注意

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

参见

toInt32OrZero.
toInt32OrNull.
toInt32OrDefault.

语法

toInt32(expr)

参数

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

返回值

返回一个 32 位整数值。 Int32

示例

使用示例

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

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

toInt32OrDefault

引入于：v21.11

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

语法

toInt32OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回一个 Int32 类型的值，否则返回传递的默认值（如果已传递）或 0（如果未传递）。 Int32

示例

成功转换

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

-32

转换失败

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

-1

toInt32OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toInt32.
toInt32OrZero.
toInt32OrDefault.

语法

toInt32OrNull(x)

参数

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

返回值

返回一个 Int32 类型的值，否则如果转换不成功，则返回 NULL。 Int32 或 NULL

示例

使用示例

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

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

toInt32OrZero

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toInt32.
toInt32OrNull.
toInt32OrDefault.

语法

toInt32OrZero(x)

参数

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

返回值

返回一个 Int32 类型的值，否则如果转换不成功，则返回 0。 Int32

示例

使用示例

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

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

toInt64

引入于：v1.1

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

支持的参数

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

不支持的参数

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

注意

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

注意

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

参见

toInt64OrZero.
toInt64OrNull.
toInt64OrDefault.

语法

toInt64(expr)

参数

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

返回值

返回一个 64 位整数值。 Int64

示例

使用示例

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

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

toInt64OrDefault

引入于：v21.11

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

语法

toInt64OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回 Int64 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 Int64

示例

成功转换

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

-64

转换失败

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

-1

toInt64OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toInt64.
toInt64OrZero.
toInt64OrDefault.

语法

toInt64OrNull(x)

参数

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

返回值

返回 Int64 类型的值，否则如果转换不成功则返回 NULL。 Int64 或 NULL

示例

使用示例

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

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

toInt64OrZero

引入于：v1.1

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

参见

toInt64.
toInt64OrNull.
toInt64OrDefault.

语法

toInt64OrZero(x)

参数

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

返回值

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

示例

使用示例

SELECT toInt64OrZero('123')

转换失败返回零

SELECT toInt64OrZero('abc')

toInt8

引入于：v1.1

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

支持的参数

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

不支持的参数

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

注意

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

注意

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

参见

toInt8OrZero.
toInt8OrNull.
toInt8OrDefault.

语法

toInt8(expr)

参数

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

返回值

返回一个 8 位整数值。 Int8

示例

使用示例

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

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

toInt8OrDefault

引入于：v21.11

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

语法

toInt8OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回 Int8 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 Int8

示例

成功转换

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

-8

转换失败

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

-1

toInt8OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toInt8.
toInt8OrZero.
toInt8OrDefault.

语法

toInt8OrNull(x)

参数

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

返回值

返回 Int8 类型的值，否则如果转换不成功则返回 NULL。 Int8 或 NULL

示例

使用示例

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

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

toInt8OrZero

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toInt8.
toInt8OrNull.
toInt8OrDefault.

语法

toInt8OrZero(x)

参数

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

返回值

返回 Int8 类型的值，否则如果转换不成功则返回 0。 Int8

示例

使用示例

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

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

toInterval

引入于: v25.4

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

此函数提供了一种统一的方式来创建不同类型（秒、分钟、小时、天、周、月、季度、年）的间隔，只需通过指定单位作为字符串参数即可。单位字符串不区分大小写。

这等效于调用特定类型的函数，如 toIntervalSecond、toIntervalMinute、toIntervalDay 等，但允许将单位动态地指定为字符串参数。

语法

toInterval(value, unit)

参数

value — 表示单位数量的数字值。可以是任何数字类型。 Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64
unit — 时间单位。必须是常量字符串。有效值：'nanosecond'、'microsecond'、'millisecond'、'second'、'minute'、'hour'、'day'、'week'、'month'、'quarter'、'year'。 String

返回值

返回指定类型的 Interval 值。结果类型取决于单位：IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter 或 IntervalYear。 Interval

示例

使用不同的单位创建间隔

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

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

在日期算术中使用间隔

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

┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘

动态间隔创建

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

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

toIntervalDay

引入于：v1.1

返回一个包含 n 天的间隔，数据类型为 IntervalDay。

语法

toIntervalDay(n)

参数

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

返回值

返回一个包含 n 天的间隔。 Interval

示例

使用示例

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

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

toIntervalHour

引入于：v1.1

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

语法

toIntervalHour(n)

参数

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

返回值

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

示例

使用示例

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

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

toIntervalMicrosecond

引入于：v22.6

返回一个包含 n 微秒的间隔，数据类型为 IntervalMicrosecond。

语法

toIntervalMicrosecond(n)

参数

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

返回值

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

示例

使用示例

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

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

toIntervalMillisecond

引入于：v22.6

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

语法

toIntervalMillisecond(n)

参数

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

返回值

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

示例

使用示例

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

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

toIntervalMinute

引入于：v1.1

返回一个包含 n 分钟的间隔，数据类型为 IntervalMinute。

语法

toIntervalMinute(n)

参数

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

返回值

返回一个包含 n 分钟的间隔。 Interval

示例

使用示例

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

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

toIntervalMonth

引入于：v1.1

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

语法

toIntervalMonth(n)

参数

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

返回值

返回一个包含 n 个月的间隔。 Interval

示例

使用示例

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

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

toIntervalNanosecond

引入于：v22.6

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

语法

toIntervalNanosecond(n)

参数

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

返回值

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

示例

使用示例

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

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

toIntervalQuarter

引入于：v1.1

返回一个包含 n 个季度的间隔，数据类型为 IntervalQuarter。

语法

toIntervalQuarter(n)

参数

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

返回值

返回一个 n 个季度的区间。 Interval

示例

使用示例

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

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

toIntervalSecond

引入于：v1.1

返回一个 n 秒的区间，数据类型为 IntervalSecond。

语法

toIntervalSecond(n)

参数

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

返回值

返回一个 n 秒的区间。 Interval

示例

使用示例

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

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

toIntervalWeek

引入于：v1.1

返回一个 n 周的区间，数据类型为 IntervalWeek。

语法

toIntervalWeek(n)

参数

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

返回值

返回一个 n 周的区间。 Interval

示例

使用示例

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

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

toIntervalYear

引入于：v1.1

返回一个 n 年的区间，数据类型为 IntervalYear。

语法

toIntervalYear(n)

参数

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

返回值

返回一个 n 年的区间。 Interval

示例

使用示例

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

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

toLowCardinality

引入于：v18.12

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

提示

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

语法

toLowCardinality(expr)

参数

expr — 产生受支持数据类型之一的表达式。 String 或 FixedString 或 Date 或 DateTime 或 (U)Int* 或 Float*

返回值

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

示例

使用示例

SELECT toLowCardinality('1')

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

toString

引入于：v1.1

将值转换为其字符串表示形式。对于 DateTime 参数，该函数可以接受第二个 String 参数，其中包含时区名称。

语法

toString(value[, timezone])

参数

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

返回值

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

示例

使用示例

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

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

toStringCutToZero

引入于：v1.1

接受一个 String 或 FixedString 参数，并返回一个 String，其中包含原始字符串的副本，该副本在第一个空字节处被截断。

空字节 (\0) 被视为字符串终止符。此函数对于处理 C 风格的字符串或在空字节标记有意义内容结尾的二进制数据非常有用。

语法

toStringCutToZero(s)

参数

s — 要处理的 String 或 FixedString。 String 或 FixedString

返回值

返回一个包含第一个空字节之前字符的 String。 String

示例

使用示例

SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')

┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘

toTime

引入于：v1.1

将输入值转换为类型 Time。支持从 String、FixedString、DateTime 或表示午夜后秒数的数字类型进行转换。

语法

toTime(x)

参数

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

返回值

返回转换后的值。 Time

示例

String 到 Time 转换

SELECT toTime('14:30:25')

14:30:25

DateTime 到 Time 转换

SELECT toTime(toDateTime('2025-04-15 14:30:25'))

14:30:25

Integer 到 Time 转换

SELECT toTime(52225)

14:30:25

toTime64

引入于: v25.6

将输入值转换为类型 Time64。支持从 String、FixedString、DateTime64 或表示午夜后微秒数的数字类型进行转换。为时间值提供微秒级精度。

语法

toTime64(x)

参数

x — 输入值进行转换。 String 或 FixedString 或 DateTime64 或 (U)Int* 或 Float*

返回值

返回具有微秒精度的转换后的输入值。 Time64(6)

示例

String 到 Time64 转换

SELECT toTime64('14:30:25.123456')

14:30:25.123456

DateTime64 到 Time64 转换

SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))

14:30:25.123456

Integer 到 Time64 转换

SELECT toTime64(52225123456)

14:30:25.123456

toTime64OrNull

引入于: v25.6

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

参见

toTime64
toTime64OrZero

语法

toTime64OrNull(x)

参数

x — 具有亚秒精度的时间的字符串表示形式。 String

返回值

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

示例

使用示例

SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')

┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│                   12:30:45.123 │                      ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘

toTime64OrZero

引入于: v25.6

将输入值转换为类型 Time64 的值，但在发生错误时返回 00:00:00.000。类似于 toTime64，但在转换错误时返回 00:00:00.000 而不是抛出异常。

语法

toTime64OrZero(x)

参数

x — 具有亚秒精度的时间的字符串表示形式。 String

返回值

如果成功，则返回 Time64 值，否则返回 00:00:00.000。 Time64

示例

使用示例

SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')

┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘

toTimeOrNull

引入于：v1.1

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

参见

toTime
toTimeOrZero

语法

toTimeOrNull(x)

参数

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

返回值

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

示例

使用示例

SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')

┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘

toTimeOrZero

引入于：v1.1

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

语法

toTimeOrZero(x)

参数

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

返回值

如果成功，则返回 Time 值，否则返回 00:00:00。 Time

示例

使用示例

SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')

┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘

toUInt128

引入于：v1.1

将输入值转换为类型 UInt128。发生错误时抛出异常。该函数使用朝零舍入，这意味着它会截断数字的小数部分。

支持的参数

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

不支持的参数

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

注意

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

参见

toUInt128OrZero.
toUInt128OrNull.
toUInt128OrDefault.

语法

toUInt128(expr)

参数

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

返回值

返回一个 128 位无符号整数值。 UInt128

示例

使用示例

SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical

Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128

toUInt128OrDefault

引入于：v21.11

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

语法

toUInt128OrDefault(expr[, default])

参数

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

返回值

如果成功，则返回 UInt128 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。

示例

成功转换

SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))

转换失败

SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))

toUInt128OrNull

引入于：v21.6

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toUInt128.
toUInt128OrZero.
toUInt128OrDefault.

语法

toUInt128OrNull(x)

参数

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

返回值

返回 UInt128 类型的值，否则如果转换不成功，则返回 NULL。 UInt128 或 NULL

示例

使用示例

SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N

toUInt128OrZero

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toUInt128.
toUInt128OrNull.
toUInt128OrDefault.

语法

toUInt128OrZero(x)

参数

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

返回值

返回 UInt128 类型的值，否则如果转换不成功则返回 0。 UInt128

示例

使用示例

SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0

toUInt16

引入于：v1.1

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

支持的参数

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

不支持的参数

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

注意

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

注意

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

参见

toUInt16OrZero.
toUInt16OrNull.
toUInt16OrDefault.

语法

toUInt16(expr)

参数

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

返回值

返回一个 16 位无符号整数值。 UInt16

示例

使用示例

SELECT
    toUInt16(16),
    toUInt16(16.16),
    toUInt16('16')
FORMAT Vertical

Row 1:
──────
toUInt16(16):    16
toUInt16(16.16): 16
toUInt16('16'):  16

toUInt16OrDefault

引入于：v21.11

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

语法

toUInt16OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 UInt16

返回值

如果成功，则返回一个 UInt16 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 UInt16

示例

成功转换

SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))

转换失败

SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))

toUInt16OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toUInt16.
toUInt16OrZero.
toUInt16OrDefault.

语法

toUInt16OrNull(x)

参数

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

返回值

返回一个 UInt16 类型的值，否则如果转换不成功则返回 NULL。 UInt16 或 NULL

示例

使用示例

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

Row 1:
──────
toUInt16OrNull('16'):  16
toUInt16OrNull('abc'): \N

toUInt16OrZero

引入于：v1.1

类似于 toUInt16，此函数将输入值转换为 UInt16 类型的值，但在发生错误时返回 0。

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toUInt16.
toUInt16OrNull.
toUInt16OrDefault.

语法

toUInt16OrZero(x)

参数

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

返回值

返回一个 UInt16 类型的值，否则如果转换不成功则返回 0。 UInt16

示例

使用示例

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

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

toUInt256

引入于：v1.1

将输入值转换为 UInt256 类型的值。如果发生错误，则抛出异常。该函数使用朝零舍入，这意味着它会截断数字的小数部分。

支持的参数

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

不支持的参数

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

注意

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

参见

toUInt256OrZero.
toUInt256OrNull.
toUInt256OrDefault.

语法

toUInt256(expr)

参数

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

返回值

返回一个 256 位无符号整数值。 UInt256

示例

使用示例

SELECT
    toUInt256(256),
    toUInt256(256.256),
    toUInt256('256')
FORMAT Vertical

Row 1:
──────
toUInt256(256):     256
toUInt256(256.256): 256
toUInt256('256'):   256

toUInt256OrDefault

引入于：v21.11

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

语法

toUInt256OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 UInt256

返回值

如果成功，则返回一个 UInt256 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 UInt256

示例

成功转换

SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))

转换失败

SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))

toUInt256OrNull

引入于：v20.8

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toUInt256.
toUInt256OrZero.
toUInt256OrDefault.

语法

toUInt256OrNull(x)

参数

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

返回值

返回一个 UInt256 类型的值，否则如果转换不成功则返回 NULL。 UInt256 或 NULL

示例

使用示例

SELECT
    toUInt256OrNull('256'),
    toUInt256OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N

toUInt256OrZero

引入于：v20.8

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

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toUInt256.
toUInt256OrNull.
toUInt256OrDefault.

语法

toUInt256OrZero(x)

参数

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

返回值

返回一个 UInt256 类型的值，否则如果转换不成功则返回 0。 UInt256

示例

使用示例

SELECT
    toUInt256OrZero('256'),
    toUInt256OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0

toUInt32

引入于：v1.1

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

支持的参数

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

不支持的参数

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

注意

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

注意

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

参见

toUInt32OrZero.
toUInt32OrNull.
toUInt32OrDefault.

语法

toUInt32(expr)

参数

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

返回值

返回一个 32 位无符号整数值。 UInt32

示例

使用示例

SELECT
    toUInt32(32),
    toUInt32(32.32),
    toUInt32('32')
FORMAT Vertical

Row 1:
──────
toUInt32(32):    32
toUInt32(32.32): 32
toUInt32('32'):  32

toUInt32OrDefault

引入于：v21.11

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

语法

toUInt32OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 UInt32

返回值

如果成功，则返回一个 UInt32 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 UInt32

示例

成功转换

SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))

转换失败

SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))

toUInt32OrNull

引入于：v1.1

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

支持的参数

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

不支持的参数（返回 NULL）

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

注意

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

参见

toUInt32.
toUInt32OrZero.
toUInt32OrDefault.

语法

toUInt32OrNull(x)

参数

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

返回值

返回一个 UInt32 类型的值，否则如果转换不成功则返回 NULL。 UInt32 或 NULL

示例

使用示例

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

Row 1:
──────
toUInt32OrNull('32'):  32
toUInt32OrNull('abc'): \N

toUInt32OrZero

引入于：v1.1

类似于 toUInt32，此函数将输入值转换为 UInt32 类型的值，但在发生错误时返回 0。

支持的参数

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

不支持的参数（返回 0）

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

注意

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

参见

toUInt32.
toUInt32OrNull.
toUInt32OrDefault.

语法

toUInt32OrZero(x)

参数

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

返回值

返回一个 UInt32 类型的值，否则如果转换不成功则返回 0。 UInt32

示例

使用示例

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

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

toUInt64

引入于：v1.1

将输入值转换为 UInt64 类型的值。如果发生错误，则抛出异常。

支持的参数

类型为 (U)Int* 的值或字符串表示形式。
Float* 类型的值。

不支持的类型

Float* 值的字符串表示形式，包括 NaN 和 Inf。
字符串表示的二进制和十六进制值，例如 SELECT toUInt64('0xc0fe');。

注意

如果输入值无法在 UInt64 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。例如：SELECT toUInt64(18446744073709551616) == 0;

注意

该函数使用向零舍入，这意味着它会截断数字的小数部分。

参见

toUInt64OrZero.
toUInt64OrNull.
toUInt64OrDefault.

语法

toUInt64(expr)

参数

expr — 返回数字或数字字符串表示形式的表达式。 Expression

返回值

返回一个 64 位无符号整数值。 UInt64

示例

使用示例

SELECT
    toUInt64(64),
    toUInt64(64.64),
    toUInt64('64')
FORMAT Vertical

Row 1:
──────
toUInt64(64):    64
toUInt64(64.64): 64
toUInt64('64'):  64

toUInt64OrDefault

引入于：v21.11

类似于 toUInt64，此函数将输入值转换为 UInt64 类型的值，但在发生错误时返回默认值。如果没有传递 default 值，则在发生错误时返回 0。

语法

toUInt64OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。如果解析不成功，则返回的默认值。 UInt64

返回值

如果成功，则返回一个 UInt64 类型的值，否则返回传递的默认值（如果已传递），否则返回 0。 UInt64

示例

成功转换

SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))

转换失败

SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))

toUInt64OrNull

引入于：v1.1

类似于 toUInt64，此函数将输入值转换为 UInt64 类型的值，但在发生错误时返回 NULL。

支持的参数

(U)Int* 的字符串表示形式。

不支持的参数（返回 NULL）

Float* 值的字符串表示形式，包括 NaN 和 Inf。
字符串表示形式的二进制和十六进制值，例如 SELECT toUInt64OrNull('0xc0fe');。

注意

如果输入值无法在 UInt64 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

参见

toUInt64.
toUInt64OrZero.
toUInt64OrDefault.

语法

toUInt64OrNull(x)

参数

x — 数字的字符串表示形式。 String

返回值

返回 UInt64 类型的值，否则如果转换不成功则返回 NULL。 UInt64 或 NULL

示例

使用示例

SELECT
    toUInt64OrNull('64'),
    toUInt64OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrNull('64'):  64
toUInt64OrNull('abc'): \N

toUInt64OrZero

引入于：v1.1

类似于 toUInt64，此函数将输入值转换为 UInt64 类型的值，但在发生错误时返回 0。

支持的参数

(U)Int* 的字符串表示形式。

不支持的参数（返回 0）

Float* 值的字符串表示形式，包括 NaN 和 Inf。
字符串表示形式的二进制和十六进制值，例如 SELECT toUInt64OrZero('0xc0fe');。

注意

如果输入值无法在 UInt64 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

参见

toUInt64.
toUInt64OrNull.
toUInt64OrDefault.

语法

toUInt64OrZero(x)

参数

x — 数字的字符串表示形式。 String

返回值

返回 UInt64 类型的值，否则如果转换不成功则返回 0。 UInt64

示例

使用示例

SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0

toUInt8

引入于：v1.1

将输入值转换为 UInt8 类型的值。如果发生错误，则抛出异常。

支持的参数

类型为 (U)Int* 的值或字符串表示形式。
Float* 类型的值。

不支持的参数

Float* 值的字符串表示形式，包括 NaN 和 Inf。
字符串表示形式的二进制和十六进制值，例如 SELECT toUInt8('0xc0fe');。

注意

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。例如：SELECT toUInt8(256) == 0;。

注意

该函数使用向零舍入，这意味着它会截断数字的小数部分。

参见

toUInt8OrZero.
toUInt8OrNull.
toUInt8OrDefault.

语法

toUInt8(expr)

参数

expr — 返回数字或数字字符串表示形式的表达式。 Expression

返回值

返回一个 8 位无符号整数值。 UInt8

示例

使用示例

SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical

Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8

toUInt8OrDefault

引入于：v21.11

类似于 toUInt8，此函数将输入值转换为 UInt8 类型的值，但在发生错误时返回默认值。如果未传递 default 值，则在发生错误时返回 0。

语法

toUInt8OrDefault(expr[, default])

参数

expr — 返回数字或数字字符串表示形式的表达式。 String 或 (U)Int* 或 Float*
default — 可选。在解析不成功时返回的默认值。 UInt8

返回值

如果成功，则返回 UInt8 类型的值，否则返回传递的默认值，或者如果没有传递默认值，则返回 0。 UInt8

示例

成功转换

SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))

转换失败

SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))

toUInt8OrNull

引入于：v1.1

类似于 toUInt8，此函数将输入值转换为 UInt8 类型的值，但在发生错误时返回 NULL。

支持的参数

(U)Int8/16/32/128/256 的字符串表示形式。

不支持的参数（返回 NULL）

字符串表示形式的普通 Float* 值，包括 NaN 和 Inf。
字符串表示形式的二进制和十六进制值，例如 SELECT toUInt8OrNull('0xc0fe');。

注意

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

参见

toUInt8.
toUInt8OrZero.
toUInt8OrDefault.

语法

toUInt8OrNull(x)

参数

x — 数字的字符串表示形式。 String

返回值

返回 UInt8 类型的值，否则如果转换不成功则返回 NULL。 UInt8 或 NULL

示例

使用示例

SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N

toUInt8OrZero

引入于：v1.1

类似于 toUInt8，此函数将输入值转换为 UInt8 类型的值，但在发生错误时返回 0。

支持的参数

(U)Int8/16/32/128/256 的字符串表示形式。

不支持的参数（返回 0）

字符串表示形式的普通 Float* 值，包括 NaN 和 Inf。
字符串表示形式的二进制和十六进制值，例如 SELECT toUInt8OrZero('0xc0fe');。

注意

如果输入值无法在 UInt8 的范围内表示，则结果会发生溢出或下溢。这不被视为错误。

参见

toUInt8.
toUInt8OrNull.
toUInt8OrDefault.

语法

toUInt8OrZero(x)

参数

x — 数字的字符串表示形式。 String

返回值

返回 UInt8 类型的值，否则如果转换不成功则返回 0。 UInt8

示例

使用示例

SELECT
    toUInt8OrZero('-8'),
    toUInt8OrZero('abc')
FORMAT Vertical

Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0

toUUID

引入于：v1.1

将字符串值转换为 UUID 值。

语法

toUUID(string)

参数

string — 作为字符串的 UUID。 String 或 FixedString

返回值

从 UUID 的字符串表示形式返回 UUID。 UUID

示例

使用示例

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrZero

引入于：v20.12

将输入值转换为 UUID 类型的值，但在发生错误时返回零 UUID。类似于 toUUID，但在转换错误时返回零 UUID (00000000-0000-0000-0000-000000000000)，而不是抛出异常。

支持的参数

标准格式 (8-4-4-4-12 十六进制数字) 的 UUID 字符串表示形式。
不带连字符的 UUID 字符串表示形式 (32 个十六进制数字)。

不支持的参数 (返回零 UUID)

无效的字符串格式。
非字符串类型。

语法

toUUIDOrZero(x)

参数

x — UUID 的字符串表示形式。 String

返回值

如果成功，则返回 UUID 值，否则返回零 UUID (00000000-0000-0000-0000-000000000000)。 UUID

示例

使用示例

SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid

┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘

toUnixTimestamp64Micro

引入于：v20.5

将 DateTime64 转换为具有固定微秒精度的 Int64 值。根据其精度对输入值进行适当的放大或缩小。

注意

输出值相对于 UTC，而不是输入值的时区。

语法

toUnixTimestamp64Micro(value)

参数

value — 具有任何精度的 DateTime64 值。 DateTime64

返回值

返回微秒中的 Unix 时间戳。 Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);

┌─toUnixTimestamp64Micro(dt64)─┐
│               1739489491011123 │
└────────────────────────────────┘

toUnixTimestamp64Milli

引入于：v20.5

将 DateTime64 转换为具有固定毫秒精度的 Int64 值。根据其精度对输入值进行适当的放大或缩小。

注意

输出值相对于 UTC，而不是输入值的时区。

语法

toUnixTimestamp64Milli(value)

参数

value — 具有任何精度的 DateTime64 值。 DateTime64

返回值

返回毫秒中的 Unix 时间戳。 Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);

┌─toUnixTimestamp64Milli(dt64)─┐
│                1739489491011 │
└──────────────────────────────┘

toUnixTimestamp64Nano

引入于：v20.5

将 DateTime64 转换为具有固定纳秒精度的 Int64 值。根据其精度对输入值进行适当的放大或缩小。

注意

输出值相对于 UTC，而不是输入值的时区。

语法

toUnixTimestamp64Nano(value)

参数

value — 具有任何精度的 DateTime64 值。 DateTime64

返回值

返回纳秒中的 Unix 时间戳。 Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);

┌─toUnixTimestamp64Nano(dt64)────┐
│            1739489491011123456 │
└────────────────────────────────┘

toUnixTimestamp64Second

引入于：v24.12

将 DateTime64 转换为具有固定秒精度的 Int64 值。根据其精度对输入值进行适当的放大或缩小。

注意

输出值相对于 UTC，而不是输入值的时区。

语法

toUnixTimestamp64Second(value)

参数

value — 具有任何精度的 DateTime64 值。 DateTime64

返回值

返回秒中的 Unix 时间戳。 Int64

示例

使用示例

WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);

┌─toUnixTimestamp64Second(dt64)─┐
│                    1739489491 │
└───────────────────────────────┘

数据转换的常见问题​

关于 toString 函数的说明​

关于 toDate/toDateTime 函数的说明​

CAST​

accurateCast​

accurateCastOrDefault​

accurateCastOrNull​

formatRow​

formatRowNoNewline​

fromUnixTimestamp64Micro​

fromUnixTimestamp64Milli​

fromUnixTimestamp64Nano​

fromUnixTimestamp64Second​

parseDateTime​

parseDateTime32BestEffort​

parseDateTime32BestEffortOrNull​

parseDateTime32BestEffortOrZero​

parseDateTime64​

parseDateTime64BestEffort​

parseDateTime64BestEffortOrNull​

parseDateTime64BestEffortOrZero​

parseDateTime64BestEffortUS​

parseDateTime64BestEffortUSOrNull​

parseDateTime64BestEffortUSOrZero​

parseDateTime64InJodaSyntax​

parseDateTime64InJodaSyntaxOrNull​

parseDateTime64InJodaSyntaxOrZero​

parseDateTime64OrNull​

parseDateTime64OrZero​

parseDateTimeBestEffort​

parseDateTimeBestEffortOrNull​

parseDateTimeBestEffortOrZero​

parseDateTimeBestEffortUS​

parseDateTimeBestEffortUSOrNull​

parseDateTimeBestEffortUSOrZero​

parseDateTimeInJodaSyntax​

parseDateTimeInJodaSyntaxOrNull​

parseDateTimeInJodaSyntaxOrZero​

parseDateTimeOrNull​

parseDateTimeOrZero​

reinterpret​

reinterpretAsDate​

reinterpretAsDateTime​

reinterpretAsFixedString​

reinterpretAsFloat32​

reinterpretAsFloat64​

reinterpretAsInt128​

reinterpretAsInt16​

reinterpretAsInt256​

reinterpretAsInt32​

reinterpretAsInt64​

reinterpretAsInt8​

reinterpretAsString​

reinterpretAsUInt128​

reinterpretAsUInt16​

reinterpretAsUInt256​

reinterpretAsUInt32​

reinterpretAsUInt64​

reinterpretAsUInt8​

reinterpretAsUUID​

toBFloat16​

toBFloat16OrNull​

toBFloat16OrZero​

toBool​

toDate​

toDate32​

toDate32OrDefault​

toDate32OrNull​

toDate32OrZero​

toDateOrDefault​

toDateOrNull​

toDateOrZero​

toDateTime​

toDateTime32​

toDateTime64​

toDateTime64OrDefault​

toDateTime64OrNull​

toDateTime64OrZero​

toDateTimeOrDefault​

toDateTimeOrNull​

数据转换的常见问题

关于 `toString` 函数的说明

关于 `toDate`/`toDateTime` 函数的说明

CAST

accurateCast

accurateCastOrDefault

accurateCastOrNull

formatRow

formatRowNoNewline

fromUnixTimestamp64Micro

fromUnixTimestamp64Milli

fromUnixTimestamp64Nano

fromUnixTimestamp64Second

parseDateTime

parseDateTime32BestEffort

parseDateTime32BestEffortOrNull

parseDateTime32BestEffortOrZero

parseDateTime64

parseDateTime64BestEffort

parseDateTime64BestEffortOrNull

parseDateTime64BestEffortOrZero

parseDateTime64BestEffortUS

parseDateTime64BestEffortUSOrNull

parseDateTime64BestEffortUSOrZero

parseDateTime64InJodaSyntax

parseDateTime64InJodaSyntaxOrNull

parseDateTime64InJodaSyntaxOrZero

parseDateTime64OrNull

parseDateTime64OrZero

parseDateTimeBestEffort

parseDateTimeBestEffortOrNull

parseDateTimeBestEffortOrZero

parseDateTimeBestEffortUS

parseDateTimeBestEffortUSOrNull

parseDateTimeBestEffortUSOrZero

parseDateTimeInJodaSyntax

parseDateTimeInJodaSyntaxOrNull

parseDateTimeInJodaSyntaxOrZero

parseDateTimeOrNull

parseDateTimeOrZero

reinterpret

reinterpretAsDate

reinterpretAsDateTime

reinterpretAsFixedString

reinterpretAsFloat32

reinterpretAsFloat64

reinterpretAsInt128

reinterpretAsInt16

reinterpretAsInt256

reinterpretAsInt32

reinterpretAsInt64

reinterpretAsInt8

reinterpretAsString

reinterpretAsUInt128

reinterpretAsUInt16

reinterpretAsUInt256

reinterpretAsUInt32

reinterpretAsUInt64

reinterpretAsUInt8

reinterpretAsUUID

toBFloat16

toBFloat16OrNull

toBFloat16OrZero

toBool

toDate

toDate32

toDate32OrDefault

toDate32OrNull

toDate32OrZero

toDateOrDefault

toDateOrNull

toDateOrZero

toDateTime

toDateTime32

toDateTime64

toDateTime64OrDefault

toDateTime64OrNull

toDateTime64OrZero

toDateTimeOrDefault

toDateTimeOrNull