│
└──────────────────────────────────────────────┘
```
## formatRowNoNewline
引入版本：v20.7.0
与 [`formatRow`](#formatRow) 相同，但会去掉每行末尾的换行符。
通过指定的格式将任意表达式转换为字符串，但会移除结果末尾的所有换行符。
**语法**
```sql theme={null}
formatRowNoNewline(format, x, y, ...)
```
**参数**
* `format` — 文本格式，例如 CSV、TSV。[`String`](/zh/reference/data-types/string)
* `x, y, ...` — 表达式。[`Any`](/zh/reference/data-types)
**返回值**
返回去除了换行符的格式化字符串。[`String`](/zh/reference/data-types/string)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT formatRowNoNewline('CSV', number, 'good')
FROM numbers(3)
```
```response title=Response theme={null}
┌─formatRowNoNewline('CSV', number, 'good')─┐
│ 0,"good" │
│ 1,"good" │
│ 2,"good" │
└───────────────────────────────────────────┘
```
## fromUnixTimestamp64Micro
引入于：v20.5.0
将以微秒为单位的 Unix 时间戳转换为具有微秒精度的 `DateTime64` 值。
输入值会被视为具有微秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 起经过的微秒数) 。
**语法**
```sql theme={null}
fromUnixTimestamp64Micro(value[, timezone])
```
**参数**
* `value` — 以微秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。用于返回值的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回具有微秒精度的 `DateTime64` 值。[`DateTime64(6)`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT fromUnixTimestamp64Micro(1640995200123456)
```
```response title=Response theme={null}
┌─fromUnixTimestamp64Micro(1640995200123456)─┐
│ 2022-01-01 00:00:00.123456 │
└────────────────────────────────────────────┘
```
## fromUnixTimestamp64Milli
引入版本：v20.5.0
将以毫秒为单位的 Unix 时间戳转换为具有毫秒精度的 `DateTime64` 值。
输入值会被视为毫秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 起经过的毫秒数) 。
**语法**
```sql theme={null}
fromUnixTimestamp64Milli(value[, timezone])
```
**参数**
* `value` — 以毫秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。用于返回值的时区。[`String`](/zh/reference/data-types/string)
**返回值**
具有毫秒精度的 `DateTime64` 值。[`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT fromUnixTimestamp64Milli(1640995200123)
```
```response title=Response theme={null}
┌─fromUnixTimestamp64Milli(1640995200123)─┐
│ 2022-01-01 00:00:00.123 │
└─────────────────────────────────────────┘
```
## fromUnixTimestamp64Nano
引入版本：v20.5.0
将纳秒级 Unix 时间戳转换为具有纳秒精度的 [`DateTime64`](/zh/reference/data-types/datetime64) 值。
输入值会被视为纳秒精度的 Unix 时间戳 (即自 1970-01-01 00:00:00 UTC 以来的纳秒数) 。
请注意，输入值会被视为 UTC 时间戳，而不是按输入值自身的时区来处理。
**语法**
```sql theme={null}
fromUnixTimestamp64Nano(value[, timezone])
```
**参数**
* `value` — 以纳秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。返回值使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回具有纳秒精度的 `DateTime64` 值。[`DateTime64(9)`](/zh/reference/data-types/datetime64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT fromUnixTimestamp64Nano(1640995200123456789)
```
```response title=Response theme={null}
┌─fromUnixTimestamp64Nano(1640995200123456789)─┐
│ 2022-01-01 00:00:00.123456789 │
└──────────────────────────────────────────────┘
```
## fromUnixTimestamp64Second
引入版本：v24.12.0
将以秒为单位的 Unix 时间戳转换为秒精度的 `DateTime64` 值。
输入值会被视为秒精度的 Unix 时间戳 (自 1970-01-01 00:00:00 UTC 起经过的秒数) 。
**语法**
```sql theme={null}
fromUnixTimestamp64Second(value[, timezone])
```
**参数**
* `value` — 以秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。返回值使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个具有秒级精度的 `DateTime64` 值。[`DateTime64(0)`](/zh/reference/data-types/datetime64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT fromUnixTimestamp64Second(1640995200)
```
```response title=Response theme={null}
┌─fromUnixTimestamp64Second(1640995200)─┐
│ 2022-01-01 00:00:00 │
└───────────────────────────────────────┘
```
## parseDateTime
引入版本：v23.3.0
根据 MySQL 日期格式字符串解析日期时间字符串。
此函数是 [`formatDateTime`](/zh/reference/functions/regular-functions/date-time-functions) 的逆函数。
它使用格式 String 解析 String 参数，并返回 DateTime 类型。
**语法**
```sql theme={null}
parseDateTime(time_string, format[, timezone])
```
**别名**: `TO_UNIXTIME`
**参数**
* `time_string` — 要解析为 DateTime 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 用于指定如何解析 time\_string 的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
根据 MySQL 风格的格式字符串，从输入字符串解析出的 DateTime。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')
```
```response title=Response theme={null}
┌─parseDateTime('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│ 2025-01-04 23:00:00 │
└───────────────────────────────────────────────────────────┘
```
## parseDateTime32BestEffort
Introduced in: v20.9.0
将日期和时间的字符串表示形式转换为 [`DateTime`](/zh/reference/data-types/datetime) 数据类型。
该函数可以解析 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)、[RFC 1123 - 5.2.14 RFC-822 Date and Time Specification](https://tools.ietf.org/html/rfc1123#page-55)、ClickHouse 以及其他一些日期和时间格式。
**语法**
```sql theme={null}
parseDateTime32BestEffort(time_string[, time_zone])
```
**参数**
* `time_string` — 包含待转换日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时所依据的时区。[`String`](/zh/reference/data-types/string)
**返回值**
将 `time_string` 以 `DateTime` 类型返回。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime32BestEffort('23/10/2025 12:12:57')
AS parseDateTime32BestEffort
```
```response title=Response theme={null}
┌─parseDateTime32BestEffort─┐
│ 2025-10-23 12:12:57 │
└───────────────────────────┘
```
**带时区**
```sql title=Query theme={null}
SELECT parseDateTime32BestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul')
AS parseDateTime32BestEffort
```
```response title=Response theme={null}
┌─parseDateTime32BestEffort─┐
│ 2025-08-18 10:22:16 │
└───────────────────────────┘
```
**Unix 时间戳**
```sql title=Query theme={null}
SELECT parseDateTime32BestEffort('1284101485')
AS parseDateTime32BestEffort
```
```response title=Response theme={null}
┌─parseDateTime32BestEffort─┐
│ 2015-07-07 12:04:41 │
└───────────────────────────┘
```
## parseDateTime32BestEffortOrNull
引入版本：v20.9.0
与 [`parseDateTime32BestEffort`](#parseDateTime32BestEffort) 相同，但在遇到无法处理的日期格式时会返回 `NULL`。
**语法**
```sql theme={null}
parseDateTime32BestEffortOrNull(time_string[, time_zone])
```
**参数**
* `time_string` — 包含要转换的日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从字符串中解析出的 `DateTime` 对象；如果解析失败，则返回 `NULL`。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
parseDateTime32BestEffortOrNull('23/10/2025 12:12:57') AS valid,
parseDateTime32BestEffortOrNull('invalid date') AS invalid
```
```response title=Response theme={null}
┌─valid───────────────┬─invalid─┐
│ 2025-10-23 12:12:57 │ ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘
```
## parseDateTime32BestEffortOrZero
引入版本：v20.9.0
与 [`parseDateTime32BestEffort`](#parseDateTime32BestEffort) 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。
**语法**
```sql theme={null}
parseDateTime32BestEffortOrZero(time_string[, time_zone])
```
**参数**
* `time_string` — 包含待转换日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时所依据的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从字符串解析出的 `DateTime` 对象；如果解析失败，则返回零日期 (`1970-01-01 00:00:00`) 。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
parseDateTime32BestEffortOrZero('23/10/2025 12:12:57') AS valid,
parseDateTime32BestEffortOrZero('invalid date') AS invalid
```
```response title=Response theme={null}
┌─valid───────────────┬─invalid─────────────┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘
```
## parseDateTime64
引入版本：v24.11.0
按照 MySQL 日期格式字符串，解析带有子秒级精度的日期时间字符串。
对于 DateTime64，此函数是 [`formatDateTime`](/zh/reference/functions/regular-functions/date-time-functions) 的逆操作。
它使用 格式 String 解析一个 String 参数。返回 DateTime64 类型，可表示 1900 年到 2299 年之间、具有子秒级精度的日期时间值。
**语法**
```sql theme={null}
parseDateTime64(time_string, format[, timezone])
```
**参数**
* `time_string` — 将被解析为 DateTime64 的 String。[`String`](/zh/reference/data-types/string)
* `format` — 用于指定如何解析 time\_string 的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回根据 MySQL 风格的格式字符串从输入字符串解析得到的 DateTime64。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')
```
```response title=Response theme={null}
┌─parseDateTime64('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│ 2025-01-04 23:00:00.123 │
└─────────────────────────────────────────────────────────────────────┘
```
## parseDateTime64BestEffort
在 v20.1.0 中引入
与 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 函数相同，但还支持解析毫秒和微秒，并返回 [`DateTime64`](/zh/reference/data-types/datetime64) 数据类型。
**语法**
```sql theme={null}
parseDateTime64BestEffort(time_string[, precision[, time_zone]])
```
**参数**
* `time_string` — 包含待转换日期或日期时间的 String。 [`String`](/zh/reference/data-types/string)
* `precision` — 可选。所需精度。`3` 表示毫秒，`6` 表示微秒。默认值：`3`。 [`UInt8`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。时区。函数会根据该时区解析 `time_string`。 [`String`](/zh/reference/data-types/string)
**返回值**
返回转换为 [`DateTime64`](/zh/reference/data-types/datetime64) 数据类型的 `time_string`。 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTime64BestEffort('2025-01-01') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346') AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',6) AS a, toTypeName(a) AS t
UNION ALL
SELECT parseDateTime64BestEffort('2025-01-01 01:01:00.12346',3,'Asia/Istanbul') AS a, toTypeName(a) AS t
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌──────────────────────────a─┬─t──────────────────────────────┐
│ 2025-01-01 01:01:00.123000 │ DateTime64(3) │
│ 2025-01-01 00:00:00.000000 │ DateTime64(3) │
│ 2025-01-01 01:01:00.123460 │ DateTime64(6) │
│ 2025-12-31 22:01:00.123000 │ DateTime64(3, 'Asia/Istanbul') │
└────────────────────────────┴────────────────────────────────┘
```
## parseDateTime64BestEffortOrNull
引入版本：v20.1.0
与 [`parseDateTime64BestEffort`](#parseDateTime64BestEffort) 相同，不同之处在于，遇到无法处理的日期格式时会返回 `NULL`。
**语法**
```sql theme={null}
parseDateTime64BestEffortOrNull(time_string[, precision[, time_zone]])
```
**参数**
* `time_string` — 包含要转换的日期或日期时间的 String。[`String`](/zh/reference/data-types/string)
* `precision` — 可选。所需精度。`3` 表示毫秒，`6` 表示微秒。默认值：`3`。[`UInt8`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。时区。函数会根据该时区解析 `time_string`。[`String`](/zh/reference/data-types/string)
**返回值**
返回转换后的 [`DateTime64`](/zh/reference/data-types/datetime64) 类型 `time_string`；如果输入无法解析，则返回 `NULL`。[`DateTime64`](/zh/reference/data-types/datetime64) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTime64BestEffortOrNull('2025-01-01 01:01:00.123') AS valid,
parseDateTime64BestEffortOrNull('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid───────────────────┬─invalid─┐
│ 2025-01-01 01:01:00.123 │ ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘
```
## parseDateTime64BestEffortOrZero
引入版本：v20.1.0
与 [`parseDateTime64BestEffort`](#parseDateTime64BestEffort) 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。
**语法**
```sql theme={null}
parseDateTime64BestEffortOrZero(time_string[, precision[, time_zone]])
```
**参数**
* `time_string` — 包含要转换的日期或日期时间的 String。[`String`](/zh/reference/data-types/string)
* `precision` — 可选。所需精度。`3` 表示毫秒，`6` 表示微秒。默认值：`3`。[`UInt8`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。时区。函数会按照该时区解析 `time_string`。[`String`](/zh/reference/data-types/string)
**返回值**
返回转换后的 [`DateTime64`](/zh/reference/data-types/datetime64) 类型 `time_string`；如果输入无法解析，则返回零日期/日期时间 (`1970-01-01 00:00:00.000`) 。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64BestEffortOrZero('2025-01-01 01:01:00.123') AS valid,
parseDateTime64BestEffortOrZero('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid───────────────────┬─invalid─────────────────┐
│ 2025-01-01 01:01:00.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘
```
## parseDateTime64BestEffortUS
引入版本：v22.8.0
与 [`parseDateTime64BestEffort`](#parseDateTime64BestEffort) 相同，但在日期格式存在歧义时，此函数会优先采用美国日期格式 (`MM/DD/YYYY` 等) 。
**语法**
```sql theme={null}
parseDateTime64BestEffortUS(time_string [, precision [, time_zone]])
```
**参数**
* `time_string` — 包含要转换的日期或日期时间的 String。[`String`](/zh/reference/data-types/string)
* `precision` — 可选。所需精度。`3` 表示毫秒，`6` 表示微秒。默认值：`3`。[`UInt8`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。时区。函数会根据该时区解析 `time_string`。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 `time_string` 转换为 [`DateTime64`](/zh/reference/data-types/datetime64) 后的结果；对于有歧义的情况，优先按美国日期格式解析。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64BestEffortUS('02/10/2025 12:30:45.123') AS us_format,
parseDateTime64BestEffortUS('15/08/2025 10:15:30.456') AS fallback_to_standard
```
```response title=Response theme={null}
┌─us_format───────────────┬─fallback_to_standard────┐
│ 2025-02-10 12:30:45.123 │ 2025-08-15 10:15:30.456 │
└─────────────────────────┴─────────────────────────┘
```
## parseDateTime64BestEffortUSOrNull
引入版本：v22.8.0
与 [`parseDateTime64BestEffort`](#parseDateTime64BestEffort) 相同，不同之处在于：当日期格式存在歧义时，此函数会优先采用美国日期格式 (`MM/DD/YYYY` 等) ；当遇到无法处理的日期格式时，则返回 `NULL`。
**语法**
```sql theme={null}
parseDateTime64BestEffortUSOrNull(time_string[, precision[, time_zone]])
```
**参数**
* `time_string` — 包含要转换的日期或日期时间的 String。([`String`](/zh/reference/data-types/string))
* `precision` — 可选。所需精度。`3` 表示毫秒，`6` 表示微秒。默认值：`3`。([`UInt8`](/zh/reference/data-types/int-uint))
* `time_zone` — 可选。时区。函数会根据该时区解析 `time_string`。([`String`](/zh/reference/data-types/string))
**返回值**
返回采用美国日期格式优先规则解析后转换得到的 [`DateTime64`](/zh/reference/data-types/datetime64) 类型值；如果输入无法解析，则返回 `NULL`。([`DateTime64`](/zh/reference/data-types/datetime64) 或 [`NULL`](/zh/reference/syntax#null))
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64BestEffortUSOrNull('02/10/2025 12:30:45.123') AS valid_us,
parseDateTime64BestEffortUSOrNull('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid_us────────────────┬─invalid─┐
│ 2025-02-10 12:30:45.123 │ ᴺᵁᴸᴸ │
└─────────────────────────┴─────────┘
```
## parseDateTime64BestEffortUSOrZero
引入版本：v22.8.0
与 [`parseDateTime64BestEffort`](#parseDateTime64BestEffort) 相同，不同之处在于，此函数在存在歧义时会优先使用美国日期格式 (`MM/DD/YYYY` 等) ，并且在遇到无法处理的日期格式时会返回零日期或零日期时间。
**语法**
```sql theme={null}
parseDateTime64BestEffortUSOrZero(time_string [, precision [, time_zone]])
```
**参数**
* `time_string` — 包含要转换的日期或日期时间的 String。[`String`](/zh/reference/data-types/string)
* `precision` — 可选。所需精度。`3` 表示毫秒，`6` 表示微秒。默认值：`3`。[`UInt8`](/zh/reference/data-types/int-uint)
* `time_zone` — 可选。时区。该函数会按此时区解析 `time_string`。[`String`](/zh/reference/data-types/string)
**返回值**
返回按美国日期格式优先规则转换后的 `time_string` 的 [`DateTime64`](/zh/reference/data-types/datetime64) 值；如果输入无法解析，则返回零日期/日期时间 (`1970-01-01 00:00:00.000`) 。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64BestEffortUSOrZero('02/10/2025 12:30:45.123') AS valid_us,
parseDateTime64BestEffortUSOrZero('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid_us────────────────┬─invalid─────────────────┐
│ 2025-02-10 12:30:45.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘
```
## parseDateTime64InJodaSyntax
引入版本：v24.10.0
根据 Joda 日期格式字符串，解析具有子秒级精度的日期和时间字符串。
对于 DateTime64，此函数是 [`formatDateTimeInJodaSyntax`](/zh/reference/functions/regular-functions/date-time-functions#formatDateTimeInJodaSyntax) 的逆操作。
它使用 Joda 风格的格式 String 解析一个 String 类型的参数。返回 DateTime64 类型，可表示 1900 年至 2299 年间且具有子秒级精度的日期和时间。
有关格式模式，请参阅 [Joda Time documentation](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html)。
**语法**
```sql theme={null}
parseDateTime64InJodaSyntax(time_string, format[, timezone])
```
**参数**
* `time_string` — 要解析为 DateTime64 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — Joda 语法格式字符串，用于指定如何解析 time\_string。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回根据 Joda 风格格式字符串从输入字符串解析出的 DateTime64。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')
```
```response title=Response theme={null}
┌─parseDateTime64InJodaSyntax('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│ 2025-01-04 23:00:00.123 │
└────────────────────────────────────────────────────────────────────────────────────┘
```
## parseDateTime64InJodaSyntaxOrNull
Introduced in: v24.10.0
与 [`parseDateTime64InJodaSyntax`](#parseDateTime64InJodaSyntax) 相同，但遇到无法解析的日期格式时会返回 `NULL`。
**Syntax**
```sql theme={null}
parseDateTime64InJodaSyntaxOrNull(time_string, format[, timezone])
```
**参数**
* `time_string` — 要解析为 DateTime64 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 采用 Joda 语法的格式字符串，用于指定如何解析 time\_string。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析出的 DateTime64；如果解析失败，则返回 NULL。[`Nullable(DateTime64)`](/zh/reference/data-types/nullable)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')
```
```response title=Response theme={null}
┌─parseDateTime64InJodaSyntaxOrNull('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│ 2025-01-04 23:00:00.123 │
└──────────────────────────────────────────────────────────────────────────────────────────┘
```
## parseDateTime64InJodaSyntaxOrZero
引入版本：v24.10.0
与 [`parseDateTime64InJodaSyntax`](#parseDateTime64InJodaSyntax) 相同，但在遇到无法解析的日期格式时会返回零日期。
**语法**
```sql theme={null}
parseDateTime64InJodaSyntaxOrZero(time_string, format[, timezone])
```
**参数**
* `time_string` — 要解析为 DateTime64 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 采用 Joda 语法的格式字符串，用于指定如何解析 time\_string。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析出的 DateTime64；如果解析失败，则返回零值 DateTime64。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')
```
```response title=Response theme={null}
┌─parseDateTime64InJodaSyntaxOrZero('2025-01-04 23:00:00.123', 'yyyy-MM-dd HH:mm:ss.SSS')─┐
│ 2025-01-04 23:00:00.123 │
└──────────────────────────────────────────────────────────────────────────────────────────┘
```
## parseDateTime64OrNull
引入于：v24.11.0
与 [`parseDateTime64`](#parseDateTime64) 相同，但遇到无法解析的日期格式时会返回 `NULL`。
**语法**
```sql theme={null}
parseDateTime64OrNull(time_string, format[, timezone])
```
**参数**
* `time_string` — 将被解析为 DateTime64 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 指定 time\_string 解析方式的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析得到的 DateTime64；如果解析失败，则返回 NULL。[`Nullable(DateTime64)`](/zh/reference/data-types/nullable)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')
```
```response title=Response theme={null}
┌─parseDateTime64OrNull('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│ 2025-01-04 23:00:00.123 │
└───────────────────────────────────────────────────────────────────────────┘
```
## parseDateTime64OrZero
引入版本：v24.11.0
与 [`parseDateTime64`](#parseDateTime64) 相同，但遇到无法解析的日期格式时会返回零日期。
**语法**
```sql theme={null}
parseDateTime64OrZero(time_string, format[, timezone])
```
**参数**
* `time_string` — 要解析为 DateTime64 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 指定解析 time\_string 方式的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析得到的 DateTime64；如果解析失败，则返回零值 DateTime64。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')
```
```response title=Response theme={null}
┌─parseDateTime64OrZero('2025-01-04 23:00:00.123', '%Y-%m-%d %H:%i:%s.%f')─┐
│ 2025-01-04 23:00:00.123 │
└───────────────────────────────────────────────────────────────────────────┘
```
## parseDateTimeBestEffort
版本引入：v1.1.0
将 String 字符串表示形式中的日期和时间转换为 DateTime 数据类型。
该函数可解析 [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)、[RFC 1123 - 5.2.14 RFC-822](https://datatracker.ietf.org/doc/html/rfc822) 日期和时间规范、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`。
对于所有带分隔符的格式，该函数都可以解析用月份全称或月份名前三个字母表示的月份名称。
如果未指定年份，则默认为当前年份。
**语法**
```sql theme={null}
parseDateTimeBestEffort(time_string[, time_zone])
```
**参数**
* `time_string` — 包含要转换的日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `DateTime` 类型的 `time_string`。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffort('23/10/2025 12:12:57') AS parseDateTimeBestEffort
```
```response title=Response theme={null}
┌─parseDateTimeBestEffort─┐
│ 2025-10-23 12:12:57 │
└─────────────────────────┘
```
**带有时区**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffort('Sat, 18 Aug 2025 07:22:16 GMT', 'Asia/Istanbul') AS parseDateTimeBestEffort
```
```response title=Response theme={null}
┌─parseDateTimeBestEffort─┐
│ 2025-08-18 10:22:16 │
└─────────────────────────┘
```
**Unix 时间戳**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffort('1735689600') AS parseDateTimeBestEffort
```
```response title=Response theme={null}
┌─parseDateTimeBestEffort─┐
│ 2025-01-01 00:00:00 │
└─────────────────────────┘
```
## parseDateTimeBestEffortOrNull
引入版本：v1.1.0
与 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 相同，不同之处在于当遇到无法处理的日期格式时，它会返回 `NULL`。
该函数可解析 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)、[RFC 1123 - 5.2.14 RFC-822 日期和时间规范](https://tools.ietf.org/html/rfc1123#page-55)、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`。
对于所有带分隔符的格式，该函数都可以解析以月份全称或月份名前三个字母表示的月份名称。
如果未指定年份，则默认为当前年份。
**语法**
```sql theme={null}
parseDateTimeBestEffortOrNull(time_string[, time_zone])
```
**参数**
* `time_string` — 包含待转换日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。用于解析 `time_string` 的时区。[`String`](/zh/reference/data-types/string)
**返回值**
`time_string` 会以 DateTime 形式返回；如果输入无法解析，则返回 `NULL`。[`DateTime`](/zh/reference/data-types/datetime) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffortOrNull('23/10/2025 12:12:57') AS valid,
parseDateTimeBestEffortOrNull('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid───────────────┬─invalid─┐
│ 2025-10-23 12:12:57 │ ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘
```
## parseDateTimeBestEffortOrZero
引入版本：v1.1.0
与 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 相同，不同之处在于，当遇到无法处理的日期格式时，它会返回零日期或零日期时间。
该函数可解析 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)、[RFC 1123 - 5.2.14 RFC-822 日期和时间规范](https://tools.ietf.org/html/rfc1123#page-55)、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`。
对于所有带分隔符的格式，该函数都可以解析用月份全称或月份名前三个字母表示的月份名称。
如果未指定年份，则默认为当前年份。
**语法**
```sql theme={null}
parseDateTimeBestEffortOrZero(time_string[, time_zone])
```
**参数**
* `time_string` — 包含要转换的日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时所依据的时区。[`String`](/zh/reference/data-types/string)
**返回值**
将 `time_string` 作为 `DateTime` 返回；如果输入无法解析，则返回零日期/日期时间 (`1970-01-01` 或 `1970-01-01 00:00:00`) 。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffortOrZero('23/10/2025 12:12:57') AS valid,
parseDateTimeBestEffortOrZero('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid───────────────┬─invalid─────────────┐
│ 2025-10-23 12:12:57 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘
```
## parseDateTimeBestEffortUS
引入于：v1.1.0
对于 ISO 日期格式 (例如 `YYYY-MM-DD hh:mm:ss`) 以及其他能够明确识别出月份和日期组件的日期格式 (例如 `YYYYMMDDhhmmss`、`YYYY-MM`、`DD hh` 或 `YYYY-MM-DD hh:mm:ss ±h:mm`) ，此函数的行为与 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 相同。
如果无法明确识别月份和日期组件，例如 `MM/DD/YYYY`、`MM-DD-YYYY` 或 `MM-DD-YY`，则会优先按美国日期格式解析，而不是按 `DD/MM/YYYY`、`DD-MM-YYYY` 或 `DD-MM-YY` 解析。
不过，上一条有一个例外：如果月份值大于 12 且小于等于 31，此函数会回退到 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 的行为，例如 `15/08/2020` 会被解析为 `2020-08-15`。
**语法**
```sql theme={null}
parseDateTimeBestEffortUS(time_string[, time_zone])
```
**参数**
* `time_string` — 包含要转换的日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 `time_string` 解析为 `DateTime` 的结果；对于有歧义的情况，优先按照美国日期格式进行解析。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffortUS('02/10/2025') AS us_format,
parseDateTimeBestEffortUS('15/08/2025') AS fallback_to_standard
```
```response title=Response theme={null}
┌─us_format───────────┬─fallback_to_standard─┐
│ 2025-02-10 00:00:00 │ 2025-08-15 00:00:00 │
└─────────────────────┴──────────────────────┘
```
## parseDateTimeBestEffortUSOrNull
引入版本：v1.1.0
与 [`parseDateTimeBestEffortUS`](#parseDateTimeBestEffortUS) 函数相同，不同之处在于：当遇到无法处理的日期格式时，它会返回 `NULL`。
对于 ISO 日期格式，此函数的行为与 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 相同；但在存在歧义的情况下，会优先采用美国日期格式，并在解析出错时返回 `NULL`。
**语法**
```sql theme={null}
parseDateTimeBestEffortUSOrNull(time_string[, time_zone])
```
**参数**
* `time_string` — 包含待转换日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。解析 `time_string` 时所依据的时区。[`String`](/zh/reference/data-types/string)
**返回值**
将 `time_string` 按照美国日期格式优先级解析为 DateTime 并返回；如果输入无法解析，则返回 `NULL`。[`DateTime`](/zh/reference/data-types/datetime) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffortUSOrNull('02/10/2025') AS valid_us,
parseDateTimeBestEffortUSOrNull('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid_us────────────┬─invalid─┐
│ 2025-02-10 00:00:00 │ ᴺᵁᴸᴸ │
└─────────────────────┴─────────┘
```
## parseDateTimeBestEffortUSOrZero
引入版本：v1.1.0
与 [`parseDateTimeBestEffortUS`](#parseDateTimeBestEffortUS) 函数相同，但当遇到无法处理的日期格式时，它会返回零日期 (`1970-01-01`) 或零日期时间 (`1970-01-01 00:00:00`) 。
对于 ISO 日期格式，此函数的行为与 [`parseDateTimeBestEffort`](#parseDateTimeBestEffort) 相同；但在存在歧义的情况下，会优先采用美国日期格式，并在解析错误时返回零值。
**语法**
```sql theme={null}
parseDateTimeBestEffortUSOrZero(time_string[, time_zone])
```
**参数**
* `time_string` — 包含要转换的日期和时间的 String。[`String`](/zh/reference/data-types/string)
* `time_zone` — 可选。按此时区解析 `time_string`。[`String`](/zh/reference/data-types/string)
**返回值**
以美国日期格式优先的方式将 `time_string` 解析为 `DateTime` 并返回；如果输入无法解析，则返回零日期/日期时间 (`1970-01-01` 或 `1970-01-01 00:00:00`) 。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeBestEffortUSOrZero('02/10/2025') AS valid_us,
parseDateTimeBestEffortUSOrZero('invalid') AS invalid
```
```response title=Response theme={null}
┌─valid_us────────────┬─invalid─────────────┐
│ 2025-02-10 00:00:00 │ 1970-01-01 00:00:00 │
└─────────────────────┴─────────────────────┘
```
## parseDateTimeInJodaSyntax
引入版本：v23.3.0
根据 Joda 日期格式字符串解析日期时间字符串。
此函数是 [`formatDateTimeInJodaSyntax`](/zh/reference/functions/regular-functions/date-time-functions#formatDateTimeInJodaSyntax) 的逆操作。
它使用 Joda 风格的格式 String 解析 String 参数，并返回 DateTime 类型。
有关格式模式，请参阅 [Joda Time 文档](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html)。
**语法**
```sql theme={null}
parseDateTimeInJodaSyntax(time_string, format[, timezone])
```
**参数**
* `time_string` — 将被解析为 DateTime 的 String。[`String`](/zh/reference/data-types/string)
* `format` — Joda 语法格式字符串，用于指定如何解析 time\_string。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
根据 Joda 风格的格式字符串，从输入字符串解析得到的 DateTime。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─parseDateTimeInJodaSyntax('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│ 2025-01-04 23:00:00 │
└──────────────────────────────────────────────────────────────────────────┘
```
## parseDateTimeInJodaSyntaxOrNull
引入版本：v23.3.0
与 [`parseDateTimeInJodaSyntax`](#parseDateTimeInJodaSyntax) 相同，但在遇到无法解析的日期格式时返回 `NULL`。
**语法**
```sql theme={null}
parseDateTimeInJodaSyntaxOrNull(time_string, format[, timezone])
```
**参数**
* `time_string` — 要被解析为 DateTime 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 采用 Joda 语法的格式字符串，用于指定如何解析 time\_string。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串中解析得到的 DateTime；如果解析失败，则返回 NULL。[`Nullable(DateTime)`](/zh/reference/data-types/nullable)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─parseDateTimeInJodaSyntaxOrNull('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│ 2025-01-04 23:00:00 │
└────────────────────────────────────────────────────────────────────────────────┘
```
## parseDateTimeInJodaSyntaxOrZero
引入版本：v23.3.0
与 [`parseDateTimeInJodaSyntax`](#parseDateTimeInJodaSyntax) 相同，但遇到无法解析的日期格式时会返回零日期。
**语法**
```sql theme={null}
parseDateTimeInJodaSyntaxOrZero(time_string, format[, timezone])
```
**参数**
* `time_string` — 要解析为 DateTime 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 采用 Joda 语法的格式字符串，用于指定如何解析 time\_string。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析得到的 DateTime；如果解析失败，则返回零 DateTime。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─parseDateTimeInJodaSyntaxOrZero('2025-01-04 23:00:00', 'yyyy-MM-dd HH:mm:ss')─┐
│ 2025-01-04 23:00:00 │
└────────────────────────────────────────────────────────────────────────────────┘
```
## parseDateTimeOrNull
版本引入：v23.3.0
与 [`parseDateTime`](#parseDateTime) 相同，但遇到无法解析的日期格式时会返回 `NULL`。
**语法**
```sql theme={null}
parseDateTimeOrNull(time_string, format[, timezone])
```
**别名**: `str_to_date`
**参数**
* `time_string` — 要解析为 DateTime 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 指定如何解析 time\_string 的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析得到的 DateTime；如果解析失败，则返回 NULL。[`Nullable(DateTime)`](/zh/reference/data-types/nullable)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')
```
```response title=Response theme={null}
┌─parseDateTimeOrNull('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│ 2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘
```
## parseDateTimeOrZero
在以下版本中引入：v23.3.0
与 [`parseDateTime`](#parseDateTime) 相同，但在遇到无法解析的日期格式时会返回零日期。
**语法**
```sql theme={null}
parseDateTimeOrZero(time_string, format[, timezone])
```
**参数**
* `time_string` — 要解析为 DateTime 的字符串。[`String`](/zh/reference/data-types/string)
* `format` — 指定 `time_string` 解析方式的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回从输入字符串解析得到的 DateTime；如果解析失败，则返回零 DateTime。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')
```
```response title=Response theme={null}
┌─parseDateTimeOrZero('2025-01-04+23:00:00', '%Y-%m-%d+%H:%i:%s')─┐
│ 2025-01-04 23:00:00 │
└─────────────────────────────────────────────────────────────────┘
```
## reinterpret
引入版本：v1.1.0
对给定的值 `x`，使用其在内存中的同一源字节序列，并将其重新解释为目标类型。
**语法**
```sql theme={null}
reinterpret(x, type)
```
**参数**
* `x` — 任意类型。[`Any`](/zh/reference/data-types)
* `type` — 目标类型。若为数组，则其元素类型必须为定长类型。[`String`](/zh/reference/data-types/string)
**返回值**
目标类型的值。[`Any`](/zh/reference/data-types)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT reinterpret(toInt8(-1), 'UInt8') AS int_to_uint,
reinterpret(toInt8(1), 'Float32') AS int_to_float,
reinterpret('1', 'UInt32') AS string_to_int
```
```response title=Response theme={null}
┌─int_to_uint─┬─int_to_float─┬─string_to_int─┐
│ 255 │ 1e-45 │ 49 │
└─────────────┴──────────────┴───────────────┘
```
**Array 示例**
```sql title=Query theme={null}
SELECT reinterpret(x'3108b4403108d4403108b4403108d440', 'Array(Float32)') AS string_to_array_of_Float32
```
```response title=Response theme={null}
┌─string_to_array_of_Float32─┐
│ [5.626,6.626,5.626,6.626] │
└────────────────────────────┘
```
## reinterpretAsDate
引入版本：v1.1.0
将输入值重新解释为 Date 值 (假设采用小端字节序) ，即自 Unix 纪元 1970-01-01 起经过的天数
**语法**
```sql theme={null}
reinterpretAsDate(x)
```
**参数**
* `x` — 自 Unix 纪元起经过的天数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
日期。[`Date`](/zh/reference/data-types/date)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT reinterpretAsDate(65), reinterpretAsDate('A')
```
```response title=Response theme={null}
┌─reinterpretAsDate(65)─┬─reinterpretAsDate('A')─┐
│ 1970-03-07 │ 1970-03-07 │
└───────────────────────┴────────────────────────┘
```
## reinterpretAsDateTime
引入版本：v1.1.0
将输入值重新解释为 DateTime 值 (按小端字节序) ，即自 Unix 纪元 1970-01-01 开始以来的天数
**语法**
```sql theme={null}
reinterpretAsDateTime(x)
```
**参数**
* `x` — 自 Unix 纪元起经过的秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
日期和时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT reinterpretAsDateTime(65), reinterpretAsDateTime('A')
```
```response title=Response theme={null}
┌─reinterpretAsDateTime(65)─┬─reinterpretAsDateTime('A')─┐
│ 1970-01-01 01:01:05 │ 1970-01-01 01:01:05 │
└───────────────────────────┴────────────────────────────┘
```
## reinterpretAsFixedString
引入版本：v1.1.0
将输入值重新解释为定长字符串 (假定采用小端字节序) 。
末尾的 null 字节会被忽略。例如，对于 UInt32 值 255，该函数会返回一个仅包含单个字符的字符串。
**语法**
```sql theme={null}
reinterpretAsFixedString(x)
```
**参数**
* `x` — 要重新解释为字符串的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
包含表示 `x` 的字节的定长字符串。[`FixedString`](/zh/reference/data-types/fixedstring)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05')),
reinterpretAsFixedString(toDate('1970-03-07'))
```
```response title=Response theme={null}
┌─reinterpretAsFixedString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsFixedString(toDate('1970-03-07'))─┐
│ A │ A │
└─────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┘
```
## reinterpretAsFloat32
Introduced in: v1.1.0
将输入值重新解释为 Float32 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，输出结果则未定义。
**语法**
```sql theme={null}
reinterpretAsFloat32(x)
```
**参数**
* `x` — 要重新解释为 Float32 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Float32`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT reinterpretAsUInt32(toFloat32(0.2)) AS x, reinterpretAsFloat32(x)
```
```response title=Response theme={null}
┌──────────x─┬─reinterpretAsFloat32(x)─┐
│ 1045220557 │ 0.2 │
└────────────┴─────────────────────────┘
```
## reinterpretAsFloat64
在以下版本中引入：v1.1.0
将输入值重新解释为 Float64 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出未定义。
**语法**
```sql theme={null}
reinterpretAsFloat64(x)
```
**参数**
* `x` — 要重新解释为 Float64 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Float64`](/zh/reference/data-types/float)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT reinterpretAsUInt64(toFloat64(0.2)) AS x, reinterpretAsFloat64(x)
```
```response title=Response theme={null}
┌───────────────────x─┬─reinterpretAsFloat64(x)─┐
│ 4596373779694328218 │ 0.2 │
└─────────────────────┴─────────────────────────┘
```
## reinterpretAsInt128
首次引入于：v1.1.0
将输入值重新解释为 Int128 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，输出结果将是未定义的。
**语法**
```sql theme={null}
reinterpretAsInt128(x)
```
**参数**
* `x` — 要重新解释为 Int128 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Int128`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt64(257) AS x,
toTypeName(x),
reinterpretAsInt128(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int64 │ 257 │ Int128 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsInt16
首次引入于：v1.1.0
将输入值重新解释为 Int16 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsInt16(x)
```
**参数**
* `x` — 要重新解释为 Int16 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Int16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt8(257) AS x,
toTypeName(x),
reinterpretAsInt16(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ Int8 │ 1 │ Int16 │
└───┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsInt256
引入版本：v1.1.0
将输入值重新解释为 Int256 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsInt256(x)
```
**参数**
* `x` — 要重新解释为 Int256 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Int256`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt128(257) AS x,
toTypeName(x),
reinterpretAsInt256(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int128 │ 257 │ Int256 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsInt32
引入版本：v1.1.0
将输入值重新解释为 Int32 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsInt32(x)
```
**参数**
* `x` — 要重新解释为 Int32 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt16(257) AS x,
toTypeName(x),
reinterpretAsInt32(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int16 │ 257 │ Int32 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsInt64
引入版本：v1.1.0
将输入值重新解释为 Int64 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsInt64(x)
```
**参数**
* `x` — 要重新解释为 Int64 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt32(257) AS x,
toTypeName(x),
reinterpretAsInt64(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ Int32 │ 257 │ Int64 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsInt8
引入版本：v1.1.0
将输入值重新解释为 Int8 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示该输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsInt8(x)
```
**参数**
* `x` — 要重新解释为 Int8 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`Int8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toUInt8(257) AS x,
toTypeName(x),
reinterpretAsInt8(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8 │ 1 │ Int8 │
└───┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsString
引入版本：v1.1.0
将输入值重新解释为字符串 (假设采用小端字节序) 。
末尾的空字节会被忽略。例如，对于值为 255 的 UInt32，该函数会返回一个仅包含单个字符的字符串。
**语法**
```sql theme={null}
reinterpretAsString(x)
```
**参数**
* `x` — 要重新解释为字符串的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
包含表示 `x` 的字节序列的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
reinterpretAsString(toDateTime('1970-01-01 01:01:05')),
reinterpretAsString(toDate('1970-03-07'))
```
```response title=Response theme={null}
┌─reinterpretAsString(toDateTime('1970-01-01 01:01:05'))─┬─reinterpretAsString(toDate('1970-03-07'))─┐
│ A │ A │
└────────────────────────────────────────────────────────┴───────────────────────────────────────────┘
```
## reinterpretAsUInt128
首次引入于：v1.1.0
将输入值重新解释为 UInt128 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示该输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsUInt128(x)
```
**参数**
* `x` — 要重新解释为 UInt128 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`UInt128`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt64(257) AS x,
toTypeName(x),
reinterpretAsUInt128(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt64 │ 257 │ UInt128 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsUInt16
引入版本：v1.1.0
将输入值重新解释为 UInt16 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
**语法**
```sql theme={null}
reinterpretAsUInt16(x)
```
**参数**
* `x` — 要重新解释为 UInt16 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toUInt8(257) AS x,
toTypeName(x),
reinterpretAsUInt16(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌─x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 1 │ UInt8 │ 1 │ UInt16 │
└───┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsUInt256
Introduced in: v1.1.0
将输入值重新解释为 UInt256 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值；如果目标类型无法表示输入类型，则输出结果未定义。
**Syntax**
```sql theme={null}
reinterpretAsUInt256(x)
```
**参数**
* `x` — 要重新解释为 UInt256 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`UInt256`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toUInt128(257) AS x,
toTypeName(x),
reinterpretAsUInt256(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt128 │ 257 │ UInt256 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsUInt32
首次引入版本：v1.1.0
将输入值重新解释为 UInt32 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果是未定义的。
**语法**
```sql theme={null}
reinterpretAsUInt32(x)
```
**参数**
* `x` — 要重新解释为 UInt32 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的 `x` 值。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt16(257) AS x,
toTypeName(x),
reinterpretAsUInt32(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt16 │ 257 │ UInt32 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsUInt64
首次引入版本：v1.1.0
将输入值重新解释为 UInt64 类型的值。
与 [`CAST`](#CAST) 不同，此函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出未定义。
**语法**
```sql theme={null}
reinterpretAsUInt64(x)
```
**参数**
* `x` — 要重新解释为 UInt64 的值。[`Int*`](/zh/reference/data-types/int-uint) 或 [`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回 `x` 重新解释后的值。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt32(257) AS x,
toTypeName(x),
reinterpretAsUInt64(x) AS res,
toTypeName(res)
```
```response title=Response theme={null}
┌───x─┬─toTypeName(x)─┬─res─┬─toTypeName(res)─┐
│ 257 │ UInt32 │ 257 │ UInt64 │
└─────┴───────────────┴─────┴─────────────────┘
```
## reinterpretAsUInt8
Introduced in：v1.1.0
将输入值重新解释为 UInt8 类型的值。
与 [`CAST`](#CAST) 不同，该函数不会尝试保留原始值——如果目标类型无法表示输入类型，则输出结果未定义。
**Syntax**
```sql theme={null}
reinterpretAsUInt8(x)
```
**参数**
* `x` — 要重新解释为 UInt8 的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回重新解释后的值 `x`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt8(-1) AS val,
toTypeName(val),
reinterpretAsUInt8(val) AS res,
toTypeName(res);
```
```response title=Response theme={null}
┌─val─┬─toTypeName(val)─┬─res─┬─toTypeName(res)─┐
│ -1 │ Int8 │ 255 │ UInt8 │
└─────┴─────────────────┴─────┴─────────────────┘
```
## reinterpretAsUUID
首次引入版本：v1.1.0
接受一个 16 字节字符串，并将其中每个 8 字节半段按 little-endian 字节序解释后返回一个 UUID。如果字符串长度不足，函数会像在末尾补足所需数量的空字节一样处理；如果字符串长度超过 16 字节，则会忽略末尾多出的字节。
**语法**
```sql theme={null}
reinterpretAsUUID(fixed_string)
```
**参数**
* `fixed_string` — 大端字节串。[`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
UUID 类型的值。[`UUID`](/zh/reference/data-types/uuid)
**示例**
**字符串转换为 UUID**
```sql title=Query theme={null}
SELECT reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))
```
```response title=Response theme={null}
┌─reinterpretAsUUID(reverse(unhex('000102030405060708090a0b0c0d0e0f')))─┐
│ 08090a0b-0c0d-0e0f-0001-020304050607 │
└───────────────────────────────────────────────────────────────────────┘
```
## toBFloat16
引入版本：v1.1.0
将输入值转换为 BFloat16 类型的值。
如果发生错误，会抛出异常。
另请参见：
* [`toBFloat16OrZero`](#toBFloat16OrZero)。
* [`toBFloat16OrNull`](#toBFloat16OrNull)。
**语法**
```sql theme={null}
toBFloat16(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 16 位 brain-float 类型的值。[`BFloat16`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toBFloat16(toFloat32(42.7)),
toBFloat16(toFloat32('42.7')),
toBFloat16('42.7')
FORMAT Vertical;
```
```response title=Response theme={null}
toBFloat16(toFloat32(42.7)): 42.5
toBFloat16(t⋯32('42.7')): 42.5
toBFloat16('42.7'): 42.5
```
## toBFloat16OrNull
引入于：v1.1.0
将 String 输入值转换为 BFloat16 类型的值。
如果字符串不表示浮点值，则该函数返回 NULL。
支持的参数：
* 数值的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* 二进制和十六进制值的字符串表示形式。
* 数值。
该函数在从字符串表示形式转换时，允许静默丢失精度。
另请参见：
* [`toBFloat16`](#toBFloat16).
* [`toBFloat16OrZero`](#toBFloat16OrZero).
**语法**
```sql theme={null}
toBFloat16OrNull(x)
```
**参数**
* `x` — 数字的 `String` 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 16 位 brain-float 值；否则返回 `NULL`。[`BFloat16`](/zh/reference/data-types/float) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toBFloat16OrNull('0x5E'), -- 不支持的参数
toBFloat16OrNull('12.3'), -- 典型用法
toBFloat16OrNull('12.3456789') -- 精度静默丢失
```
```response title=Response theme={null}
\N
12.25
12.3125
```
## toBFloat16OrZero
引入版本：v1.1.0
将 String 输入值转换为 BFloat16 类型的值。
如果该字符串不表示浮点数值，则函数返回零。
支持的参数：
* 数值的字符串表示形式。
不支持的参数 (返回 `0`) ：
* 二进制和十六进制值的字符串表示形式。
* 数值。
该函数允许在从字符串表示形式转换时静默丢失精度。
另请参见：
* [`toBFloat16`](#toBFloat16).
* [`toBFloat16OrNull`](#toBFloat16OrNull).
**语法**
```sql theme={null}
toBFloat16OrZero(x)
```
**参数**
* `x` — 数字的 `String` 表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 16 位 brain-float 值；否则返回 `0`。[`BFloat16`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toBFloat16OrZero('0x5E'), -- 不支持的参数
toBFloat16OrZero('12.3'), -- 典型用法
toBFloat16OrZero('12.3456789') -- 静默精度损失
```
```response title=Response theme={null}
0
12.25
12.3125
```
## toBool
Introduced in：v22.2.0
将输入值转换为 Bool 类型。
**语法**
```sql theme={null}
toBool(expr)
```
**参数**
* `expr` — 返回数值或字符串的表达式。对于字符串，可接受 'true' 或 'false' (不区分大小写) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string) 或 [`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
根据参数的求值结果，返回 `true` 或 `false`。[`Bool`](/zh/reference/data-types/boolean)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toBool(toUInt8(1)),
toBool(toInt8(-1)),
toBool(toFloat32(1.01)),
toBool('true'),
toBool('false'),
toBool('FALSE')
FORMAT Vertical
```
```response title=Response theme={null}
toBool(toUInt8(1)): true
toBool(toInt8(-1)): true
toBool(toFloat32(1.01)): true
toBool('true'): true
toBool('false'): false
toBool('FALSE'): false
```
## toDate
引入版本：v1.1.0
将输入值转换为 [`Date`](/zh/reference/data-types/date) 类型。
支持从 String、FixedString、DateTime 或数值类型转换。
**语法**
```sql theme={null}
toDate(x)
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回转换后的输入值。[`Date`](/zh/reference/data-types/date)
**示例**
**将 String 转换为 Date**
```sql title=Query theme={null}
SELECT toDate('2025-04-15')
```
```response title=Response theme={null}
2025-04-15
```
**将 DateTime 转换为 Date**
```sql title=Query theme={null}
SELECT toDate(toDateTime('2025-04-15 10:30:00'))
```
```response title=Response theme={null}
2025-04-15
```
**整数转换为日期**
```sql title=Query theme={null}
SELECT toDate(20297)
```
```response title=Response theme={null}
2025-07-28
```
## toDate32
引入版本：v21.9.0
将参数转换为 [Date32](/zh/reference/data-types/date32) 数据类型。
如果值超出范围，`toDate32` 会返回 [Date32](/zh/reference/data-types/date32) 支持的边界值。
如果参数类型为 [`Date`](/zh/reference/data-types/date)，则会考虑其取值边界。
**语法**
```sql theme={null}
toDate32(expr)
```
**参数**
* `expr` — 要转换的值。[`String`](/zh/reference/data-types/string) 或 [`UInt32`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date)
**返回值**
返回一个日历日期。[`Date32`](/zh/reference/data-types/date32)
**示例**
**在取值范围内**
```sql title=Query theme={null}
SELECT toDate32('2025-01-01') AS value, toTypeName(value)
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
value: 2025-01-01
toTypeName(value): Date32
```
**超出取值范围**
```sql title=Query theme={null}
SELECT toDate32('1899-01-01') AS value, toTypeName(value)
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
value: 1900-01-01
toTypeName(value): Date32
```
## toDate32OrDefault
引入版本：v21.11.0
将参数转换为 [Date32](/zh/reference/data-types/date32) 数据类型。如果该值超出范围，`toDate32OrDefault` 会返回 [Date32](/zh/reference/data-types/date32) 支持的下限值。如果参数的类型为 [Date](/zh/reference/data-types/date)，则会考虑其边界。如果接收到无效参数，则返回默认值。
**语法**
```sql theme={null}
toDate32OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数字或数字字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Date32`](/zh/reference/data-types/date32)
**返回值**
成功时返回 `Date32` 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 1900-01-01。[`Date32`](/zh/reference/data-types/date32)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toDate32OrDefault('1930-01-01', toDate32('2020-01-01'))
```
```response title=Response theme={null}
1930-01-01
```
**转换失败**
```sql title=Query theme={null}
SELECT toDate32OrDefault('xx1930-01-01', toDate32('2020-01-01'))
```
```response title=Response theme={null}
2020-01-01
```
## toDate32OrNull
引入版本：v21.9.0
将输入值转换为 Date32 类型的值；如果参数无效，则返回 `NULL`。
与 [`toDate32`](#toDate32) 相同，但在参数无效时会返回 `NULL`。
**语法**
```sql theme={null}
toDate32OrNull(x)
```
**参数**
* `x` — 日期的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 Date32 值，否则返回 `NULL`。[`Date32`](/zh/reference/data-types/date32) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDate32OrNull('2025-01-01'), toDate32OrNull('invalid')
```
```response title=Response theme={null}
┌─toDate32OrNull('2025-01-01')─┬─toDate32OrNull('invalid')─┐
│ 2025-01-01 │ ᴺᵁᴸᴸ │
└──────────────────────────────┴───────────────────────────┘
```
## toDate32OrZero
引入版本：v21.9.0
将输入值转换为 [Date32](/zh/reference/data-types/date32) 类型的值；如果收到无效参数，则返回 [Date32](/zh/reference/data-types/date32) 的下界值。
与 [toDate32](#toDate32) 相同，但如果收到无效参数，则返回 [Date32](/zh/reference/data-types/date32) 的下界值。
另请参见：
* [`toDate32`](#toDate32)
* [`toDate32OrNull`](#toDate32OrNull)
* [`toDate32OrDefault`](#toDate32OrDefault)
**语法**
```sql theme={null}
toDate32OrZero(x)
```
**参数**
* `x` — 日期的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 Date32 值，否则返回 Date32 的下界值 (`1900-01-01`) 。[`Date32`](/zh/reference/data-types/date32)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDate32OrZero('2025-01-01'), toDate32OrZero('')
```
```response title=Response theme={null}
┌─toDate32OrZero('2025-01-01')─┬─toDate32OrZero('')─┐
│ 2025-01-01 │ 1900-01-01 │
└──────────────────────────────┴────────────────────┘
```
## toDateOrDefault
引入版本：v21.11.0
与 [toDate](#toDate) 类似，但如果转换失败，则返回默认值：若指定了第二个参数，则返回该参数；否则返回 [Date](/zh/reference/data-types/date) 的下界值。
**语法**
```sql theme={null}
toDateOrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Date`](/zh/reference/data-types/date)
**返回值**
如果转换成功，则返回 Date 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 1970-01-01。[`Date`](/zh/reference/data-types/date)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toDateOrDefault('2022-12-30')
```
```response title=Response theme={null}
2022-12-30
```
**转换失败**
```sql title=Query theme={null}
SELECT toDateOrDefault('', CAST('2023-01-01', 'Date'))
```
```response title=Response theme={null}
2023-01-01
```
## toDateOrNull
首次引入版本：v1.1.0
将输入值转换为 `Date` 类型的值；如果参数无效，则返回 `NULL`。
与 [`toDate`](#toDate) 相同，但在参数无效时返回 `NULL`。
**语法**
```sql theme={null}
toDateOrNull(x)
```
**参数**
* `x` — 日期的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 `Date` 值，否则返回 `NULL`。[`Date`](/zh/reference/data-types/date) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDateOrNull('2025-12-30'), toDateOrNull('invalid')
```
```response title=Response theme={null}
┌─toDateOrNull('2025-12-30')─┬─toDateOrNull('invalid')─┐
│ 2025-12-30 │ ᴺᵁᴸᴸ │
└────────────────────────────┴────────────────────────┘
```
## toDateOrZero
引入版本：v1.1.0
将输入值转换为 [`Date`](/zh/reference/data-types/date) 类型的值；如果传入的是无效参数，则返回 [`Date`](/zh/reference/data-types/date) 的下界值。
与 [toDate](#toDate) 相同，但如果传入的是无效参数，则返回 [`Date`](/zh/reference/data-types/date) 的下界值。
另请参见：
* [`toDate`](#toDate)
* [`toDateOrNull`](#toDateOrNull)
* [`toDateOrDefault`](#toDateOrDefault)
**语法**
```sql theme={null}
toDateOrZero(x)
```
**参数**
* `x` — 日期的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 Date 值，否则返回 Date 的下界值 (`1970-01-01`) 。[`Date`](/zh/reference/data-types/date)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDateOrZero('2025-12-30'), toDateOrZero('')
```
```response title=Response theme={null}
┌─toDateOrZero('2025-12-30')─┬─toDateOrZero('')─┐
│ 2025-12-30 │ 1970-01-01 │
└────────────────────────────┴──────────────────┘
```
## toDateTime
引入于：v1.1.0
将输入值转换为 [DateTime](/zh/reference/data-types/datetime) 类型。
如果 `expr` 是数值，则会将其解释为自 Unix 纪元开始以来的秒数 (即 Unix timestamp) 。
如果 `expr` 是 [String](/zh/reference/data-types/string)，则可能会将其解释为 Unix timestamp，或解释为日期 / 日期时间的字符串表示形式。
因此，由于存在歧义，较短数字的字符串表示形式 (最多 4 位) 会明确禁用解析。例如，字符串 `'1999'` 既可能表示年份 (Date / DateTime 的不完整字符串表示形式) ，也可能是 Unix timestamp。更长的数字字符串则允许解析。
**语法**
```sql theme={null}
toDateTime(expr[, time_zone])
```
**参数**
* `expr` — 值。[`String`](/zh/reference/data-types/string) 或 [`Int`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
* `time_zone` — 时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回日期时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDateTime('2025-01-01 00:00:00'), toDateTime(1735689600, 'UTC')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toDateTime('2025-01-01 00:00:00'): 2025-01-01 00:00:00
toDateTime(1735689600, 'UTC'): 2025-01-01 00:00:00
```
## toDateTime32
Introduced in: v20.9.0
将输入值转换为 `DateTime` 类型。
支持从 `String`、`FixedString`、`Date`、`Date32`、`DateTime` 或数值类型 (`(U)Int*`、`Float*`、`Decimal`) 转换。
与 `DateTime` 相比，DateTime32 的取值范围更大，支持 `1900-01-01` 至 `2299-12-31` 的日期。
**Syntax**
```sql theme={null}
toDateTime32(x[, timezone])
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回的 `DateTime` 值使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回转换后的输入值。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**值在范围内**
```sql title=Query theme={null}
SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);
```
```response title=Response theme={null}
┌───────────────────value─┬─toTypeName(toDateTime64('20255-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3) │
└─────────────────────────┴────────────────────────────────────────────────────────┘
```
**作为指定精度的 Decimal 值**
```sql title=Query theme={null}
SELECT toDateTime64(1735689600.000, 3) AS value, toTypeName(value);
-- 没有小数点时，该值仍被视为以秒为单位的 Unix 时间戳
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);
```
```response title=Response theme={null}
┌───────────────────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) │
└─────────────────────────┴────────────────────────────────────────────┘
```
**指定时区**
```sql title=Query theme={null}
SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);
```
```response title=Response theme={null}
┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul') │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────┘
```
## toDateTime64
引入版本：v20.1.0
将输入值转换为 [`DateTime64`](/zh/reference/data-types/datetime64) 类型的值。
**语法**
```sql theme={null}
toDateTime64(expr, scale[, timezone])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `scale` — 时间粒度 (精度) ：10^(-scale) 秒。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。指定 `DateTime64` 对象的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回具有子秒级精度的日历日期和时间。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**值在范围内**
```sql title=Query theme={null}
SELECT toDateTime64('2025-01-01 00:00:00.000', 3) AS value, toTypeName(value);
```
```response title=Response theme={null}
┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00.000', 3))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3) │
└─────────────────────────┴────────────────────────────────────────────────────────┘
```
**作为指定精度的 Decimal**
```sql title=Query theme={null}
SELECT toDateTime64(1546300800.000, 3) AS value, toTypeName(value);
-- 没有小数点时，该值仍被视为以秒为单位的 Unix 时间戳
SELECT toDateTime64(1546300800000, 3) AS value, toTypeName(value);
```
```response title=Response theme={null}
┌───────────────────value─┬─toTypeName(toDateTime64(1546300800000, 3))─┐
│ 2282-12-31 00:00:00.000 │ DateTime64(3) │
└─────────────────────────┴────────────────────────────────────────────┘
```
**指定时区**
```sql title=Query theme={null}
SELECT toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul') AS value, toTypeName(value);
```
```response title=Response theme={null}
┌───────────────────value─┬─toTypeName(toDateTime64('2025-01-01 00:00:00', 3, 'Asia/Istanbul'))─┐
│ 2025-01-01 00:00:00.000 │ DateTime64(3, 'Asia/Istanbul') │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────┘
```
## toDateTime64OrDefault
引入版本：v21.11.0
与 [toDateTime64](#toDateTime64) 类似，此函数会将输入值转换为 [DateTime64](/zh/reference/data-types/datetime64) 类型的值，
但如果收到无效参数，则返回 [DateTime64](/zh/reference/data-types/datetime64) 的默认值
或提供的默认值。
**语法**
```sql theme={null}
toDateTime64OrDefault(expr, scale[, timezone, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `scale` — 时间粒度 (精度) ：10^-precision 秒。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
* `default` — 可选。解析失败时返回的默认值。[`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
成功时返回 DateTime64 类型的值；否则，如果传入了默认值则返回该默认值，若未传入则返回 1970-01-01 00:00:00.000。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**成功转换**
```sql title=Query theme={null}
SELECT toDateTime64OrDefault('1976-10-18 00:00:00.30', 3)
```
```response title=Response theme={null}
1976-10-18 00:00:00.300
```
**转换失败**
```sql title=Query theme={null}
SELECT toDateTime64OrDefault('1976-10-18 00:00:00 30', 3, 'UTC', toDateTime64('2001-01-01 00:00:00.00',3))
```
```response title=Response theme={null}
2000-12-31 23:00:00.000
```
## toDateTime64OrNull
引入版本：v20.1.0
将输入值转换为 `DateTime64` 类型的值；如果接收到无效参数，则返回 `NULL`。
与 `toDateTime64` 相同，但如果接收到无效参数，则返回 `NULL`。
**语法**
```sql theme={null}
toDateTime64OrNull(x)
```
**参数**
* `x` — 带有子秒级精度的日期时间字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
如果成功，则返回 DateTime64 值；否则返回 `NULL`。[`DateTime64`](/zh/reference/data-types/datetime64) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDateTime64OrNull('2025-12-30 13:44:17.123'), toDateTime64OrNull('invalid')
```
```response title=Response theme={null}
┌─toDateTime64OrNull('2025-12-30 13:44:17.123')─┬─toDateTime64OrNull('invalid')─┐
│ 2025-12-30 13:44:17.123 │ ᴺᵁᴸᴸ │
└─────────────────────────────────────────────────┴───────────────────────────────┘
```
## toDateTime64OrZero
引入版本：v20.1.0
将输入值转换为 [DateTime64](/zh/reference/data-types/datetime64) 类型的值；如果接收到无效参数，则返回 [DateTime64](/zh/reference/data-types/datetime64) 的下界值。
与 [toDateTime64](#toDateTime64) 相同，但在接收到无效参数时会返回 [DateTime64](/zh/reference/data-types/datetime64) 的下界值。
另请参见：
* [toDateTime64](#toDateTime64)。
* [toDateTime64OrNull](#toDateTime64OrNull)。
* [toDateTime64OrDefault](#toDateTime64OrDefault)。
**语法**
```sql theme={null}
toDateTime64OrZero(x)
```
**参数**
* `x` — 带有子秒级精度的日期时间字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 DateTime64 值，否则返回 DateTime64 的下界值 (`1970-01-01 00:00:00.000`) 。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDateTime64OrZero('2025-12-30 13:44:17.123'), toDateTime64OrZero('invalid')
```
```response title=Response theme={null}
┌─toDateTime64OrZero('2025-12-30 13:44:17.123')─┬─toDateTime64OrZero('invalid')─┐
│ 2025-12-30 13:44:17.123 │ 1970-01-01 00:00:00.000 │
└─────────────────────────────────────────────────┴─────────────────────────────────────┘
```
## toDateTimeOrDefault
引入版本：v21.11.0
与 [toDateTime](#toDateTime) 类似，但如果转换失败，则返回默认值：若指定了第三个参数，则返回该参数；否则返回 [DateTime](/zh/reference/data-types/datetime) 的下界值。
**语法**
```sql theme={null}
toDateTimeOrDefault(expr[, timezone, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
* `default` — 可选。解析失败时返回的默认值。[`DateTime`](/zh/reference/data-types/datetime)
**返回值**
成功时返回 `DateTime` 类型的值；否则如果传入了默认值，则返回该默认值；若未传入，则返回 `1970-01-01 00:00:00`。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toDateTimeOrDefault('2022-12-30 13:44:17')
```
```response title=Response theme={null}
2022-12-30 13:44:17
```
**转换失败**
```sql title=Query theme={null}
SELECT toDateTimeOrDefault('', 'UTC', CAST('2023-01-01', 'DateTime(\'UTC\')'))
```
```response title=Response theme={null}
2023-01-01 00:00:00
```
## toDateTimeOrNull
引入版本：v1.1.0
将输入值转换为 `DateTime` 类型的值；如果接收到无效参数，则返回 `NULL`。
与 [`toDateTime`](#toDateTime) 相同，但在接收到无效参数时会返回 `NULL`。
**语法**
```sql theme={null}
toDateTimeOrNull(x)
```
**参数**
* `x` — 日期时间的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 `DateTime` 值，否则返回 `NULL`。[`DateTime`](/zh/reference/data-types/datetime) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDateTimeOrNull('2025-12-30 13:44:17'), toDateTimeOrNull('invalid')
```
```response title=Response theme={null}
┌─toDateTimeOrNull('2025-12-30 13:44:17')─┬─toDateTimeOrNull('invalid')─┐
│ 2025-12-30 13:44:17 │ ᴺᵁᴸᴸ │
└─────────────────────────────────────────┴─────────────────────────────┘
```
## toDateTimeOrZero
引入版本：v1.1.0
将输入值转换为 [DateTime](/zh/reference/data-types/datetime) 类型的值；如果收到无效参数，则返回 [DateTime](/zh/reference/data-types/datetime) 的下界值。
与 [toDateTime](#toDateTime) 相同，但如果收到无效参数，则返回 [DateTime](/zh/reference/data-types/datetime) 的下界值。
**语法**
```sql theme={null}
toDateTimeOrZero(x)
```
**参数**
* `x` — 日期时间的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
如果成功，则返回 DateTime 值；否则返回 DateTime 的下界值 (`1970-01-01 00:00:00`) 。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDateTimeOrZero('2025-12-30 13:44:17'), toDateTimeOrZero('invalid')
```
```response title=Response theme={null}
┌─toDateTimeOrZero('2025-12-30 13:44:17')─┬─toDateTimeOrZero('invalid')─┐
│ 2025-12-30 13:44:17 │ 1970-01-01 00:00:00 │
└─────────────────────────────────────────┴─────────────────────────────┘
```
## toDecimal128
引入版本：v18.12.0
将输入值转换为标度为 `S` 的 [`Decimal(38, S)`](/zh/reference/data-types/decimal) 类型值。
出错时会抛出异常。
支持的参数：
* (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`
**语法**
```sql theme={null}
toDecimal128(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
* `S` — 取值范围为 0 到 38 的 scale 参数，用于指定数值的小数部分可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
返回类型为 `Decimal(38, S)` 的值 [`Decimal128(S)`](/zh/reference/data-types/decimal)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toDecimal128(99, 1) AS a, toTypeName(a) AS type_a,
toDecimal128(99.67, 2) AS b, toTypeName(b) AS type_b,
toDecimal128('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
a: 99
type_a: Decimal(38, 1)
b: 99.67
type_b: Decimal(38, 2)
c: 99.67
type_c: Decimal(38, 3)
```
## toDecimal128OrDefault
Introduced in: v21.11.0
与 [`toDecimal128`](#toDecimal128) 类似，此函数将输入值转换为 [Decimal(38, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误，则返回默认值。
**语法**
```sql theme={null}
toDecimal128OrDefault(expr, S[, default])
```
**参数**
* `expr` — 数字的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
* `S` — 介于 0 到 38 之间的 scale 参数，用于指定数字的小数部分可包含的位数。[`UInt8`](/zh/reference/data-types/int-uint)
* `default` — 可选。如果解析为 Decimal128(S) 类型失败，则返回此默认值。[`Decimal128(S)`](/zh/reference/data-types/decimal)
**返回值**
成功时返回 Decimal(38, S) 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`Decimal128(S)`](/zh/reference/data-types/decimal)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toDecimal128OrDefault(toString(1/42), 18)
```
```response title=Response theme={null}
0.023809523809523808
```
**转换失败**
```sql title=Query theme={null}
SELECT toDecimal128OrDefault('Inf', 0, CAST('-1', 'Decimal128(0)'))
```
```response title=Response theme={null}
-1
```
## toDecimal128OrNull
引入版本：v20.1.0
将输入值转换为 [`Decimal(38, S)`](/zh/reference/data-types/decimal) 类型的值；如果出错，则返回 `NULL`。
与 [`toDecimal128`](#toDecimal128) 类似，但在转换出错时返回 `NULL`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值 `NaN` 和 `Inf` 及其字符串表示形式 (不区分大小写) 。
* 二进制值和十六进制值的字符串表示形式。
* 超出 `Decimal128` 取值范围的值：`(-1*10^(38 - S), 1*10^(38 - S))`。
另请参阅：
* [`toDecimal128`](#toDecimal128)。
* [`toDecimal128OrZero`](#toDecimal128OrZero)。
* [`toDecimal128OrDefault`](#toDecimal128OrDefault)。
**语法**
```sql theme={null}
toDecimal128OrNull(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 38 之间的 scale 参数，用于指定数值的小数部分可包含的位数。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Decimal(38, S) 值，否则返回 `NULL`。[`Decimal128(S)`](/zh/reference/data-types/decimal) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDecimal128OrNull('42.7', 2), toDecimal128OrNull('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal128OrNull('42.7', 2)─┬─toDecimal128OrNull('invalid', 2)─┐
│ 42.70 │ ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘
```
## toDecimal128OrZero
引入版本：v20.1.0
将输入值转换为 [Decimal(38, S)](/zh/reference/data-types/decimal) 类型的值；如果出错，则返回 `0`。
与 [`toDecimal128`](#toDecimal128) 类似，但在转换出错时返回 `0`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值 `NaN` 和 `Inf`，或其字符串表示形式 (不区分大小写) 。
* 二进制值和十六进制值的字符串表示形式。
如果输入值超出 `Decimal128` 的范围：`(-1*10^(38 - S), 1*10^(38 - S))`，函数将返回 `0`。
**语法**
```sql theme={null}
toDecimal128OrZero(expr, S)
```
**参数**
* `expr` — 返回数字或数字字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 取值范围为 0 到 38 的 scale 参数，用于指定数字的小数部分最多可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Decimal(38, S) 值，否则返回 `0`。[`Decimal128(S)`](/zh/reference/data-types/decimal)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT toDecimal128OrZero('42.7', 2), toDecimal128OrZero('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal128OrZero('42.7', 2)─┬─toDecimal128OrZero('invalid', 2)─┐
│ 42.70 │ 0.00 │
└───────────────────────────────┴──────────────────────────────────┘
```
## toDecimal256
引入版本：v20.8.0
将输入值转换为带有 `S` 标度的 [`Decimal(76, S)`](/zh/reference/data-types/decimal) 类型的值。出错时会抛出异常。
支持的参数：
* (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`
**语法**
```sql theme={null}
toDecimal256(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 76 之间的 scale 参数，指定数值的小数部分可包含的位数。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
返回一个 `Decimal(76, S)` 类型的值。[`Decimal256(S)`](/zh/reference/data-types/decimal)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toDecimal256(99, 1) AS a, toTypeName(a) AS type_a,
toDecimal256(99.67, 2) AS b, toTypeName(b) AS type_b,
toDecimal256('99.67', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
a: 99
type_a: Decimal(76, 1)
b: 99.67
type_b: Decimal(76, 2)
c: 99.67
type_c: Decimal(76, 3)
```
## toDecimal256OrDefault
引入版本：v21.11.0
与 [`toDecimal256`](#toDecimal256) 类似，此函数会将输入值转换为 [Decimal(76, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误，则返回默认值。
**语法**
```sql theme={null}
toDecimal256OrDefault(expr, S[, default])
```
**参数**
* `expr` — 数字的 `String` 表示形式。[`String`](/zh/reference/data-types/string)
* `S` — 介于 0 到 76 之间的 scale 参数，用于指定数字的小数部分可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
* `default` — 可选。如果解析为 Decimal256(S) 类型失败，则返回该默认值。[`Decimal256(S)`](/zh/reference/data-types/decimal)
**返回值**
成功时返回 `Decimal(76, S)` 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 `0`。[`Decimal256(S)`](/zh/reference/data-types/decimal)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toDecimal256OrDefault(toString(1/42), 76)
```
```response title=Response theme={null}
0.023809523809523808
```
**转换失败**
```sql title=Query theme={null}
SELECT toDecimal256OrDefault('Inf', 0, CAST('-1', 'Decimal256(0)'))
```
```response title=Response theme={null}
-1
```
## toDecimal256OrNull
引入版本：v20.8.0
将输入值转换为 [`Decimal(76, S)`](/zh/reference/data-types/decimal) 类型的值，但如果出错则返回 `NULL`。
与 [`toDecimal256`](#toDecimal256) 类似，但在转换出错时返回 `NULL`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 类型的 `NaN` 和 `Inf` 值，或其字符串表示形式 (不区分大小写) 。
* 二进制和十六进制值的字符串表示形式。
* 超出 `Decimal256` 取值范围的值：`(-1 * 10^(76 - S), 1 * 10^(76 - S))`。
另请参阅：
* [`toDecimal256`](#toDecimal256)。
* [`toDecimal256OrZero`](#toDecimal256OrZero)。
* [`toDecimal256OrDefault`](#toDecimal256OrDefault)。
**语法**
```sql theme={null}
toDecimal256OrNull(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 取值范围为 0 到 76 的 scale 参数，用于指定数值的小数部分最多可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `Decimal(76, S)` 值，否则返回 `NULL`。[`Decimal256(S)`](/zh/reference/data-types/decimal) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDecimal256OrNull('42.7', 2), toDecimal256OrNull('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal256OrNull('42.7', 2)─┬─toDecimal256OrNull('invalid', 2)─┐
│ 42.70 │ ᴺᵁᴸᴸ │
└───────────────────────────────┴──────────────────────────────────┘
```
## toDecimal256OrZero
引入版本：v20.8.0
将输入值转换为 [Decimal(76, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误则返回 `0`。
与 [`toDecimal256`](#toDecimal256) 类似，但在转换出错时返回 `0`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值 `NaN` 和 `Inf`，以及它们的字符串表示形式 (不区分大小写) 。
* 二进制和十六进制值的字符串表示形式。
如果输入值超出 `Decimal256` 的范围：`(-1*10^(76 - S), 1*10^(76 - S))`，函数将返回 `0`。
另请参阅：
* [`toDecimal256`](#toDecimal256)。
* [`toDecimal256OrNull`](#toDecimal256OrNull)。
* [`toDecimal256OrDefault`](#toDecimal256OrDefault)。
**语法**
```sql theme={null}
toDecimal256OrZero(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 76 之间的 scale 参数，用于指定数值的小数部分最多可包含多少位数字。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Decimal(76, S) 值，否则返回 `0`。[`Decimal256(S)`](/zh/reference/data-types/decimal)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDecimal256OrZero('42.7', 2), toDecimal256OrZero('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal256OrZero('42.7', 2)─┬─toDecimal256OrZero('invalid', 2)─┐
│ 42.70 │ 0.00 │
└───────────────────────────────┴──────────────────────────────────┘
```
## toDecimal32
引入版本：v18.12.0
将输入值转换为 [`Decimal(9, S)`](/zh/reference/data-types/decimal) 类型、标度为 `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`
**语法**
```sql theme={null}
toDecimal32(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 取值范围为 0 到 9 的 scale 参数，用于指定数值的小数部分可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
返回类型为 `Decimal(9, S)` 的值 [`Decimal32(S)`](/zh/reference/data-types/decimal)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toDecimal32(2, 1) AS a, toTypeName(a) AS type_a,
toDecimal32(4.2, 2) AS b, toTypeName(b) AS type_b,
toDecimal32('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
a: 2
type_a: Decimal(9, 1)
b: 4.2
type_b: Decimal(9, 2)
c: 4.2
type_c: Decimal(9, 3)
```
## toDecimal32OrDefault
Introduced in：v21.11.0
与 [`toDecimal32`](#toDecimal32) 类似，此函数会将输入值转换为 [Decimal(9, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误，则返回默认值。
**语法**
```sql theme={null}
toDecimal32OrDefault(expr, S[, default])
```
**参数**
* `expr` — 数字的 `String` 表示形式。[`String`](/zh/reference/data-types/string)
* `S` — 介于 0 到 9 之间的 scale 参数，用于指定数字的小数部分可有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
* `default` — 可选。如果解析为 Decimal32(S) 类型失败，则返回此默认值。[`Decimal32(S)`](/zh/reference/data-types/decimal)
**返回值**
成功时返回 Decimal(9, S) 类型的值；否则，如果传入了默认值则返回该值，未传入则返回 0。[`Decimal32(S)`](/zh/reference/data-types/decimal)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toDecimal32OrDefault(toString(0.0001), 5)
```
```response title=Response theme={null}
0.0001
```
**转换失败**
```sql title=Query theme={null}
SELECT toDecimal32OrDefault('Inf', 0, CAST('-1', 'Decimal32(0)'))
```
```response title=Response theme={null}
-1
```
## toDecimal32OrNull
引入版本：v20.1.0
将输入值转换为 [`Decimal(9, S)`](/zh/reference/data-types/decimal) 类型的值；如果发生错误，则返回 `NULL`。
与 [`toDecimal32`](#toDecimal32) 类似，但在转换出错时会返回 `NULL`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 类型的 `NaN` 和 `Inf` 值，或其字符串表示形式 (不区分大小写) 。
* 二进制值和十六进制值的字符串表示形式。
* 超出 `Decimal32` 取值范围的值：`(-1*10^(9 - S), 1*10^(9 - S))`。
另请参见：
* [`toDecimal32`](#toDecimal32)。
* [`toDecimal32OrZero`](#toDecimal32OrZero)。
* [`toDecimal32OrDefault`](#toDecimal32OrDefault)。
**语法**
```sql theme={null}
toDecimal32OrNull(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 和 9 之间的 scale 参数，指定数值的小数部分可包含的位数。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Decimal(9, S) 值，否则返回 `NULL`。[`Decimal32(S)`](/zh/reference/data-types/decimal) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDecimal32OrNull('42.7', 2), toDecimal32OrNull('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal32OrNull('42.7', 2)─┬─toDecimal32OrNull('invalid', 2)─┐
│ 42.70 │ ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘
```
## toDecimal32OrZero
引入版本：v20.1.0
将输入值转换为 [Decimal(9, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误则返回 `0`。
与 [`toDecimal32`](#toDecimal32) 类似，但在转换出错时会返回 `0`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值 `NaN` 和 `Inf`，以及它们的字符串表示形式 (不区分大小写) 。
* 二进制和十六进制值的字符串表示形式。
如果输入值超出 `Decimal32` 的范围：`(-1*10^(9 - S), 1*10^(9 - S))`，则函数返回 `0`。
**语法**
```sql theme={null}
toDecimal32OrZero(expr, S)
```
**参数**
* `expr` — 返回数值或数值的字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 9 之间的 scale 参数，用于指定数值的小数部分可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `Decimal(9, S)` 值，否则返回 `0`。[`Decimal32(S)`](/zh/reference/data-types/decimal)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDecimal32OrZero('42.7', 2), toDecimal32OrZero('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal32OrZero('42.7', 2)─┬─toDecimal32OrZero('invalid', 2)─┐
│ 42.70 │ 0.00 │
└──────────────────────────────┴─────────────────────────────────┘
```
## toDecimal64
引入版本：v18.12.0
将输入值转换为标度为 `S` 的 [`Decimal(18, S)`](/zh/reference/data-types/decimal) 类型值。
出错时会抛出异常。
支持的参数：
* (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`
**语法**
```sql theme={null}
toDecimal64(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 18 之间的 scale 参数，用于指定数值的小数部分可以有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
返回一个 Decimal 值。[`Decimal(18, S)`](/zh/reference/data-types/decimal)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toDecimal64(2, 1) AS a, toTypeName(a) AS type_a,
toDecimal64(4.2, 2) AS b, toTypeName(b) AS type_b,
toDecimal64('4.2', 3) AS c, toTypeName(c) AS type_c
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
a: 2.0
type_a: Decimal(18, 1)
b: 4.20
type_b: Decimal(18, 2)
c: 4.200
type_c: Decimal(18, 3)
```
## toDecimal64OrDefault
首次引入版本：v21.11.0
与 [`toDecimal64`](#toDecimal64) 类似，此函数会将输入值转换为 [Decimal(18, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误，则返回默认值。
**语法**
```sql theme={null}
toDecimal64OrDefault(expr, S[, default])
```
**参数**
* `expr` — 数字的 `String` 字符串表示形式。[`String`](/zh/reference/data-types/string)
* `S` — 介于 0 到 18 之间的 scale 参数，用于指定数字的小数部分最多可有多少位。[`UInt8`](/zh/reference/data-types/int-uint)
* `default` — 可选。如果无法解析为 `Decimal64(S)` 类型，则返回此默认值。[`Decimal64(S)`](/zh/reference/data-types/decimal)
**返回值**
成功时返回 `Decimal(18, S)` 类型的值；否则，如果传入了默认值则返回默认值，未传入则返回 `0`。[`Decimal64(S)`](/zh/reference/data-types/decimal)
**示例**
**成功转换**
```sql title=Query theme={null}
SELECT toDecimal64OrDefault(toString(0.0001), 18)
```
```response title=Response theme={null}
0.0001
```
**转换失败**
```sql title=Query theme={null}
SELECT toDecimal64OrDefault('Inf', 0, CAST('-1', 'Decimal64(0)'))
```
```response title=Response theme={null}
-1
```
## toDecimal64OrNull
引入版本：v20.1.0
将输入值转换为 [Decimal(18, S)](/zh/reference/data-types/decimal) 类型的值；如果出错，则返回 `NULL`。
与 [`toDecimal64`](#toDecimal64) 类似，但在转换出错时返回 `NULL`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值 `NaN` 和 `Inf` 及其字符串表示形式 (不区分大小写) 。
* 二进制和十六进制值的字符串表示形式。
* 超出 `Decimal64` 取值范围的值：`(-1*10^(18 - S), 1*10^(18 - S))`。
另请参见：
* [`toDecimal64`](#toDecimal64)。
* [`toDecimal64OrZero`](#toDecimal64OrZero)。
* [`toDecimal64OrDefault`](#toDecimal64OrDefault)。
**语法**
```sql theme={null}
toDecimal64OrNull(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 18 之间的 scale 参数，用于指定数值的小数部分可包含的位数。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Decimal(18, S) 值，否则返回 `NULL`。[`Decimal64(S)`](/zh/reference/data-types/decimal) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDecimal64OrNull('42.7', 2), toDecimal64OrNull('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal64OrNull('42.7', 2)─┬─toDecimal64OrNull('invalid', 2)─┐
│ 42.70 │ ᴺᵁᴸᴸ │
└──────────────────────────────┴─────────────────────────────────┘
```
## toDecimal64OrZero
引入版本：v20.1.0
将输入值转换为 [Decimal(18, S)](/zh/reference/data-types/decimal) 类型的值，但如果发生错误则返回 `0`。
与 [`toDecimal64`](#toDecimal64) 类似，但在转换错误时返回 `0`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值或其字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 类型的 `NaN` 和 `Inf` 值，或其字符串表示形式 (不区分大小写) 。
* 二进制和十六进制值的字符串表示形式。
如果输入值超出 `Decimal64` 的范围：`(-1*10^(18 - S), 1*10^(18 - S))`，函数将返回 `0`。
另请参见：
* [`toDecimal64`](#toDecimal64)。
* [`toDecimal64OrNull`](#toDecimal64OrNull)。
* [`toDecimal64OrDefault`](#toDecimal64OrDefault)。
**语法**
```sql theme={null}
toDecimal64OrZero(expr, S)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
* `S` — 介于 0 到 18 之间的 scale 参数，用于指定数值的小数部分最多可以有多少位数字。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `Decimal(18, S)` 值，否则返回 `0`。[`Decimal64(S)`](/zh/reference/data-types/decimal)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDecimal64OrZero('42.7', 2), toDecimal64OrZero('invalid', 2)
```
```response title=Response theme={null}
┌─toDecimal64OrZero('42.7', 2)─┬─toDecimal64OrZero('invalid', 2)─┐
│ 42.70 │ 0.00 │
└──────────────────────────────┴─────────────────────────────────┘
```
## toDecimalString
引入版本：v23.3.0
将数值转换为具有指定小数位数的 String。
该函数会将输入值四舍五入到指定的小数位数。如果输入值的小数位数少于指定值，
则结果会用 0 补齐，以达到指定的确切小数位数。
**语法**
```sql theme={null}
toDecimalString(number, scale)
```
**参数**
* `number` — 要转换为字符串的数值。可以是任意数值类型 (Int、UInt、Float、Decimal) 。[`Int8`](/zh/reference/data-types/int-uint) 或 [`Int16`](/zh/reference/data-types/int-uint) 或 [`Int32`](/zh/reference/data-types/int-uint) 或 [`Int64`](/zh/reference/data-types/int-uint) 或 [`UInt8`](/zh/reference/data-types/int-uint) 或 [`UInt16`](/zh/reference/data-types/int-uint) 或 [`UInt32`](/zh/reference/data-types/int-uint) 或 [`UInt64`](/zh/reference/data-types/int-uint) 或 [`Float32`](/zh/reference/data-types/float) 或 [`Float64`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `scale` — 小数部分显示的位数。必要时会对结果进行四舍五入。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
返回该数值的 String 表示形式，并且小数位数严格等于指定的位数。[`String`](/zh/reference/data-types/string)
**示例**
**对数值进行四舍五入并格式化**
```sql title=Query theme={null}
SELECT toDecimalString(2.1456, 2)
```
```response title=Response theme={null}
┌─toDecimalString(2.1456, 2)─┐
│ 2.15 │
└────────────────────────────┘
```
**用零补齐**
```sql title=Query theme={null}
SELECT toDecimalString(5, 3)
```
```response title=Response theme={null}
┌─toDecimalString(5, 3)─┐
│ 5.000 │
└───────────────────────┘
```
**不同数值类型**
```sql title=Query theme={null}
SELECT toDecimalString(CAST(123.456 AS Decimal(10,3)), 2) AS decimal_val,
toDecimalString(CAST(42.7 AS Float32), 4) AS float_val
```
```response title=Response theme={null}
┌─decimal_val─┬─float_val─┐
│ 123.46 │ 42.7000 │
└─────────────┴───────────┘
```
## toFixedString
引入版本：v1.1.0
将 [`String`](/zh/reference/data-types/string) 参数转换为 [`FixedString(N)`](/zh/reference/data-types/fixedstring) 类型 (长度固定为 N 的字符串) 。
如果字符串的字节数小于 N，则会在右侧用空字节填充。
如果字符串的字节数大于 N，则会抛出异常。
**语法**
```sql theme={null}
toFixedString(s, N)
```
**参数**
* `s` — 要转换的 String。[`String`](/zh/reference/data-types/string)
* `N` — 生成的 FixedString 的长度。[`const UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回长度为 N 的 FixedString。[`FixedString(N)`](/zh/reference/data-types/fixedstring)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toFixedString('foo', 8) AS s;
```
```response title=Response theme={null}
┌─s─────────────┐
│ foo\0\0\0\0\0 │
└───────────────┘
```
## toFloat32
引入版本：v1.1.0
将输入值转换为 [Float32](/zh/reference/data-types/float) 类型的值。
如果出错，则会抛出异常。
支持的参数：
* (U)Int\* 类型的值。
* (U)Int8/16/32/128/256 的字符串表示形式。
* Float\* 类型的值，包括 `NaN` 和 `Inf`。
* Float\* 的字符串表示形式，包括 `NaN` 和 `Inf` (不区分大小写) 。
不支持的参数：
* 二进制值和十六进制值的字符串表示形式，例如 `SELECT toFloat32('0xc0fe');`。
另请参见：
* [`toFloat32OrZero`](#toFloat32OrZero)。
* [`toFloat32OrNull`](#toFloat32OrNull)。
* [`toFloat32OrDefault`](#toFloat32OrDefault)。
**语法**
```sql theme={null}
toFloat32(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 32 位浮点数。[`Float32`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toFloat32(42.7),
toFloat32('42.7'),
toFloat32('NaN')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toFloat32(42.7): 42.7
toFloat32('42.7'): 42.7
toFloat32('NaN'): nan
```
## toFloat32OrDefault
引入版本：v21.11.0
与 [`toFloat32`](#toFloat32) 类似，此函数会将输入值转换为 [Float32](/zh/reference/data-types/float) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toFloat32OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Float32`](/zh/reference/data-types/float)
**返回值**
成功时返回 `Float32` 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 0。[`Float32`](/zh/reference/data-types/float)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toFloat32OrDefault('8', CAST('0', 'Float32'))
```
```response title=Response theme={null}
8
```
**转换失败**
```sql title=Query theme={null}
SELECT toFloat32OrDefault('abc', CAST('0', 'Float32'))
```
```response title=Response theme={null}
0
```
## toFloat32OrNull
引入版本：v1.1.0
将输入值转换为 [Float32](/zh/reference/data-types/float) 类型的值；如果出错，则返回 `NULL`。
与 [`toFloat32`](#toFloat32) 类似，但在转换出错时会返回 `NULL`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值。
* (U)Int8/16/32/128/256 的字符串表示形式。
* Float\* 类型的值，包括 `NaN` 和 `Inf`。
* Float\* 的字符串表示形式，包括 `NaN` 和 `Inf` (不区分大小写) 。
不支持的参数 (返回 `NULL`) ：
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toFloat32OrNull('0xc0fe');`。
* 无效的字符串格式。
另请参见：
* [`toFloat32`](#toFloat32)。
* [`toFloat32OrZero`](#toFloat32OrZero)。
* [`toFloat32OrDefault`](#toFloat32OrDefault)。
**语法**
```sql theme={null}
toFloat32OrNull(x)
```
**参数**
* `x` — 数值的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 32 位 Float 值，否则返回 `NULL`。[`Float32`](/zh/reference/data-types/float) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toFloat32OrNull('42.7'),
toFloat32OrNull('NaN'),
toFloat32OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toFloat32OrNull('42.7'): 42.7
toFloat32OrNull('NaN'): nan
toFloat32OrNull('abc'): \N
```
## toFloat32OrZero
首次引入版本：v1.1.0
将输入值转换为 [Float32](/zh/reference/data-types/float) 类型的值；如果发生错误，则返回 `0`。
与 [`toFloat32`](#toFloat32) 类似，但在转换出错时会返回 `0`，而不是抛出异常。
另请参见：
* [`toFloat32`](#toFloat32)。
* [`toFloat32OrNull`](#toFloat32OrNull)。
* [`toFloat32OrDefault`](#toFloat32OrDefault)。
**语法**
```sql theme={null}
toFloat32OrZero(x)
```
**参数**
* `x` — 数字的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 32 位 Float 值，否则返回 `0`。[`Float32`](/zh/reference/data-types/float)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toFloat32OrZero('42.7'),
toFloat32OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toFloat32OrZero('42.7'): 42.7
toFloat32OrZero('abc'): 0
```
## toFloat64
引入版本：v1.1.0
将输入值转换为 [`Float64`](/zh/reference/data-types/float) 类型的值。
发生错误时会抛出异常。
支持的参数：
* (U)Int\* 类型的值。
* (U)Int8/16/32/128/256 的字符串表示形式。
* Float\* 类型的值，包括 `NaN` 和 `Inf`。
* Float\* 类型的字符串表示形式，包括 `NaN` 和 `Inf` (不区分大小写) 。
不支持的参数：
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toFloat64('0xc0fe');`。
另请参阅：
* [`toFloat64OrZero`](#toFloat64OrZero)。
* [`toFloat64OrNull`](#toFloat64OrNull)。
* [`toFloat64OrDefault`](#toFloat64OrDefault)。
**语法**
```sql theme={null}
toFloat64(expr)
```
**参数**
* `expr` — 返回数字或数字的字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回 64 位浮点值。[`Float64`](/zh/reference/data-types/float)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toFloat64(42.7),
toFloat64('42.7'),
toFloat64('NaN')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toFloat64(42.7): 42.7
toFloat64('42.7'): 42.7
toFloat64('NaN'): nan
```
## toFloat64OrDefault
引入版本：v21.11.0
与 [`toFloat64`](#toFloat64) 类似，此函数会将输入值转换为 [Float64](/zh/reference/data-types/float) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则发生错误时返回 `0`。
**语法**
```sql theme={null}
toFloat64OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或其字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Float64`](/zh/reference/data-types/float)
**返回值**
成功时返回 `Float64` 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 `0`。[`Float64`](/zh/reference/data-types/float)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toFloat64OrDefault('8', CAST('0', 'Float64'))
```
```response title=Response theme={null}
8
```
**转换失败**
```sql title=Query theme={null}
SELECT toFloat64OrDefault('abc', CAST('0', 'Float64'))
```
```response title=Response theme={null}
0
```
## toFloat64OrNull
引入版本：v1.1.0
将输入值转换为 [Float64](/zh/reference/data-types/float) 类型的值；如果发生错误，则返回 `NULL`。
与 [`toFloat64`](#toFloat64) 类似，但在转换出错时会返回 `NULL`，而不是抛出异常。
支持的参数：
* (U)Int\* 类型的值。
* (U)Int8/16/32/128/256 的字符串表示形式。
* Float\* 类型的值，包括 `NaN` 和 `Inf`。
* Float\* 类型的字符串表示形式，包括 `NaN` 和 `Inf` (不区分大小写) 。
不支持的参数 (返回 `NULL`) ：
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toFloat64OrNull('0xc0fe');`。
* 无效的字符串格式。
另请参阅：
* [`toFloat64`](#toFloat64)。
* [`toFloat64OrZero`](#toFloat64OrZero)。
* [`toFloat64OrDefault`](#toFloat64OrDefault)。
**语法**
```sql theme={null}
toFloat64OrNull(x)
```
**参数**
* `x` — 数值的字符串表示形式。 [`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 64 位 Float 值，否则返回 `NULL`。 [`Float64`](/zh/reference/data-types/float) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toFloat64OrNull('42.7'),
toFloat64OrNull('NaN'),
toFloat64OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toFloat64OrNull('42.7'): 42.7
toFloat64OrNull('NaN'): nan
toFloat64OrNull('abc'): \N
```
## toFloat64OrZero
引入于：v1.1.0
将输入值转换为 [Float64](/zh/reference/data-types/float) 类型的值；如果发生错误，则返回 `0`。
与 [`toFloat64`](#toFloat64) 类似，但在转换错误时会返回 `0`，而不是抛出异常。
另请参见：
* [`toFloat64`](#toFloat64)。
* [`toFloat64OrNull`](#toFloat64OrNull)。
* [`toFloat64OrDefault`](#toFloat64OrDefault)。
**语法**
```sql theme={null}
toFloat64OrZero(x)
```
**参数**
* `x` — 数值的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 64 位浮点值，否则返回 `0`。[`Float64`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toFloat64OrZero('42.7'),
toFloat64OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
第 1 行：
──────
toFloat64OrZero('42.7'): 42.7
toFloat64OrZero('abc'): 0
```
## toInt128
首次引入于：v1.1.0
将输入值转换为 [Int128](/zh/reference/data-types/int-uint) 类型的值。
出错时会抛出异常。
该函数采用向零舍入，也就是说会截断数字的小数位。
支持的参数：
* `(U)Int*` 类型的值或其字符串表示形式。
* `Float*` 类型的值。
不支持的参数：
* `Float*` 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt128('0xc0fe');`。
如果输入值无法在 Int128 的取值范围内表示，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toInt128OrZero`](#toInt128OrZero)。
* [`toInt128OrNull`](#toInt128OrNull)。
* [`toInt128OrDefault`](#toInt128OrDefault)。
**语法**
```sql theme={null}
toInt128(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 128 位整数值。[`Int128`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt128(-128),
toInt128(-128.8),
toInt128('-128')
FORMAT Vertical
```
```response title=Response theme={null}
第 1 行：
──────
toInt128(-128): -128
toInt128(-128.8): -128
toInt128('-128'): -128
```
## toInt128OrDefault
引入版本：v21.11.0
与 [`toInt128`](#toInt128) 类似，该函数会将输入值转换为 [Int128](/zh/reference/data-types/int-uint) 类型的值，但在发生错误时会返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toInt128OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Int128`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `Int128` 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 `0`。[`Int128`](/zh/reference/data-types/int-uint)
**示例**
**成功转换**
```sql title=Query theme={null}
SELECT toInt128OrDefault('-128', CAST('-1', 'Int128'))
```
```response title=Response theme={null}
-128
```
**转换失败**
```sql title=Query theme={null}
SELECT toInt128OrDefault('abc', CAST('-1', 'Int128'))
```
```response title=Response theme={null}
-1
```
## toInt128OrNull
Introduced in: v20.8.0
与 [`toInt128`](#toInt128) 类似，此函数会将输入值转换为 [Int128](/zh/reference/data-types/int-uint) 类型的值，但在出错时返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt128OrNull('0xc0fe');`。
如果输入值超出 [Int128](/zh/reference/data-types/int-uint) 的可表示范围，结果会发生上溢或下溢。
这不视为错误。
See also:
* [`toInt128`](#toInt128)。
* [`toInt128OrZero`](#toInt128OrZero)。
* [`toInt128OrDefault`](#toInt128OrDefault)。
**Syntax**
```sql theme={null}
toInt128OrNull(x)
```
**参数**
* `x` — 数字的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 Int128 类型的值；如果转换失败，则返回 `NULL`。[`Int128`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt128OrNull('-128'),
toInt128OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt128OrNull('-128'): -128
toInt128OrNull('abc'): \N
```
## toInt128OrZero
引入版本：v20.8.0
将输入值转换为 [Int128](/zh/reference/data-types/int-uint) 类型，但如果发生错误则返回 `0`。
与 [`toInt128`](#toInt128) 类似，但返回 `0` 而不是抛出异常。
另请参见：
* [`toInt128`](#toInt128)。
* [`toInt128OrNull`](#toInt128OrNull)。
* [`toInt128OrDefault`](#toInt128OrDefault)。
**语法**
```sql theme={null}
toInt128OrZero(x)
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
返回转换后的输入值；如果转换失败，则返回 `0`。[`Int128`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toInt128OrZero('123')
```
```response title=Response theme={null}
123
```
**转换失败时返回 0**
```sql title=Query theme={null}
SELECT toInt128OrZero('abc')
```
```response title=Response theme={null}
0
```
## toInt16
引入于：v1.1.0
将输入值转换为 [`Int16`](/zh/reference/data-types/int-uint) 类型的值。
发生错误时会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 类型值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt16('0xc0fe');`。
如果输入值无法表示在 [Int16](/zh/reference/data-types/int-uint) 的范围内，则结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toInt16(32768) == -32768;`。
该函数采用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，也就是说会截去数字的小数位。
另请参阅：
* [`toInt16OrZero`](#toInt16OrZero)。
* [`toInt16OrNull`](#toInt16OrNull)。
* [`toInt16OrDefault`](#toInt16OrDefault)。
**语法**
```sql theme={null}
toInt16(expr)
```
**参数**
* `expr` — 返回数值或该数值的字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 16 位整数值。[`Int16`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt16(-16),
toInt16(-16.16),
toInt16('-16')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt16(-16): -16
toInt16(-16.16): -16
toInt16('-16'): -16
```
## toInt16OrDefault
引入版本：v21.11.0
与 [`toInt16`](#toInt16) 类似，此函数将输入值转换为 [Int16](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toInt16OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Int16`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Int16 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`Int16`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toInt16OrDefault('-16', CAST('-1', 'Int16'))
```
```response title=Response theme={null}
-16
```
**转换失败**
```sql title=Query theme={null}
SELECT toInt16OrDefault('abc', CAST('-1', 'Int16'))
```
```response title=Response theme={null}
-1
```
## toInt16OrNull
引入版本：v1.1.0
与 [`toInt16`](#toInt16) 类似，此函数将输入值转换为 [Int16](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt16OrNull('0xc0fe');`。
如果输入值无法表示为 [Int16](/zh/reference/data-types/int-uint) 范围内的值，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toInt16`](#toInt16)。
* [`toInt16OrZero`](#toInt16OrZero)。
* [`toInt16OrDefault`](#toInt16OrDefault)。
**语法**
```sql theme={null}
toInt16OrNull(x)
```
**参数**
* `x` — 数值的 `String` 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `Int16` 类型的值；如果转换失败，则返回 `NULL`。[`Int16`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt16OrNull('-16'),
toInt16OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt16OrNull('-16'): -16
toInt16OrNull('abc'): \N
```
## toInt16OrZero
引入版本：v1.1.0
与 [`toInt16`](#toInt16) 类似，此函数会将输入值转换为 [Int16](/zh/reference/data-types/int-uint) 类型的值，但在发生错误时返回 `0`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt16OrZero('0xc0fe');`。
如果输入值无法在 [Int16](/zh/reference/data-types/int-uint) 的取值范围内表示，则结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toInt16`](#toInt16)。
* [`toInt16OrNull`](#toInt16OrNull)。
* [`toInt16OrDefault`](#toInt16OrDefault)。
**语法**
```sql theme={null}
toInt16OrZero(x)
```
**参数**
* `x` — 数值的 `String` 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 Int16 类型的值；如果转换失败，则返回 `0`。[`Int16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt16OrZero('16'),
toInt16OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
第 1 行:
──────
toInt16OrZero('16'): 16
toInt16OrZero('abc'): 0
```
## toInt256
引入版本：v1.1.0
将输入值转换为 [Int256](/zh/reference/data-types/int-uint) 类型的值。
如果发生错误，会抛出异常。
该函数采用向零舍入，也就是说会截去数字的小数位。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt256('0xc0fe');`。
如果输入值超出 Int256 的表示范围，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toInt256OrZero`](#toInt256OrZero)。
* [`toInt256OrNull`](#toInt256OrNull)。
* [`toInt256OrDefault`](#toInt256OrDefault)。
**语法**
```sql theme={null}
toInt256(expr)
```
**参数**
* `expr` — 返回数字或数字的字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 256 位整数值。[`Int256`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt256(-256),
toInt256(-256.256),
toInt256('-256')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt256(-256): -256
toInt256(-256.256): -256
toInt256('-256'): -256
```
## toInt256OrDefault
引入版本：v21.11.0
与 [`toInt256`](#toInt256) 类似，此函数会将输入值转换为 [Int256](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toInt256OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Int256`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Int256 类型的值；否则，如果传入了默认值，则返回该默认值；若未传入，则返回 0。[`Int256`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toInt256OrDefault('-256', CAST('-1', 'Int256'))
```
```response title=Response theme={null}
-256
```
**转换失败**
```sql title=Query theme={null}
SELECT toInt256OrDefault('abc', CAST('-1', 'Int256'))
```
```response title=Response theme={null}
-1
```
## toInt256OrNull
引入版本：v20.8.0
与 [`toInt256`](#toInt256) 类似，此函数会将输入值转换为 [Int256](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt256OrNull('0xc0fe');`。
如果输入值超出了 [Int256](/zh/reference/data-types/int-uint) 的可表示范围，则结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toInt256`](#toInt256)。
* [`toInt256OrZero`](#toInt256OrZero)。
* [`toInt256OrDefault`](#toInt256OrDefault)。
**语法**
```sql theme={null}
toInt256OrNull(x)
```
**参数**
* `x` — 数字的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 Int256 类型的值；如果转换失败，则返回 `NULL`。[`Int256`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt256OrNull('-256'),
toInt256OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt256OrNull('-256'): -256
toInt256OrNull('abc'): \N
```
## toInt256OrZero
引入版本：v20.8.0
将输入值转换为 [Int256](/zh/reference/data-types/int-uint) 类型；如果发生错误，则返回 `0`。
与 [`toInt256`](#toInt256) 类似，但会返回 `0`，而不是抛出异常。
另请参见：
* [`toInt256`](#toInt256)。
* [`toInt256OrNull`](#toInt256OrNull)。
* [`toInt256OrDefault`](#toInt256OrDefault)。
**语法**
```sql theme={null}
toInt256OrZero(x)
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
返回转换后的输入值；如果转换失败，则返回 `0`。([`Int256`](/zh/reference/data-types/int-uint))
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toInt256OrZero('123')
```
```response title=Response theme={null}
123
```
**转换失败时返回 0**
```sql title=Query theme={null}
SELECT toInt256OrZero('abc')
```
```response title=Response theme={null}
0
```
## toInt32
Introduced in: v1.1.0
将输入值转换为 [`Int32`](/zh/reference/data-types/int-uint) 类型的值。
出错时会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 类型值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt32('0xc0fe');`。
如果输入值超出 [Int32](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toInt32(2147483648) == -2147483648;`
该函数采用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即截去数字的小数位。
See also:
* [`toInt32OrZero`](#toInt32OrZero)。
* [`toInt32OrNull`](#toInt32OrNull)。
* [`toInt32OrDefault`](#toInt32OrDefault)。
**Syntax**
```sql theme={null}
toInt32(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 32 位整数。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt32(-32),
toInt32(-32.32),
toInt32('-32')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt32(-32): -32
toInt32(-32.32): -32
toInt32('-32'): -32
```
## toInt32OrDefault
引入版本：v21.11.0
与 [`toInt32`](#toInt32) 类似，此函数会将输入值转换为 [Int32](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toInt32OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Int32`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Int32 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toInt32OrDefault('-32', CAST('-1', 'Int32'))
```
```response title=Response theme={null}
-32
```
**转换失败**
```sql title=Query theme={null}
SELECT toInt32OrDefault('abc', CAST('-1', 'Int32'))
```
```response title=Response theme={null}
-1
```
## toInt32OrNull
引入版本：v1.1.0
与 [`toInt32`](#toInt32) 类似，此函数会将输入值转换为 [Int32](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt32OrNull('0xc0fe');`。
如果输入值无法在 [Int32](/zh/reference/data-types/int-uint) 的取值范围内表示，结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toInt32`](#toInt32)。
* [`toInt32OrZero`](#toInt32OrZero)。
* [`toInt32OrDefault`](#toInt32OrDefault)。
**语法**
```sql theme={null}
toInt32OrNull(x)
```
**参数**
* `x` — 数字的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `Int32` 类型的值；如果转换失败，则返回 `NULL`。[`Int32`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toInt32OrNull('-32'),
toInt32OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt32OrNull('-32'): -32
toInt32OrNull('abc'): \N
```
## toInt32OrZero
引入版本：v1.1.0
与 [`toInt32`](#toInt32) 类似，此函数会将输入值转换为 [Int32](/zh/reference/data-types/int-uint) 类型的值；如果发生错误，则返回 `0`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt32OrZero('0xc0fe');`。
如果输入值超出 [Int32](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toInt32`](#toInt32)。
* [`toInt32OrNull`](#toInt32OrNull)。
* [`toInt32OrDefault`](#toInt32OrDefault)。
**语法**
```sql theme={null}
toInt32OrZero(x)
```
**参数**
* `x` — 数字的 `String` 表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回类型为 Int32 的值；如果转换失败，则返回 `0`。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt32OrZero('32'),
toInt32OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt32OrZero('32'): 32
toInt32OrZero('abc'): 0
```
## toInt64
引入版本：v1.1.0
将输入值转换为 [`Int64`](/zh/reference/data-types/int-uint) 类型的值。
如果发生错误，则会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt64('0xc0fe');`。
如果输入值超出 [Int64](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toInt64(9223372036854775808) == -9223372036854775808;`
该函数使用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即会截断数字的小数位。
另请参见：
* [`toInt64OrZero`](#toInt64OrZero)。
* [`toInt64OrNull`](#toInt64OrNull)。
* [`toInt64OrDefault`](#toInt64OrDefault)。
**语法**
```sql theme={null}
toInt64(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。支持：类型为 (U)Int\* 的值或其字符串表示形式，以及类型为 Float\* 的值。不支持：Float\* 值的字符串表示形式 (包括 NaN 和 Inf) ，以及二进制和十六进制值的字符串表示形式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 64 位整数值。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt64(-64),
toInt64(-64.64),
toInt64('-64')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt64(-64): -64
toInt64(-64.64): -64
toInt64('-64'): -64
```
## toInt64OrDefault
引入版本：v21.11.0
与 [`toInt64`](#toInt64) 类似，此函数会将输入值转换为 [Int64](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则发生错误时返回 `0`。
**语法**
```sql theme={null}
toInt64OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数字或数字的字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Int64`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 Int64 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**成功转换**
```sql title=Query theme={null}
SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))
```
```response title=Response theme={null}
-64
```
**转换失败**
```sql title=Query theme={null}
SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))
```
```response title=Response theme={null}
-1
```
## toInt64OrNull
引入版本：v1.1.0
与 [`toInt64`](#toInt64) 类似，此函数将输入值转换为 [Int64](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt64OrNull('0xc0fe');`。
如果输入值超出 [Int64](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toInt64`](#toInt64)。
* [`toInt64OrZero`](#toInt64OrZero)。
* [`toInt64OrDefault`](#toInt64OrDefault)。
**语法**
```sql theme={null}
toInt64OrNull(x)
```
**参数**
* `x` — 数值的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `Int64` 类型的值；如果转换失败，则返回 `NULL`。[`Int64`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt64OrNull('-64'),
toInt64OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): \N
```
## toInt64OrZero
引入版本：v1.1.0
将输入值转换为 [Int64](/zh/reference/data-types/int-uint) 类型，但如果发生错误则返回 `0`。
与 [`toInt64`](#toInt64) 类似，不过它会返回 `0`，而不是抛出异常。
另请参见：
* [`toInt64`](#toInt64)。
* [`toInt64OrNull`](#toInt64OrNull)。
* [`toInt64OrDefault`](#toInt64OrDefault)。
**语法**
```sql theme={null}
toInt64OrZero(x)
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
返回转换后的输入值；如果转换失败，则返回 `0`。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toInt64OrZero('123')
```
```response title=Response theme={null}
123
```
**转换失败则返回零**
```sql title=Query theme={null}
SELECT toInt64OrZero('abc')
```
```response title=Response theme={null}
0
```
## toInt8
引入版本：v1.1.0
将输入值转换为 [`Int8`](/zh/reference/data-types/int-uint) 类型的值。
出错时会抛出异常。
支持的参数：
* `(U)Int*` 类型的值或其字符串表示形式。
* `Float*` 类型的值。
不支持的参数：
* `Float*` 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt8('0xc0fe');`。
如果输入值超出 [Int8](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toInt8(128) == -128;`。
此函数使用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即会截去数字的小数位。
另请参见：
* [`toInt8OrZero`](#toInt8OrZero)。
* [`toInt8OrNull`](#toInt8OrNull)。
* [`toInt8OrDefault`](#toInt8OrDefault)。
**语法**
```sql theme={null}
toInt8(expr)
```
**参数**
* `expr` — 返回数值或数值的字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 8 位整数值。[`Int8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt8(-8),
toInt8(-8.8),
toInt8('-8')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt8(-8): -8
toInt8(-8.8): -8
toInt8('-8'): -8
```
## toInt8OrDefault
首次引入版本：v21.11.0
与 [`toInt8`](#toInt8) 类似，此函数会将输入值转换为 [Int8](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toInt8OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`Int8`](/zh/reference/data-types/int-uint)
**返回值**
如果成功，则返回 `Int8` 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 `0`。[`Int8`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))
```
```response title=Response theme={null}
-8
```
**转换失败**
```sql title=Query theme={null}
SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))
```
```response title=Response theme={null}
-1
```
## toInt8OrNull
引入版本：v1.1.0
与 [`toInt8`](#toInt8) 类似，此函数会将输入值转换为 [Int8](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制值和十六进制值的字符串表示形式，例如 `SELECT toInt8OrNull('0xc0fe');`。
如果输入值无法在 [Int8](/zh/reference/data-types/int-uint) 的范围内表示，结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toInt8`](#toInt8)。
* [`toInt8OrZero`](#toInt8OrZero)。
* [`toInt8OrDefault`](#toInt8OrDefault)。
**语法**
```sql theme={null}
toInt8OrNull(x)
```
**参数**
* `x` — 数值的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `Int8` 类型的值；如果转换失败，则返回 `NULL`。[`Int8`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt8OrNull('-8'),
toInt8OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt8OrNull('-8'): -8
toInt8OrNull('abc'): \N
```
## toInt8OrZero
版本引入：v1.1.0
与 [`toInt8`](#toInt8) 类似，此函数会将输入值转换为 [Int8](/zh/reference/data-types/int-uint) 类型的值，但如果出错则返回 `0`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toInt8OrZero('0xc0fe');`。
如果输入值超出 [Int8](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toInt8`](#toInt8)。
* [`toInt8OrNull`](#toInt8OrNull)。
* [`toInt8OrDefault`](#toInt8OrDefault)。
**语法**
```sql theme={null}
toInt8OrZero(x)
```
**参数**
* `x` — 数值的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 Int8 类型的值；如果转换失败，则返回 `0`。[`Int8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toInt8OrZero('8'),
toInt8OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toInt8OrZero('8'): 8
toInt8OrZero('abc'): 0
```
## toInterval
引入版本：v25.4.0
根据数值和单位字符串创建一个 Interval 值。
该函数提供了一种统一的方法：通过将单位指定为字符串参数，用同一个函数创建不同类型的时间间隔 (秒、分钟、小时、天、周、月、季度、年) 。
单位字符串不区分大小写。
这等同于调用 `toIntervalSecond`、`toIntervalMinute`、`toIntervalDay` 等特定类型的函数，
但允许通过字符串参数动态指定单位。
**语法**
```sql theme={null}
toInterval(value, unit)
```
**参数**
* `value` — 表示单位数量的数值，可为任意数值类型。[`Int8`](/zh/reference/data-types/int-uint) 或 [`Int16`](/zh/reference/data-types/int-uint) 或 [`Int32`](/zh/reference/data-types/int-uint) 或 [`Int64`](/zh/reference/data-types/int-uint) 或 [`UInt8`](/zh/reference/data-types/int-uint) 或 [`UInt16`](/zh/reference/data-types/int-uint) 或 [`UInt32`](/zh/reference/data-types/int-uint) 或 [`UInt64`](/zh/reference/data-types/int-uint) 或 [`Float32`](/zh/reference/data-types/float) 或 [`Float64`](/zh/reference/data-types/float)
* `unit` — 时间单位。必须为常量字符串。有效值：'nanosecond'、'microsecond'、'millisecond'、'second'、'minute'、'hour'、'day'、'week'、'month'、'quarter'、'year'。[`String`](/zh/reference/data-types/string)
**返回值**
返回指定类型的 Interval 值。结果类型取决于 `unit`：IntervalNanosecond、IntervalMicrosecond、IntervalMillisecond、IntervalSecond、IntervalMinute、IntervalHour、IntervalDay、IntervalWeek、IntervalMonth、IntervalQuarter 或 IntervalYear。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**创建不同单位的时间间隔**
```sql title=Query theme={null}
SELECT
toInterval(5, 'second') AS seconds,
toInterval(3, 'day') AS days,
toInterval(2, 'month') AS months
```
```response title=Response theme={null}
┌─seconds─┬─days─┬─months─┐
│ 5 │ 3 │ 2 │
└─────────┴──────┴────────┘
```
**在日期算术中使用时间间隔**
```sql title=Query theme={null}
SELECT
now() AS current_time,
now() + toInterval(1, 'hour') AS one_hour_later,
now() - toInterval(7, 'day') AS week_ago
```
```response title=Response theme={null}
┌─────────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 │
└──────────────────────┴─────────────────────┴─────────────────────┘
```
**动态生成时间间隔**
```sql title=Query theme={null}
SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)
```
```response title=Response theme={null}
┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘
```
## toIntervalDay
在 v1.1.0 中引入
返回一个由 `n` 天组成、数据类型为 [`IntervalDay`](/zh/reference/data-types/special-data-types/interval) 的时间间隔。
**语法**
```sql theme={null}
toIntervalDay(n)
```
**参数**
* `n` — 天数。整数、整数的字符串表示形式或浮点数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 天的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result
```
```response title=Response theme={null}
┌─────result─┐
│ 2025-06-20 │
└────────────┘
```
## toIntervalHour
在 v1.1.0 中引入
返回一个表示 `n` 小时的时间间隔，数据类型为 [`IntervalHour`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalHour(n)
```
**参数**
* `n` — 小时数。可以是整数、其字符串表示形式或浮点数。[`Int*`](/zh/reference/data-types/int-uint) 或 [`UInt*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回一个 `n` 小时的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result
```
```response title=Response theme={null}
┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘
```
## toIntervalMicrosecond
引入版本：v22.6.0
返回一个由 `n` 微秒组成的时间间隔，数据类型为 [`IntervalMicrosecond`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalMicrosecond(n)
```
**参数**
* `n` — 微秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回由 `n` 微秒构成的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDateTime('2025-06-15') AS date,
toIntervalMicrosecond(30) AS interval_to_microseconds
SELECT date + interval_to_microseconds AS result
```
```response title=Response theme={null}
┌─────────────────────result─┐
│ 2025-06-15 00:00:00.000030 │
└────────────────────────────┘
```
## toIntervalMillisecond
引入版本：v22.6.0
返回一个 `n` 毫秒的时间间隔，数据类型为 [IntervalMillisecond](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalMillisecond(n)
```
**参数**
* `n` — 毫秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回一个包含 `n` 毫秒的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDateTime('2025-06-15') AS date,
toIntervalMillisecond(30) AS interval_to_milliseconds
SELECT date + interval_to_milliseconds AS result
```
```response title=Response theme={null}
┌──────────────────result─┐
│ 2025-06-15 00:00:00.030 │
└─────────────────────────┘
```
## toIntervalMinute
引入版本：v1.1.0
返回一个表示 `n` 分钟的时间间隔，数据类型为 [`IntervalMinute`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalMinute(n)
```
**参数**
* `n` — 分钟数。整数、其字符串表示形式以及浮点数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 分钟的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalMinute(12) AS interval_to_minutes
SELECT date + interval_to_minutes AS result
```
```response title=Response theme={null}
┌──────────────result─┐
│ 2025-06-15 00:12:00 │
└─────────────────────┘
```
## toIntervalMonth
引入版本：v1.1.0
返回一个 `n` 个月的时间间隔，数据类型为 [`IntervalMonth`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalMonth(n)
```
**参数**
* `n` — 月份数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 个月的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalMonth(1) AS interval_to_month
SELECT date + interval_to_month AS result
```
```response title=Response theme={null}
┌─────result─┐
│ 2025-07-15 │
└────────────┘
```
## toIntervalNanosecond
引入版本：v22.6.0
返回一个 `n` 纳秒的时间间隔，数据类型为 [`IntervalNanosecond`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalNanosecond(n)
```
**参数**
* `n` — 纳秒数量。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 纳秒的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDateTime('2025-06-15') AS date,
toIntervalNanosecond(30) AS interval_to_nanoseconds
SELECT date + interval_to_nanoseconds AS result
```
```response title=Response theme={null}
┌────────────────────────result─┐
│ 2025-06-15 00:00:00.000000030 │
└───────────────────────────────┘
```
## toIntervalQuarter
在 v1.1.0 中引入
返回一个由 `n` 个季度组成、数据类型为 [`IntervalQuarter`](/zh/reference/data-types/special-data-types/interval) 的时间间隔。
**语法**
```sql theme={null}
toIntervalQuarter(n)
```
**参数**
* `n` — 季度数量。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 个季度的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalQuarter(1) AS interval_to_quarter
SELECT date + interval_to_quarter AS result
```
```response title=Response theme={null}
┌─────result─┐
│ 2025-09-15 │
└────────────┘
```
## toIntervalSecond
引入版本：v1.1.0
返回一个由 `n` 秒构成、数据类型为 [`IntervalSecond`](/zh/reference/data-types/special-data-types/interval) 的时间间隔。
**语法**
```sql theme={null}
toIntervalSecond(n)
```
**参数**
* `n` — 秒数。整数、其字符串表示形式以及浮点数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 秒的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalSecond(30) AS interval_to_seconds
SELECT date + interval_to_seconds AS result
```
```response title=Response theme={null}
┌──────────────result─┐
│ 2025-06-15 00:00:30 │
└─────────────────────┘
```
## toIntervalWeek
引入版本：v1.1.0
返回一个表示 `n` 周的时间间隔，数据类型为 [`IntervalWeek`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalWeek(n)
```
**参数**
* `n` — 周数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回 `n` 周的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
WITH
toDate('2025-06-15') AS date,
toIntervalWeek(1) AS interval_to_week
SELECT date + interval_to_week AS result
```
```response title=Response theme={null}
┌─────result─┐
│ 2025-06-22 │
└────────────┘
```
## toIntervalYear
引入版本：v1.1.0
返回一个表示 `n` 年的时间间隔，数据类型为 [`IntervalYear`](/zh/reference/data-types/special-data-types/interval)。
**语法**
```sql theme={null}
toIntervalYear(n)
```
**参数**
* `n` — 年数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string)
**返回值**
返回一个 `n` 年的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH
toDate('2024-06-15') AS date,
toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result
```
```response title=Response theme={null}
┌─────result─┐
│ 2025-06-15 │
└────────────┘
```
## toLowCardinality
引入版本：v18.12.0
将输入参数转换为相同数据类型的 [LowCardinality](/zh/reference/data-types/lowcardinality) 版本。
若要将 `LowCardinality` 数据类型转换为常规数据类型，请使用 [CAST](#CAST) 函数。
例如：`CAST(x AS String)`。
**语法**
```sql theme={null}
toLowCardinality(expr)
```
**参数**
* `expr` — 结果为以下任一受支持数据类型的表达式。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回转换为 `LowCardinality` 数据类型后的输入值。[`LowCardinality`](/zh/reference/data-types/lowcardinality)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toLowCardinality('1')
```
```response title=Response theme={null}
┌─toLowCardinality('1')─┐
│ 1 │
└───────────────────────┘
```
## toString
引入版本：v1.1.0
将值转换为其字符串表示形式。
对于 DateTime 类型的参数，该函数还可以接受第二个 String 类型参数，用于指定时区名称。
**语法**
```sql theme={null}
toString(value[, timezone])
```
**参数**
* `value` — 要转换为字符串的值。[`Any`](/zh/reference/data-types)
* `timezone` — 可选。用于 DateTime 转换的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入值的字符串表示形式。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
now() AS ts,
time_zone,
toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10
```
```response title=Response theme={null}
┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast │ 2023-09-08 20:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘
```
## toStringCutToZero
引入版本：v1.1.0
接受一个 [String](/zh/reference/data-types/string) 或 [FixedString](/zh/reference/data-types/fixedstring) 类型的参数，并返回一个 String，该 String 是在第一个空字节处截断后的原始字符串副本。
空字节 (\0) 被视为字符串终止符。
当空字节用于标记有效内容的结尾时，此函数可用于处理 C 风格字符串或二进制数据。
**语法**
```sql theme={null}
toStringCutToZero(s)
```
**参数**
* `s` — 要处理的 String 或 FixedString。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回一个 String，包含第一个空字节之前的字符。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toStringCutToZero('hello'),
toStringCutToZero('hello\0world')
```
```response title=Response theme={null}
┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello │ hello │
└────────────────────────────┴───────────────────────────────────┘
```
## toTime
引入版本：v1.1.0
将输入值转换为 [Time](/zh/reference/data-types/time) 类型。
支持从 String、FixedString、DateTime 或表示自午夜起经过秒数的数值类型进行转换。
**语法**
```sql theme={null}
toTime(x)
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回转换后的值。[`Time`](/zh/reference/data-types/time)
**示例**
**String 转换为 Time**
```sql title=Query theme={null}
SELECT toTime('14:30:25')
```
```response title=Response theme={null}
14:30:25
```
**DateTime 转换为 Time**
```sql title=Query theme={null}
SELECT toTime(toDateTime('2025-04-15 14:30:25'))
```
```response title=Response theme={null}
14:30:25
```
**将整数转换为时间**
```sql title=Query theme={null}
SELECT toTime(52225)
```
```response title=Response theme={null}
14:30:25
```
## toTime64
引入版本：v25.6.0
将输入值转换为 [Time64](/zh/reference/data-types/time64) 类型。
支持从 String、FixedString、DateTime64，或表示自午夜起微秒数的数值类型进行转换。
为时间值提供微秒级精度。
**语法**
```sql theme={null}
toTime64(x)
```
**参数**
* `x` — 要转换的输入值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回转换后的输入值，精度为微秒。[`Time64(6)`](/zh/reference/data-types/time64)
**示例**
**String 转换为 Time64**
```sql title=Query theme={null}
SELECT toTime64('14:30:25.123456')
```
```response title=Response theme={null}
14:30:25.123456
```
**DateTime64 转换为 Time64**
```sql title=Query theme={null}
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))
```
```response title=Response theme={null}
14:30:25.123456
```
**整数转换为 Time64**
```sql title=Query theme={null}
SELECT toTime64(52225123456)
```
```response title=Response theme={null}
14:30:25.123456
```
## toTime64OrNull
引入版本：v25.6.0
将输入值转换为 `Time64` 类型的值；如果发生错误，则返回 `NULL`。
与 [`toTime64`](#toTime64) 类似，但在转换出错时会返回 `NULL`，而不是抛出异常。
另请参见：
* [`toTime64`](#toTime64)
* [`toTime64OrZero`](#toTime64OrZero)
**语法**
```sql theme={null}
toTime64OrNull(x)
```
**参数**
* `x` — 具有子秒级精度的时间字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 `Time64` 值，否则返回 `NULL`。[`Time64`](/zh/reference/data-types/time64) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toTime64OrNull('12:30:45.123'), toTime64OrNull('invalid')
```
```response title=Response theme={null}
┌─toTime64OrNull('12:30:45.123')─┬─toTime64OrNull('invalid')─┐
│ 12:30:45.123 │ ᴺᵁᴸᴸ │
└────────────────────────────────┴───────────────────────────┘
```
## toTime64OrZero
引入版本：v25.6.0
将输入值转换为 Time64 类型的值；如果发生错误，则返回 `00:00:00.000`。
与 [`toTime64`](#toTime64) 类似，但在转换出错时会返回 `00:00:00.000`，而不是抛出异常。
**语法**
```sql theme={null}
toTime64OrZero(x)
```
**参数**
* `x` — 具有子秒级精度的时间字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
如果成功，返回 Time64 值；否则返回 `00:00:00.000`。[`Time64`](/zh/reference/data-types/time64)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')
```
```response title=Response theme={null}
┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│ 12:30:45.123 │ 00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘
```
## toTimeOrNull
引入版本：v1.1.0
将输入值转换为 Time 类型的值；如果发生错误，则返回 `NULL`。
与 [`toTime`](#toTime) 类似，但在转换出错时会返回 `NULL`，而不是抛出异常。
另请参见：
* [`toTime`](#toTime)
* [`toTimeOrZero`](#toTimeOrZero)
**语法**
```sql theme={null}
toTimeOrNull(x)
```
**参数**
* `x` — 时间的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 `Time` 值，否则返回 `NULL`。[`Time`](/zh/reference/data-types/time) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')
```
```response title=Response theme={null}
┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│ 12:30:45 │ ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘
```
## toTimeOrZero
Introduced in: v1.1.0
将输入值转换为 `Time` 类型的值；如果出错，则返回 `00:00:00`。
与 toTime 类似，但在转换出错时会返回 `00:00:00`，而不是抛出异常。
**Syntax**
```sql theme={null}
toTimeOrZero(x)
```
**参数**
* `x` — 时间的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
如果成功，返回 Time 值；否则返回 `00:00:00`。[`Time`](/zh/reference/data-types/time)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')
```
```response title=Response theme={null}
┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│ 12:30:45 │ 00:00:00 │
└──────────────────────────┴─────────────────────────┘
```
## toUInt128
引入版本：v1.1.0
将输入值转换为 [`UInt128`](/zh/reference/functions/regular-functions/type-conversion-functions#toUInt128) 类型的值。
出错时会抛出异常。
该函数采用向零舍入，即会截断数字的小数位。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt128('0xc0fe');`。
如果输入值超出 UInt128 的表示范围，结果会发生上溢或下溢。
这不被视为错误。
另请参见：
* [`toUInt128OrZero`](#toUInt128OrZero)。
* [`toUInt128OrNull`](#toUInt128OrNull)。
* [`toUInt128OrDefault`](#toUInt128OrDefault)。
**语法**
```sql theme={null}
toUInt128(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 128 位无符号整数值。[`UInt128`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toUInt128(128),
toUInt128(128.8),
toUInt128('128')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt128(128): 128
toUInt128(128.8): 128
toUInt128('128'): 128
```
## toUInt128OrDefault
引入版本：v21.11.0
与 [`toUInt128`](#toUInt128) 类似，此函数会将输入值转换为 [`UInt128`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toUInt128OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`UInt128`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 UInt128 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`UInt128`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))
```
```response title=Response theme={null}
128
```
**转换失败**
```sql title=Query theme={null}
SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))
```
```response title=Response theme={null}
0
```
## toUInt128OrNull
引入版本：v21.6.0
与 [`toUInt128`](#toUInt128) 类似，此函数将输入值转换为 [`UInt128`](/zh/reference/data-types/int-uint) 类型的值，但在发生错误时会返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt128OrNull('0xc0fe');`。
如果输入值无法在 [`UInt128`](/zh/reference/data-types/int-uint) 的取值范围内表示，则结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toUInt128`](#toUInt128)。
* [`toUInt128OrZero`](#toUInt128OrZero)。
* [`toUInt128OrDefault`](#toUInt128OrDefault)。
**语法**
```sql theme={null}
toUInt128OrNull(x)
```
**参数**
* `x` — 数字的 String 表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UInt128 类型的值；如果转换失败，则返回 `NULL`。[`UInt128`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt128OrNull('128'),
toUInt128OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N
```
## toUInt128OrZero
引入版本：v1.1.0
与 [`toUInt128`](#toUInt128) 类似，此函数会将输入值转换为 [`UInt128`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误则返回 `0`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt128OrZero('0xc0fe');`。
如果输入值超出 [`UInt128`](/zh/reference/data-types/int-uint) 的表示范围，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt128`](#toUInt128)。
* [`toUInt128OrNull`](#toUInt128OrNull)。
* [`toUInt128OrDefault`](#toUInt128OrDefault)。
**语法**
```sql theme={null}
toUInt128OrZero(x)
```
**参数**
* `x` — 数字的 String 表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UInt128 类型的值；如果转换失败，则返回 `0`。[`UInt128`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt128OrZero('128'),
toUInt128OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0
```
## toUInt16
引入版本：v1.1.0
将输入值转换为 [`UInt16`](/zh/reference/data-types/int-uint) 类型的值。
发生错误时会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt16('0xc0fe');`。
如果输入值无法在 [`UInt16`](/zh/reference/data-types/int-uint) 的取值范围内表示，则结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toUInt16(65536) == 0;`。
该函数使用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即会截断数字的小数位。
另请参见：
* [`toUInt16OrZero`](#toUInt16OrZero)。
* [`toUInt16OrNull`](#toUInt16OrNull)。
* [`toUInt16OrDefault`](#toUInt16OrDefault)。
**语法**
```sql theme={null}
toUInt16(expr)
```
**参数**
* `expr` — 返回数值或数值的字符串表示形式的表达式。[`表达式`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 16 位无符号整数值。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt16(16),
toUInt16(16.16),
toUInt16('16')
FORMAT Vertical
```
```response title=Response theme={null}
第 1 行:
──────
toUInt16(16): 16
toUInt16(16.16): 16
toUInt16('16'): 16
```
## toUInt16OrDefault
Introduced in：v21.11.0
与 [`toUInt16`](#toUInt16) 类似，此函数会将输入值转换为 [UInt16](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**Syntax**
```sql theme={null}
toUInt16OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数字字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`UInt16`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `UInt16` 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 `0`。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toUInt16OrDefault('16', CAST('0', 'UInt16'))
```
```response title=Response theme={null}
16
```
**转换失败**
```sql title=Query theme={null}
SELECT toUInt16OrDefault('abc', CAST('0', 'UInt16'))
```
```response title=Response theme={null}
0
```
## toUInt16OrNull
Introduced in: v1.1.0
与 [`toUInt16`](#toUInt16) 类似，此函数会将输入值转换为 [`UInt16`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误则返回 `NULL`。
支持的参数：
* (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt16OrNull('0xc0fe');`。
如果输入值超出 [`UInt16`](/zh/reference/data-types/int-uint) 的表示范围，则结果会发生上溢或下溢。
这不视为错误。
See also:
* [`toUInt16`](#toUInt16)。
* [`toUInt16OrZero`](#toUInt16OrZero)。
* [`toUInt16OrDefault`](#toUInt16OrDefault)。
**Syntax**
```sql theme={null}
toUInt16OrNull(x)
```
**参数**
* `x` — 数字的 String 表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `UInt16` 类型的值；如果转换失败，则返回 `NULL`。[`UInt16`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt16OrNull('16'),
toUInt16OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt16OrNull('16'): 16
toUInt16OrNull('abc'): \N
```
## toUInt16OrZero
引入于：v1.1.0
与 [`toUInt16`](#toUInt16) 类似，此函数将输入值转换为 [`UInt16`](/zh/reference/data-types/int-uint) 类型的值，但在发生错误时会返回 `0`。
支持的参数：
* (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt16OrZero('0xc0fe');`。
如果输入值超出了 [`UInt16`](/zh/reference/data-types/int-uint) 的可表示范围，则结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toUInt16`](#toUInt16)。
* [`toUInt16OrNull`](#toUInt16OrNull)。
* [`toUInt16OrDefault`](#toUInt16OrDefault)。
**语法**
```sql theme={null}
toUInt16OrZero(x)
```
**参数**
* `x` — 数值的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UInt16 类型的值；如果转换失败，则返回 `0`。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt16OrZero('16'),
toUInt16OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt16OrZero('16'): 16
toUInt16OrZero('abc'): 0
```
## toUInt256
在 v1.1.0 中引入
将输入值转换为 UInt256 类型的值。
出错时会抛出异常。
该函数采用向零舍入，也就是说会截断数字的小数位。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt256('0xc0fe');`。
如果输入值无法在 UInt256 的取值范围内表示，结果会发生上溢或下溢。
这不被视为错误。
另请参见：
* [`toUInt256OrZero`](#toUInt256OrZero)。
* [`toUInt256OrNull`](#toUInt256OrNull)。
* [`toUInt256OrDefault`](#toUInt256OrDefault)。
**语法**
```sql theme={null}
toUInt256(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 256 位无符号整数。[`UInt256`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt256(256),
toUInt256(256.256),
toUInt256('256')
FORMAT Vertical
```
```response title=Response theme={null}
行 1:
──────
toUInt256(256): 256
toUInt256(256.256): 256
toUInt256('256'): 256
```
## toUInt256OrDefault
引入版本：v21.11.0
与 [`toUInt256`](#toUInt256) 类似，此函数会将输入值转换为 [UInt256](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则在发生错误时返回 `0`。
**语法**
```sql theme={null}
toUInt256OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值的字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`UInt256`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 UInt256 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`UInt256`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toUInt256OrDefault('-256', CAST('0', 'UInt256'))
```
```response title=Response theme={null}
0
```
**转换失败**
```sql title=Query theme={null}
SELECT toUInt256OrDefault('abc', CAST('0', 'UInt256'))
```
```response title=Response theme={null}
0
```
## toUInt256OrNull
引入版本：v20.8.0
与 [`toUInt256`](#toUInt256) 类似，此函数会将输入值转换为 [`UInt256`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制值和十六进制值的字符串表示形式，例如 `SELECT toUInt256OrNull('0xc0fe');`。
如果输入值超出 [`UInt256`](/zh/reference/data-types/int-uint) 的表示范围，则结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toUInt256`](#toUInt256)。
* [`toUInt256OrZero`](#toUInt256OrZero)。
* [`toUInt256OrDefault`](#toUInt256OrDefault)。
**语法**
```sql theme={null}
toUInt256OrNull(x)
```
**参数**
* `x` — 数字的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `UInt256` 类型的值；如果转换失败，则返回 `NULL`。[`UInt256`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt256OrNull('256'),
toUInt256OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt256OrNull('256'): 256
toUInt256OrNull('abc'): \N
```
## toUInt256OrZero
引入于：v20.8.0
与 [`toUInt256`](#toUInt256) 类似，此函数会将输入值转换为 [`UInt256`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `0`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt256OrZero('0xc0fe');`。
如果输入值超出 [`UInt256`](/zh/reference/data-types/int-uint) 的可表示范围，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt256`](#toUInt256)。
* [`toUInt256OrNull`](#toUInt256OrNull)。
* [`toUInt256OrDefault`](#toUInt256OrDefault)。
**语法**
```sql theme={null}
toUInt256OrZero(x)
```
**参数**
* `x` — 数值的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UInt256 类型的值；如果转换失败，则返回 `0`。[`UInt256`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt256OrZero('256'),
toUInt256OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt256OrZero('256'): 256
toUInt256OrZero('abc'): 0
```
## toUInt32
引入于：v1.1.0
将输入值转换为 [`UInt32`](/zh/reference/data-types/int-uint) 类型的值。
如果出错，则会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制值和十六进制值的字符串表示形式，例如 `SELECT toUInt32('0xc0fe');`。
如果输入值无法用 [`UInt32`](/zh/reference/data-types/int-uint) 的取值范围表示，结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toUInt32(4294967296) == 0;`
该函数使用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即会截去数字的小数位。
另请参见：
* [`toUInt32OrZero`](#toUInt32OrZero)。
* [`toUInt32OrNull`](#toUInt32OrNull)。
* [`toUInt32OrDefault`](#toUInt32OrDefault)。
**语法**
```sql theme={null}
toUInt32(expr)
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 32 位无符号整数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toUInt32(32),
toUInt32(32.32),
toUInt32('32')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt32(32): 32
toUInt32(32.32): 32
toUInt32('32'): 32
```
## toUInt32OrDefault
Introduced in: v21.11.0
与 [`toUInt32`](#toUInt32) 类似，此函数会将输入值转换为 [UInt32](/zh/reference/data-types/int-uint) 类型的值，但发生错误时会返回默认值。
如果未传入 `default` 值，则发生错误时返回 `0`。
**Syntax**
```sql theme={null}
toUInt32OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`UInt32`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `UInt32` 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 `0`。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toUInt32OrDefault('32', CAST('0', 'UInt32'))
```
```response title=Response theme={null}
32
```
**转换失败**
```sql title=Query theme={null}
SELECT toUInt32OrDefault('abc', CAST('0', 'UInt32'))
```
```response title=Response theme={null}
0
```
## toUInt32OrNull
引入于：v1.1.0
与 [`toUInt32`](#toUInt32) 类似，此函数会将输入值转换为 [`UInt32`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `NULL`。
支持的参数：
* (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt32OrNull('0xc0fe');`。
如果输入值无法在 [`UInt32`](/zh/reference/data-types/int-uint) 的范围内表示，则结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt32`](#toUInt32)。
* [`toUInt32OrZero`](#toUInt32OrZero)。
* [`toUInt32OrDefault`](#toUInt32OrDefault)。
**语法**
```sql theme={null}
toUInt32OrNull(x)
```
**参数**
* `x` — 数值的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `UInt32` 类型的值；如果转换失败，则返回 `NULL`。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt32OrNull('32'),
toUInt32OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt32OrNull('32'): 32
toUInt32OrNull('abc'): \N
```
## toUInt32OrZero
引入版本：v1.1.0
与 [`toUInt32`](#toUInt32) 类似，此函数会将输入值转换为 [`UInt32`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `0`。
支持的参数：
* (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt32OrZero('0xc0fe');`。
如果输入值无法在 [`UInt32`](/zh/reference/data-types/int-uint) 的取值范围内表示，则结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt32`](#toUInt32)。
* [`toUInt32OrNull`](#toUInt32OrNull)。
* [`toUInt32OrDefault`](#toUInt32OrDefault)。
**语法**
```sql theme={null}
toUInt32OrZero(x)
```
**参数**
* `x` — 数值的 String 表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UInt32 类型的值；如果转换失败，则返回 `0`。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt32OrZero('32'),
toUInt32OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt32OrZero('32'): 32
toUInt32OrZero('abc'): 0
```
## toUInt64
引入版本：v1.1.0
将输入值转换为 [`UInt64`](/zh/reference/data-types/int-uint) 类型的值。
发生错误时会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的类型：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt64('0xc0fe');`。
如果输入值超出 [`UInt64`](/zh/reference/data-types/int-uint) 的取值范围，结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toUInt64(18446744073709551616) == 0;`
该函数使用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即会截断数字的小数位。
另请参见：
* [`toUInt64OrZero`](#toUInt64OrZero)。
* [`toUInt64OrNull`](#toUInt64OrNull)。
* [`toUInt64OrDefault`](#toUInt64OrDefault)。
**语法**
```sql theme={null}
toUInt64(expr)
```
**参数**
* `expr` — 返回数字或数字的字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回一个 64 位无符号整数值。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt64(64),
toUInt64(64.64),
toUInt64('64')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt64(64): 64
toUInt64(64.64): 64
toUInt64('64'): 64
```
## toUInt64OrDefault
首次引入版本：v21.11.0
与 [`toUInt64`](#toUInt64) 类似，此函数会将输入值转换为 [UInt64](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则发生错误时返回 `0`。
**语法**
```sql theme={null}
toUInt64OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数字或数字字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`UInt64`](/zh/reference/data-types/int-uint)
**返回值**
如果转换成功，返回 UInt64 类型的值；否则，如果传入了默认值则返回该默认值，未传入则返回 0。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toUInt64OrDefault('64', CAST('0', 'UInt64'))
```
```response title=Response theme={null}
64
```
**转换失败**
```sql title=Query theme={null}
SELECT toUInt64OrDefault('abc', CAST('0', 'UInt64'))
```
```response title=Response theme={null}
0
```
## toUInt64OrNull
引入于：v1.1.0
与 [`toUInt64`](#toUInt64) 类似，此函数会将输入值转换为 [`UInt64`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误则返回 `NULL`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt64OrNull('0xc0fe');`。
如果输入值无法在 [`UInt64`](/zh/reference/data-types/int-uint) 的范围内表示，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt64`](#toUInt64)。
* [`toUInt64OrZero`](#toUInt64OrZero)。
* [`toUInt64OrDefault`](#toUInt64OrDefault)。
**语法**
```sql theme={null}
toUInt64OrNull(x)
```
**参数**
* `x` — 数值的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `UInt64` 类型的值；如果转换失败，则返回 `NULL`。[`UInt64`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt64OrNull('64'),
toUInt64OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt64OrNull('64'): 64
toUInt64OrNull('abc'): \N
```
## toUInt64OrZero
引入版本：v1.1.0
与 [`toUInt64`](#toUInt64) 类似，此函数会将输入值转换为 [`UInt64`](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回 `0`。
支持的参数：
* (U)Int\* 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt64OrZero('0xc0fe');`。
如果输入值无法表示在 [`UInt64`](/zh/reference/data-types/int-uint) 的范围内，结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt64`](#toUInt64)。
* [`toUInt64OrNull`](#toUInt64OrNull)。
* [`toUInt64OrDefault`](#toUInt64OrDefault)。
**语法**
```sql theme={null}
toUInt64OrZero(x)
```
**参数**
* `x` — 数字的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `UInt64` 类型的值；如果转换失败，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt64OrZero('64'),
toUInt64OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt64OrZero('64'): 64
toUInt64OrZero('abc'): 0
```
## toUInt8
Introduced in: v1.1.0
将输入值转换为 [`UInt8`](/zh/reference/data-types/int-uint) 类型的值。
发生错误时会抛出异常。
支持的参数：
* (U)Int\* 类型的值或其字符串表示形式。
* Float\* 类型的值。
不支持的参数：
* Float\* 类型值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt8('0xc0fe');`。
如果输入值无法在 [UInt8](/zh/reference/data-types/int-uint) 的范围内表示，结果会发生上溢或下溢。
这不视为错误。
例如：`SELECT toUInt8(256) == 0;`。
该函数采用[向零舍入](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero)，即截断数字的小数位。
另请参见：
* [`toUInt8OrZero`](#toUInt8OrZero)。
* [`toUInt8OrNull`](#toUInt8OrNull)。
* [`toUInt8OrDefault`](#toUInt8OrDefault)。
**语法**
```sql theme={null}
toUInt8(expr)
```
**参数**
* `expr` — 返回数字或数字的字符串表示形式的表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
返回 8 位无符号整数值。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt8(8),
toUInt8(8.8),
toUInt8('8')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt8(8): 8
toUInt8(8.8): 8
toUInt8('8'): 8
```
## toUInt8OrDefault
Introduced in：v21.11.0
与 [`toUInt8`](#toUInt8) 类似，此函数会将输入值转换为 [UInt8](/zh/reference/data-types/int-uint) 类型的值，但如果发生错误，则返回默认值。
如果未传入 `default` 值，则发生错误时返回 `0`。
**Syntax**
```sql theme={null}
toUInt8OrDefault(expr[, default])
```
**参数**
* `expr` — 返回数值或数值字符串表示形式的表达式。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `default` — 可选。解析失败时返回的默认值。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
成功时返回 `UInt8` 类型的值；否则，如果传入了默认值，则返回该默认值；如果未传入，则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**转换成功**
```sql title=Query theme={null}
SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))
```
```response title=Response theme={null}
8
```
**转换失败**
```sql title=Query theme={null}
SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))
```
```response title=Response theme={null}
0
```
## toUInt8OrNull
引入版本：v1.1.0
与 [`toUInt8`](#toUInt8) 类似，此函数将输入值转换为 [`UInt8`](/zh/reference/data-types/int-uint) 类型的值，但在出错时返回 `NULL`。
支持的参数：
* (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 `NULL`) ：
* 普通 Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt8OrNull('0xc0fe');`。
如果输入值无法在 [`UInt8`](/zh/reference/data-types/int-uint) 的取值范围内表示，则结果会发生上溢或下溢。
这不视为错误。
另请参见：
* [`toUInt8`](#toUInt8)。
* [`toUInt8OrZero`](#toUInt8OrZero)。
* [`toUInt8OrDefault`](#toUInt8OrDefault)。
**语法**
```sql theme={null}
toUInt8OrNull(x)
```
**参数**
* `x` — 数字的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回类型为 UInt8 的值；如果转换失败，则返回 `NULL`。[`UInt8`](/zh/reference/data-types/int-uint) 或 [`NULL`](/zh/reference/syntax#null)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUInt8OrNull('42'),
toUInt8OrNull('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt8OrNull('42'): 42
toUInt8OrNull('abc'): \N
```
## toUInt8OrZero
首次引入于：v1.1.0
与 [`toUInt8`](#toUInt8) 类似，此函数将输入值转换为 [`UInt8`](/zh/reference/data-types/int-uint) 类型的值，但在发生错误时返回 `0`。
支持的参数：
* (U)Int8/16/32/128/256 的字符串表示形式。
不支持的参数 (返回 `0`) ：
* 普通 Float\* 值的字符串表示形式，包括 `NaN` 和 `Inf`。
* 二进制和十六进制值的字符串表示形式，例如 `SELECT toUInt8OrZero('0xc0fe');`。
如果输入值超出 [`UInt8`](/zh/reference/data-types/int-uint) 的表示范围，则结果会发生上溢或下溢。
这不视为错误。
另请参阅：
* [`toUInt8`](#toUInt8)。
* [`toUInt8OrNull`](#toUInt8OrNull)。
* [`toUInt8OrDefault`](#toUInt8OrDefault)。
**语法**
```sql theme={null}
toUInt8OrZero(x)
```
**参数**
* `x` — 数字的 String 字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UInt8 类型的值；如果转换失败，则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
toUInt8OrZero('-8'),
toUInt8OrZero('abc')
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toUInt8OrZero('-8'): 0
toUInt8OrZero('abc'): 0
```
## toUUID
引入版本：v1.1.0
将 String 类型的值转换为 UUID 值。
**语法**
```sql theme={null}
toUUID(string)
```
**参数**
* `string` — 字符串形式的 UUID。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
根据 UUID 的字符串表示形式返回一个 UUID。[`UUID`](/zh/reference/data-types/uuid)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
```
```response title=Response theme={null}
┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
```
## toUUIDOrZero
Introduced in: v20.12.0
将输入值转换为 [UUID](/zh/reference/data-types/uuid) 类型的值，但如果发生错误，则返回零 UUID。
与 [`toUUID`](/zh/reference/functions/regular-functions/type-conversion-functions#toUUID) 类似，但在转换出错时会返回零 UUID (`00000000-0000-0000-0000-000000000000`) ，而不是抛出异常。
支持的参数：
* 标准格式 UUID 的字符串表示形式 (8-4-4-4-12 个十六进制数字) 。
* 不带连字符的 UUID 字符串表示形式 (32 个十六进制数字) 。
不支持的参数 (返回零 UUID) ：
* 无效的字符串格式。
* 非字符串类型。
**Syntax**
```sql theme={null}
toUUIDOrZero(x)
```
**参数**
* `x` — UUID 的字符串表示形式。[`String`](/zh/reference/data-types/string)
**返回值**
成功时返回 UUID 值，否则返回零 UUID (`00000000-0000-0000-0000-000000000000`) 。[`UUID`](/zh/reference/data-types/uuid)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
toUUIDOrZero('invalid-uuid') AS invalid_uuid
```
```response title=Response theme={null}
┌─valid_uuid───────────────────────────┬─invalid_uuid─────────────────────────┐
│ 550e8400-e29b-41d4-a716-446655440000 │ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```
## toUnixTimestamp64Micro
引入版本：v20.5.0
将 [`DateTime64`](/zh/reference/data-types/datetime64) 转换为具有固定微秒精度的 [`Int64`](/zh/reference/data-types/int-uint) 值。
输入值会根据其精度相应地进行放大或缩小。
输出值以 UTC 为基准，而不是以输入值的时区为基准。
**语法**
```sql theme={null}
toUnixTimestamp64Micro(value)
```
**参数**
* `value` — 任意精度的 DateTime64 类型值。[`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回以微秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH toDateTime64('2025-02-13 23:31:31.011123', 6, 'UTC') AS dt64
SELECT toUnixTimestamp64Micro(dt64);
```
```response title=Response theme={null}
┌─toUnixTimestamp64Micro(dt64)─┐
│ 1739489491011123 │
└────────────────────────────────┘
```
## toUnixTimestamp64Milli
引入版本：v20.5.0
将 [`DateTime64`](/zh/reference/data-types/datetime64) 转换为具有固定毫秒精度的 [`Int64`](/zh/reference/data-types/int-uint) 值。
输入值会根据其精度按相应比例放大或缩小。
输出值是相对于 UTC 的，而不是相对于输入值的时区。
**语法**
```sql theme={null}
toUnixTimestamp64Milli(value)
```
**参数**
* `value` — 具有任意精度的 DateTime64 值。[`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回一个以毫秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Milli(dt64);
```
```response title=Response theme={null}
┌─toUnixTimestamp64Milli(dt64)─┐
│ 1739489491011 │
└──────────────────────────────┘
```
## toUnixTimestamp64Nano
引入版本：v20.5.0
将 [`DateTime64`](/zh/reference/data-types/datetime64) 转换为具有固定纳秒精度的 [`Int64`](/zh/reference/functions/regular-functions/type-conversion-functions#toInt64) 值。
输入值会根据其精度相应放大或缩小。
输出值是相对于 UTC 的，而不是相对于输入值的时区。
**语法**
```sql theme={null}
toUnixTimestamp64Nano(value)
```
**参数**
* `value` — 任意精度的 DateTime64 值。[`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回以纳秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH toDateTime64('2025-02-13 23:31:31.011123456', 9, 'UTC') AS dt64
SELECT toUnixTimestamp64Nano(dt64);
```
```response title=Response theme={null}
┌─toUnixTimestamp64Nano(dt64)────┐
│ 1739489491011123456 │
└────────────────────────────────┘
```
## toUnixTimestamp64Second
引入版本：v24.12.0
将 [`DateTime64`](/zh/reference/data-types/datetime64) 转换为具有固定秒级精度的 [`Int64`](/zh/reference/data-types/int-uint) 值。
输入值会根据其精度相应按比例放大或缩小。
输出值是相对于 UTC 的，而不是相对于输入值的时区。
**语法**
```sql theme={null}
toUnixTimestamp64Second(value)
```
**参数**
* `value` — 任意精度的 DateTime64 类型值。[`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回以秒为单位的 Unix 时间戳。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH toDateTime64('2025-02-13 23:31:31.011', 3, 'UTC') AS dt64
SELECT toUnixTimestamp64Second(dt64);
```
```response title=Response theme={null}
┌─toUnixTimestamp64Second(dt64)─┐
│ 1739489491 │
└───────────────────────────────┘
```