`](/zh/reference/settings/server-settings/settings#macros) 部分中定义，即使服务器的主机名很复杂，也可以使用便于识别的名称来区分服务器。
如果该函数是在分布式表的上下文中执行的，它会生成一个普通列，其中的值与各个分片相关。
**语法**
```sql theme={null}
getMacro(name)
```
**参数**
* `name` — 要获取的 macro 名称。[`const String`](/zh/reference/data-types/string)
**返回值**
返回指定 macro 的值。[`String`](/zh/reference/data-types/string)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT getMacro('test');
```
```response title=Response theme={null}
┌─getMacro('test')─┐
│ Value │
└──────────────────┘
```
## getMaxTableNameLengthForDatabase
首次引入于：v25.1.0
返回指定数据库中表名的最大长度。
**语法**
```sql theme={null}
getMaxTableNameLengthForDatabase(database_name)
```
**参数**
* `database_name` — 指定数据库的名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回最长表名的长度，为整数。
**示例**
**典型用法**
```sql title=Query theme={null}
SELECT getMaxTableNameLengthForDatabase('default');
```
```response title=Response theme={null}
┌─getMaxTableNameLengthForDatabase('default')─┐
│ 206 │
└─────────────────────────────────────────────┘
```
## getMergeTreeSetting
引入于：v25.6.0
返回 MergeTree 设置的当前值。
**语法**
```sql theme={null}
getMergeTreeSetting(setting_name)
```
**参数**
* `setting_name` — 设置名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回 MergeTree 设置的当前值。
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT getMergeTreeSetting('index_granularity');
```
```response title=Response theme={null}
┌─getMergeTreeSetting('index_granularity')─┐
│ 8192 │
└──────────────────────────────────────────┘
```
## getOSKernelVersion
引入版本：v21.11.0
返回包含操作系统内核版本的字符串。
**语法**
```sql theme={null}
getOSKernelVersion()
```
**参数**
* 无。
**返回值**
返回当前操作系统内核版本。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT getOSKernelVersion();
```
```response title=Response theme={null}
┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘
```
## getServerPort
引入版本：v21.10.0
返回给定协议对应的服务器端口号。
**语法**
```sql theme={null}
getServerPort(port_name)
```
**参数**
* `port_name` — 端口名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回 server 的端口号。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT getServerPort('tcp_port');
```
```response title=Response theme={null}
┌─getServerPort('tcp_port')─┐
│ 9000 │
└───────────────────────────┘
```
## getServerSetting
首次引入于：v25.6.0
给定服务器设置名称，返回当前设置的值。
**语法**
```sql theme={null}
getServerSetting(setting_name')
```
**参数**
* `setting_name` — 服务器设置的名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回该服务器设置的当前值。[`Any`](/zh/reference/data-types)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT getServerSetting('allow_use_jemalloc_memory');
```
```response title=Response theme={null}
┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true │
└───────────────────────────────────────────────┘
```
## getSetting
引入版本：v20.7.0
返回某个设置的当前值。
**语法**
```sql theme={null}
getSetting(setting_name)
```
**参数**
* `setting_Name` — 设置名。[`const String`](/zh/reference/data-types/string)
**返回值**
返回该设置的当前值。[`Any`](/zh/reference/data-types)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');
```
```response title=Response theme={null}
┌─getSetting('⋯_analyzer')─┐
│ true │
└──────────────────────────┘
┌─getSetting('⋯_analyzer')─┐
│ false │
└──────────────────────────┘
```
## getSettingOrDefault
自 v24.10.0 起引入
返回某个设置的当前值；如果该设置在当前 profile 中未设置，则返回第二个参数指定的默认值。
**语法**
```sql theme={null}
getSettingOrDefault(setting_name, default_value)
```
**参数**
* `setting_name` — 设置名称。[`String`](/zh/reference/data-types/string)
* `default_value` — 若未设置 custom\_setting，则返回该值。该值可以是任意数据类型，也可以为 NULL。
**返回值**
返回指定设置的当前值；如果该设置未设置，则返回 `default_value`。
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);
```
```response title=Response theme={null}
my_value
100
NULL
```
## getSizeOfEnumType
引入版本：v1.1.0
返回给定 [`Enum`](/zh/reference/data-types/enum) 的字段数量。
**语法**
```sql theme={null}
getSizeOfEnumType(x)
```
**参数**
* `x` — 类型为 `Enum` 的值。[`Enum`](/zh/reference/data-types/enum)
**返回值**
返回输入值为 `Enum` 的字段个数。[`UInt8/16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;
```
```response title=Response theme={null}
┌─x─┐
│ 2 │
└───┘
```
## getSubcolumn
引入版本：v23.3.0
接收表达式或标识符，以及表示子列名称的常量字符串。
返回从表达式中提取的指定子列。
**语法**
```sql theme={null}
getSubcolumn(nested_value, subcolumn_name)
```
**参数**
* 无。
**返回值**
**示例**
**getSubcolumn**
```sql title=Query theme={null}
SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')
```
```response title=Response theme={null}
```
## getTypeSerializationStreams
引入版本：v22.6.0
枚举数据类型的 stream 路径。
此函数仅供开发使用。
**语法**
```sql theme={null}
getTypeSerializationStreams(col)
```
**参数**
* `col` — 用于检测数据类型的列，或数据类型的字符串表示形式。[`Any`](/zh/reference/data-types)
**返回值**
返回一个包含所有序列化子流路径的数组。[`Array(String)`](/zh/reference/data-types/array)
**示例**
**tuple**
```sql title=Query theme={null}
SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))
```
```response title=Response theme={null}
['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']
```
**Map**
```sql title=Query theme={null}
SELECT getTypeSerializationStreams('Map(String, Int64)')
```
```response title=Response theme={null}
['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']
```
## globalVariable
Introduced in：v20.5.0
接受一个常量字符串参数，并返回同名全局变量的值。此函数仅用于兼容 MySQL，对于 ClickHouse 的正常运行既非必需，也没有实际作用。只定义了少数几个虚拟的全局变量。
**Syntax**
```sql theme={null}
globalVariable(name)
```
**参数**
* `name` — 全局变量名。[`String`](/zh/reference/data-types/string)
**返回值**
返回变量 `name` 的值。[`Any`](/zh/reference/data-types)
**示例**
**globalVariable**
```sql title=Query theme={null}
SELECT globalVariable('max_allowed_packet')
```
```response title=Response theme={null}
67108864
```
## hasColumnInTable
引入版本：v1.1.0
检查数据库表中是否存在指定列。
对于嵌套数据结构中的元素，该函数会检查相应列是否存在。
对于嵌套数据结构本身，该函数返回 `0`。
**语法**
```sql theme={null}
hasColumnInTable([hostname[, username[, password]],]database, table, column)
```
**参数**
* `database` — 数据库名称。[`const String`](/zh/reference/data-types/string)
* `table` — 表名称。[`const String`](/zh/reference/data-types/string)
* `column` — 列名称。[`const String`](/zh/reference/data-types/string)
* `hostname` — 可选。要执行检查的远程服务器名称。[`const String`](/zh/reference/data-types/string)
* `username` — 可选。远程服务器的用户名。[`const String`](/zh/reference/data-types/string)
* `password` — 可选。远程服务器的密码。[`const String`](/zh/reference/data-types/string)
**返回值**
如果指定列存在，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**检查现有列**
```sql title=Query theme={null}
SELECT hasColumnInTable('system','metrics','metric')
```
```response title=Response theme={null}
1
```
**检查不存在的列**
```sql title=Query theme={null}
SELECT hasColumnInTable('system','metrics','non-existing_column')
```
```response title=Response theme={null}
0
```
## hasThreadFuzzer
引入版本：v20.6.0
返回 Thread Fuzzer 是否处于启用状态。
此函数仅用于测试和调试。
**语法**
```sql theme={null}
hasThreadFuzzer()
```
**参数**
* 无。
**返回值**
返回 Thread Fuzzer 是否有效。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**检查 Thread Fuzzer 的状态**
```sql title=Query theme={null}
SELECT hasThreadFuzzer()
```
```response title=Response theme={null}
┌─hasThreadFuzzer()─┐
│ 0 │
└───────────────────┘
```
## highlightQuery
Introduced in: v26.5.0
解析 ClickHouse SQL 查询字符串，并返回一组用于语法高亮的高亮范围。
每个范围都是一个命名元组，包含起始位置 (以字节为单位) 、结束位置以及高亮类型。
高亮类型描述片段在语法中的角色 (关键字、标识符、函数等) ，
可用于在 UI 中指定颜色。在 LIKE 和 REGEXP 字符串模式中，元字符
和转义字符会分别高亮显示。
**语法**
```sql theme={null}
highlightQuery(query)
```
**参数**
* `query` — ClickHouse SQL 查询字符串。String。
**返回值**
由命名元组 `(begin UInt64, end UInt64, type Enum8(...))` 组成的数组，表示高亮范围。[`Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))`](/zh/reference/data-types/array)
**示例**
**简单**
```sql title=Query theme={null}
SELECT highlightQuery('SELECT 1')
```
```response title=Response theme={null}
[(0,6,'keyword'),(7,8,'number')]
```
## hostName
引入版本：v20.5.0
返回执行此函数的主机名。
如果该函数在远程服务器上执行 (分布式处理) ，则返回远程服务器的名称。
如果该函数在分布式表的上下文中执行，则会生成一个常规列，其值对应各个分片。
否则，它会产生一个常量值。
**语法**
```sql theme={null}
hostName()
```
**别名**：`hostname`
**参数**
* 无。
**返回值**
返回主机名。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT hostName()
```
```response title=Response theme={null}
┌─hostName()─┐
│ clickhouse │
└────────────┘
```
## icebergBucket
引入版本：v25.5.0
实现了 [Iceberg bucket 转换](https://iceberg.apache.org/spec/#bucket-transform-details.) 的逻辑
**语法**
```sql theme={null}
icebergBucket(N, value)
```
**参数**
* `N` — 桶的数量，即取模值。[`const (U)Int*`](/zh/reference/data-types/int-uint)
* `value` — 要转换的源值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Bool`](/zh/reference/data-types/boolean) 或 [`Decimal`](/zh/reference/data-types/decimal) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`UUID`](/zh/reference/data-types/uuid) 或 [`Date`](/zh/reference/data-types/date) 或 [`Time`](/zh/reference/data-types/time) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
返回源值的 32 位哈希值。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**示例**
```sql title=Query theme={null}
SELECT icebergBucket(5, 1.0 :: Float32)
```
```response title=Response theme={null}
4
```
## icebergTruncate
在 v25.3.0 中引入
实现了 Iceberg truncate transform 的逻辑：[https://iceberg.apache.org/spec/#truncate-transform-details。](https://iceberg.apache.org/spec/#truncate-transform-details。)
**语法**
```sql theme={null}
icebergTruncate(N, value)
```
**参数**
* `value` — 待转换的值。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
与参数类型相同
**示例**
**示例**
```sql title=Query theme={null}
SELECT icebergTruncate(3, 'iceberg')
```
```response title=Response theme={null}
ice
```
## identity
引入版本：v1.1.0
此函数会返回传入的参数，这对调试和测试很有帮助。它可以绕过索引的使用，从而查看全表扫描的性能。查询分析器在查找可用索引时，会忽略 identity 函数中的任何内容，同时也会禁用常量折叠。
**语法**
```sql theme={null}
identity(x)
```
**参数**
* `x` — 输入值。[`Any`](/zh/reference/data-types)
**返回值**
返回原始输入值，不做任何更改。[`Any`](/zh/reference/data-types)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT identity(42)
```
```response title=Response theme={null}
42
```
## ignore
引入于：v1.1.0
接受任意参数，并始终返回 `0`。
**语法**
```sql theme={null}
ignore(x)
```
**参数**
* `x` — 一个未使用的输入值，传入它仅仅是为了避免语法错误。[`Any`](/zh/reference/data-types)
**返回值**
始终返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT ignore(0, 'ClickHouse', NULL)
```
```response title=Response theme={null}
┌─ignore(0, 'ClickHouse', NULL)─┐
│ 0 │
└───────────────────────────────┘
```
## indexHint
引入版本：v1.1.0
此函数用于调试和查看内部信息。
它会忽略其参数，并始终返回 1。
参数不会被求值。
在索引分析过程中，此函数的参数会被视为没有包裹在 `indexHint` 中。
这样一来，你可以根据相应条件选出索引范围内的数据，但不会再按该条件进一步过滤。
ClickHouse 中的索引是稀疏的，因此使用 `indexHint` 返回的数据会比直接指定相同条件更多。
当你运行：
```sql theme={null}
SELECT * FROM test WHERE key = 123;
```
ClickHouse 会做两件事：
1. 使用索引查找哪些粒度 (约由 8192 行组成的块) 可能包含 `key = 123`
2. 读取这些粒度，并逐行过滤，只返回 `key = 123` 的行
因此，即使它从磁盘读取了 8,192 行，最终也只会返回实际匹配的那 1 行。
而当你使用 `indexHint` 运行：
```sql theme={null}
SELECT * FROM test WHERE indexHint(key = 123);
```
ClickHouse 只会做一件事：
1. 使用索引查找哪些粒度可能包含 key = 123，并返回这些粒度中的所有行，**不做**过滤。
它会返回全部 8,192 行，其中包括 `key = 456`、`key = 789` 等对应的行。 (也就是恰好存储在同一粒度中的所有内容。)
`indexHint()` 不是用来提升性能的。它是为了调试，以及帮助你理解 ClickHouse 的索引如何工作：
* 我的条件选中了哪些粒度？
* 这些粒度中有多少行？
* 我的索引是否得到了有效利用？
注意：无法使用 `indexHint` 函数来优化查询。`indexHint` 函数不会优化查询，因为它不会为查询分析提供任何额外信息。把表达式放在 `indexHint` 函数中，并不会比不使用 `indexHint` 更好。`indexHint` 函数只能用于查看内部信息和调试，并不能提升性能。如果你看到除 ClickHouse 贡献者之外的人在使用 `indexHint`，那很可能是个错误，应当将其移除。
**语法**
```sql theme={null}
indexHint(expression)
```
**参数**
* `expression` — 可用于索引范围选择的任意表达式。[`Expression`](/zh/reference/data-types/special-data-types/expression)
**返回值**
始终返回 `1`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**按日期过滤的用法示例**
```sql title=Query theme={null}
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;
```
```response title=Response theme={null}
┌──────────k─┬─count()─┐
│ 2025-09-14 │ 7071 │
│ 2025-09-15 │ 16428 │
│ 2025-09-16 │ 1077 │
│ 2025-09-30 │ 8167 │
└────────────┴─────────┘
```
## initialQueryID
Introduced in: v1.1.0
返回初始查询的 ID。
查询的其他参数可从 [`system.query_log`](/zh/reference/system-tables/query_log) 的 `initial_query_id` 字段中提取。
与 [`queryID`](/zh/reference/functions/regular-functions/other-functions#queryID) 函数不同，`initialQueryID` 在不同分片上返回相同的结果。
**语法**
```sql theme={null}
initialQueryID()
```
**别名**: `initial_query_id`
**参数**
* 无。
**返回值**
返回初始查询的 ID。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
```
```response title=Response theme={null}
┌─count(DISTINCT t)─┐
│ 1 │
└───────────────────┘
```
## initialQueryStartTime
引入版本：v25.4.0
返回当前初始查询的开始时间。
`initialQueryStartTime` 在不同分片上返回相同的结果。
**语法**
```sql theme={null}
initialQueryStartTime()
```
**别名**: `initial_query_start_time`
**参数**
* 无。
**返回值**
返回当前初始查询的开始时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**用法示例**
```sql title=Query theme={null}
CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
```
```response title=Response theme={null}
┌─count(DISTINCT t)─┐
│ 1 │
└───────────────────┘
```
## initializeAggregation
引入版本：v20.6.0
根据单个值计算聚合函数的结果。
此函数可用于通过组合器 [-State](/zh/reference/functions/aggregate-functions/combinators#-state) 初始化聚合函数。
你可以创建聚合函数的状态，并将其插入到类型为 [`AggregateFunction`](/zh/reference/data-types/aggregatefunction) 的列中，或者将已初始化的聚合结果用作默认值。
**语法**
```sql theme={null}
initializeAggregation(aggregate_function, arg1[, arg2, ...])
```
**参数**
* `aggregate_function` — 要初始化的聚合函数名称。[`String`](/zh/reference/data-types/string)
* `arg1[, arg2, ...]` — 聚合函数的参数。[`Any`](/zh/reference/data-types)
**返回值**
返回传递给该函数的每一行的聚合结果。其返回类型与 `initializeAggregation` 的第一个参数指定的函数返回类型相同。[`Any`](/zh/reference/data-types)
**示例**
**uniqState 的基本用法**
```sql title=Query theme={null}
SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
```
```response title=Response theme={null}
┌─uniqMerge(state)─┐
│ 3 │
└──────────────────┘
```
**与 sumState 和 finalizeAggregation 配合使用**
```sql title=Query theme={null}
SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));
```
```response title=Response theme={null}
┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│ 0 │ AggregateFunction(sum, UInt8) │
│ 1 │ AggregateFunction(sum, UInt8) │
│ 2 │ AggregateFunction(sum, UInt8) │
│ 0 │ AggregateFunction(sum, UInt8) │
│ 1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘
```
## isConstant
引入版本：v20.3.0
返回参数是否为常量表达式。
常量表达式是指其结果在查询分析阶段即可确定的表达式，也就是在执行之前就能确定结果的表达式。
例如，基于[literals](/zh/reference/syntax#literals)的表达式就是常量表达式。
此函数主要用于开发、调试和演示。
**语法**
```sql theme={null}
isConstant(x)
```
**参数**
* `x` — 要检查的表达式。[`Any`](/zh/reference/data-types)
**返回值**
如果 `x` 是常量，则返回 `1`；如果 `x` 不是常量，则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**常量表达式**
```sql title=Query theme={null}
SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)
```
```response title=Response theme={null}
┌─isConstant(plus(x, 1))─┐
│ 1 │
└────────────────────────┘
```
**含函数的常量**
```sql title=Query theme={null}
WITH 3.14 AS pi
SELECT isConstant(cos(pi))
```
```response title=Response theme={null}
┌─isConstant(cos(pi))─┐
│ 1 │
└─────────────────────┘
```
**非常量表达式**
```sql title=Query theme={null}
SELECT isConstant(number)
FROM numbers(1)
```
```response title=Response theme={null}
┌─isConstant(number)─┐
│ 0 │
└────────────────────┘
```
**now() 函数的行为**
```sql title=Query theme={null}
SELECT isConstant(now())
```
```response title=Response theme={null}
┌─isConstant(now())─┐
│ 1 │
└───────────────────┘
```
## isDecimalOverflow
引入版本：v20.8.0
检查十进制数的位数是否过多，导致其无法适配给定精度的 Decimal 数据类型。
**语法**
```sql theme={null}
isDecimalOverflow(value[, precision])
```
**参数**
* `value` — 要检查的 Decimal 值。[`Decimal`](/zh/reference/data-types/decimal)
* `precision` — 可选。Decimal 类型的精度；如果省略，则使用第一个参数的原始精度。[`UInt8`](/zh/reference/data-types/int-uint)
**返回值**
如果 Decimal 值的位数超出其精度允许的范围，则返回 `1`；如果 Decimal 值符合指定精度，则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
isDecimalOverflow(toDecimal32(1000000000, 0)),
isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
isDecimalOverflow(toDecimal32(-1000000000, 0));
```
```response title=Response theme={null}
┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│ 1 │ 1 │ 1 │ 1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘
```
## joinGet
引入版本：v18.16.0
允许你像从字典中取值一样从表中提取数据。
使用指定的连接键从 Join 表中获取数据。
仅支持使用 `ENGINE = Join(ANY, LEFT, )` [statement](/zh/reference/engines/table-engines/special/join) 创建的表。
**语法**
```sql theme={null}
joinGet(join_storage_table_name, value_column, join_keys)
```
**参数**
* `join_storage_table_name` — 用于指示在何处执行查找的标识符。系统会在默认数据库中查找该标识符 (请参见配置文件中的参数 `default_database`) 。若要覆盖默认数据库设置，请使用 `USE database_name` 查询，或用点号同时指定数据库和表，例如 `database_name.table_name`。[`String`](/zh/reference/data-types/string)
* `value_column` — 表中包含所需数据的列名。[`const String`](/zh/reference/data-types/string)
* `join_keys` — 连接键列表。[`Any`](/zh/reference/data-types)
**返回值**
返回与键列表对应的值列表。[`Any`](/zh/reference/data-types)
**示例**
**用法示例**
```sql title=Query theme={null}
CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);
SELECT joinGet(db_test.id_val, 'val', toUInt32(1));
```
```response title=Response theme={null}
┌─joinGet(db_test.id_val, 'val', toUInt32(1))─┐
│ 11 │
└─────────────────────────────────────────────┘
```
**与当前数据库中的表一起使用**
```sql title=Query theme={null}
USE db_test;
SELECT joinGet(id_val, 'val', toUInt32(2));
```
```response title=Response theme={null}
┌─joinGet(id_val, 'val', toUInt32(2))─┐
│ 12 │
└─────────────────────────────────────┘
```
**将数组用作连接键**
```sql title=Query theme={null}
CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');
SELECT joinGet(some_table, 'name', 1, 11);
```
```response title=Response theme={null}
┌─joinGet(some_table, 'name', 1, 11)─┐
│ a │
└────────────────────────────────────┘
```
## joinGetOrNull
引入版本：v20.4.0
允许你像从字典中取值一样从表中提取数据。
使用指定的连接键从 Join 表中获取数据。
与 [`joinGet`](#joinGet) 不同的是，当键不存在时，它返回 `NULL`。
仅支持使用 `ENGINE = Join(ANY, LEFT, )` [statement](/zh/reference/engines/table-engines/special/join) 创建的表。
**语法**
```sql theme={null}
joinGetOrNull(join_storage_table_name, value_column, join_keys)
```
**参数**
* `join_storage_table_name` — 用于指明在何处执行查找的标识符。系统会在默认数据库中查找该标识符 (参见配置文件中的参数 default\_database) 。若要覆盖默认数据库，请使用 `USE database_name` 查询，或用点号同时指定数据库和表，例如 `database_name.table_name`。[`String`](/zh/reference/data-types/string)
* `value_column` — 表中包含所需数据的列名。[`const String`](/zh/reference/data-types/string)
* `join_keys` — 连接键列表。[`Any`](/zh/reference/data-types)
**返回值**
返回与键列表对应的值列表；如果未找到某个键，则返回 `NULL`。[`Any`](/zh/reference/data-types)
**示例**
**使用示例**
```sql title=Query theme={null}
CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);
SELECT joinGetOrNull(db_test.id_val, 'val', toUInt32(1)), joinGetOrNull(db_test.id_val, 'val', toUInt32(999));
```
```response title=Response theme={null}
┌─joinGetOrNull(db_test.id_val, 'val', toUInt32(1))─┬─joinGetOrNull(db_test.id_val, 'val', toUInt32(999))─┐
│ 11 │ ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘
```
## lowCardinalityIndices
引入版本：v18.12.0
返回某个值在 [LowCardinality](/zh/reference/data-types/lowcardinality) 列的字典中的位置。位置从 1 开始。由于 LowCardinality 会为每个分片分别维护字典，因此同一个值在不同的分片中，此函数可能返回不同的位置。
**语法**
```sql theme={null}
lowCardinalityIndices(col)
```
**参数**
* `col` — 一个低基数列。[`LowCardinality`](/zh/reference/data-types/lowcardinality)
**返回值**
该值在当前数据分片的字典中的位置。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;
-- 创建两个分片：
INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');
SELECT s, lowCardinalityIndices(s) FROM test;
```
```response title=Response theme={null}
┌─s──┬─lowCardinalityIndices(s)─┐
│ ab │ 1 │
│ cd │ 2 │
│ ab │ 1 │
│ ab │ 1 │
│ df │ 3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
│ ef │ 1 │
│ cd │ 2 │
│ ab │ 3 │
│ cd │ 2 │
│ ef │ 1 │
└────┴──────────────────────────┘
```
## lowCardinalityKeys
引入版本：v18.12.0
返回 [LowCardinality](/zh/reference/data-types/lowcardinality) 列的字典值。
如果块的大小小于或大于字典大小，结果将被截断，或用默认值补齐。
由于 LowCardinality 的字典是按分片分别维护的，因此此函数在不同的分片中可能返回不同的字典值。
**语法**
```sql theme={null}
lowCardinalityKeys(col)
```
**参数**
* `col` — 低基数列。[`LowCardinality`](/zh/reference/data-types/lowcardinality)
**返回值**
返回字典键。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**lowCardinalityKeys**
```sql title=Query theme={null}
DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;
-- 创建两个分片：
INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');
SELECT s, lowCardinalityKeys(s) FROM test;
```
```response title=Response theme={null}
┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │ │
│ cd │ ef │
│ ab │ cd │
│ cd │ ab │
│ ef │ │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │ │
│ cd │ ab │
│ ab │ cd │
│ ab │ df │
│ df │ │
└────┴───────────────────────┘
```
## materialize
引入版本：v1.1.0
将常量转换为仅包含单一值的普通列。
普通列和常量在内存中的表示方式不同。
对于普通参数和常量参数，函数通常会执行不同的代码路径，但结果一般应当相同。
此函数可用于调试这种行为。
**语法**
```sql theme={null}
materialize(x)
```
**参数**
* `x` — 常量。[`Any`](/zh/reference/data-types)
**返回值**
返回一个包含该常量值的普通列。[`Any`](/zh/reference/data-types)
**示例**
**用法示例**
```sql title=Query theme={null}
-- 在下面的示例中，`countMatches` 函数要求第二个参数为常量。
-- 可以使用 `materialize` 函数将常量转换为普通列来调试此行为，
-- 从而验证该函数对非常量参数会抛出错误。
SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));
```
```response title=Response theme={null}
2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String
```
## minSampleSizeContinuous
引入版本：v23.10.0
计算在 A/B 测试中比较两个样本的连续指标均值时所需的最小样本量。
使用[这篇文章](https://towardsdatascience.com/required-sample-size-for-a-b-testing-6f6608dd330a)中描述的公式。
假设实验组和对照组的样本量相同。
返回单个组所需的样本量 (即整个实验所需的样本量是返回值的两倍) 。
还假设实验组和对照组中测试指标的方差相同。
**语法**
```sql theme={null}
minSampleSizeContinuous(baseline, sigma, mde, power, alpha)
```
**别名**: `minSampleSizeContinous`
**参数**
* `baseline` — 指标的基线值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `sigma` — 指标基线值的标准差。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `mde` — 以基线值百分比表示的最小可检测效应 (MDE) (例如，基线值为 112.25 时，MDE 为 0.03 表示预期变化为 112.25 ± 112.25\*0.03) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `power` — 检验所需的检验功效 (1 - II 类错误的概率) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
* `alpha` — 检验所需的显著性水平 (I 类错误的概率) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回一个包含 3 个元素的命名 Tuple：`minimum_sample_size`、`detect_range_lower` 和 `detect_range_upper`。它们分别表示：所需样本量、按返回的所需样本量无法检测出的值范围下界 (计算方式为 `baseline * (1 - mde)`) ，以及按返回的所需样本量无法检测出的值范围上界 (计算方式为 `baseline * (1 + mde)`) (Float64) 。[`Tuple(Float64, Float64, Float64)`](/zh/reference/data-types/tuple)
**示例**
**minSampleSizeContinuous**
```sql title=Query theme={null}
SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size
```
```response title=Response theme={null}
(616.2931945826209,108.8825,115.6175)
```
## minSampleSizeConversion
引入版本：v22.6.0
计算在 A/B 测试中比较两个样本的转化率 (比例) 时所需的最小样本量。
使用[这篇文章](https://towardsdatascience.com/required-sample-size-for-a-b-testing-6f6608dd330a)中描述的公式。假设 treatment 组和 control 组的规模相同。返回单个组所需的样本量 (即整个实验所需的样本量是返回值的两倍) 。
**语法**
```sql theme={null}
minSampleSizeConversion(baseline, mde, power, alpha)
```
**参数**
* `baseline` — 基准转化率。[`Float*`](/zh/reference/data-types/float)
* `mde` — 以百分点表示的最小可检测效应 (MDE) (例如，基准转化率为 0.25 时，MDE 为 0.03 表示预期变化为 0.25 ± 0.03) 。[`Float*`](/zh/reference/data-types/float)
* `power` — 测试所需的检验功效 (1 - II 类错误的概率) 。[`Float*`](/zh/reference/data-types/float)
* `alpha` — 测试所需的显著性水平 (I 类错误的概率) 。[`Float*`](/zh/reference/data-types/float)
**返回值**
返回一个包含 3 个元素的命名 Tuple：`minimum_sample_size`、`detect_range_lower`、`detect_range_upper`。它们分别表示：所需样本量；在返回的所需样本量下无法检测到的值范围下界，计算方式为 `baseline - mde`；在返回的所需样本量下无法检测到的值范围上界，计算方式为 `baseline + mde`。[`Tuple(Float64, Float64, Float64)`](/zh/reference/data-types/tuple)
**示例**
**minSampleSizeConversion**
```sql title=Query theme={null}
SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size
```
```response title=Response theme={null}
(3396.077603219163,0.22,0.28)
```
## neighbor
引入版本：v20.1.0
返回当前行相对指定偏移量处的某列值。
此函数已弃用，且容易出错，因为它基于数据块的物理顺序进行操作，而该顺序可能与用户预期的逻辑顺序不一致。
建议改用适当的窗口函数。
可通过设置 `allow_deprecated_error_prone_window_functions = 1` 启用此函数。
**语法**
```sql theme={null}
neighbor(column, offset[, default_value])
```
**参数**
* `column` — 源列。[`Any`](/zh/reference/data-types)
* `offset` — 相对于当前行的偏移量。正值向前查找，负值向后查找。[`Integer`](/zh/reference/data-types/int-uint)
* `default_value` — 可选。如果偏移量超出数据范围，则返回该值。若未指定，则使用该列类型的默认值。[`Any`](/zh/reference/data-types)
**返回值**
返回指定偏移量处的值；如果超出范围，则返回默认值。[`Any`](/zh/reference/data-types)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;
```
```response title=Response theme={null}
┌─number─┬─neighbor(number, 2)─┐
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
│ 3 │ 5 │
│ 4 │ 6 │
│ 5 │ 7 │
│ 6 │ 8 │
│ 7 │ 9 │
│ 8 │ 0 │
│ 9 │ 0 │
└────────┴─────────────────────┘
```
**使用默认值**
```sql title=Query theme={null}
SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;
```
```response title=Response theme={null}
┌─number─┬─neighbor(number, 2, 999)─┐
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
│ 3 │ 5 │
│ 4 │ 6 │
│ 5 │ 7 │
│ 6 │ 8 │
│ 7 │ 9 │
│ 8 │ 999 │
│ 9 │ 999 │
└────────┴──────────────────────────┘
```
## normalizeQuery
引入版本：v20.8.0
将字面量、由字面量组成的序列以及复杂别名 (包含空白字符、两个以上数字，或长度至少为 36 字节，例如 UUIDs) 替换为占位符 `?`。
**语法**
```sql theme={null}
normalizeQuery(x)
```
**参数**
* `x` — 字符序列。[`String`](/zh/reference/data-types/string)
**返回值**
返回用占位符替换后的给定字符序列。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT normalizeQuery('[1, 2, 3, x]') AS query
```
```response title=Response theme={null}
┌─query────┐
│ [?.., x] │
└──────────┘
```
## normalizeQueryKeepNames
引入版本：v21.2.0
将字面量及其序列替换为占位符 `?`，但不会替换复杂别名 (包含空白字符、超过两位数字，或长度至少为 36 字节，例如 UUIDs) 。
这有助于更好地分析复杂的查询日志。
**语法**
```sql theme={null}
normalizeQueryKeepNames(x)
```
**参数**
* `x` — 字符序列。[`String`](/zh/reference/data-types/string)
**返回值**
返回给定字符序列的占位符形式。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')
```
```response title=Response theme={null}
┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?` │ SELECT ? AS aComplexName123 │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
```
## normalizedQueryHash
引入版本：v20.8.0
对于相似查询，在忽略字面量值的情况下会返回相同的 64 位哈希值。
这有助于分析查询日志。
**语法**
```sql theme={null}
normalizedQueryHash(x)
```
**参数**
* `x` — 字符序列。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 64 位哈希值。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res
```
```response title=Response theme={null}
┌─res─┐
│ 1 │
└─────┘
```
## normalizedQueryHashKeepNames
引入版本：v21.2.0
与 [`normalizedQueryHash`](#normalizedQueryHash) 类似，它会为相似查询返回相同的 64 位哈希值，且不包含字面量的值；但不同的是，它不会在哈希计算前将复杂别名 (包含空白字符、超过两个数字，或长度至少为 36 字节，例如 UUIDs) 替换为占位符。
这有助于分析查询日志。
**语法**
```sql theme={null}
normalizedQueryHashKeepNames(x)
```
**参数**
* `x` — 字符序列。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 64位哈希值。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;
```
```response title=Response theme={null}
┌─normalizedQueryHash─┐
│ 0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│ 1 │
└──────────────────────────────┘
```
## obfuscateQuery
引入版本：v26.4.0
通过将标识符替换为随机词、将字面量替换为随机值，同时保留查询结构，对 SQL 查询进行混淆。
此函数适合在出于调试目的将查询写入日志或共享之前，对其进行匿名化处理。
即使输入的查询相同，不同的行也会生成不同的混淆结果，这有助于
在处理多个查询时保护隐私。
可选的 `tag` 参数可防止在同一函数调用
在一个查询中被多次使用时发生 common subexpression elimination。这样可确保每次调用都会生成不同的混淆结果。
特性：
* 将表名、列名和别名替换为随机词
* 将数字和字符串字面量替换为随机值
* 保留整体查询结构和 SQL 语法
* 对不同的行生成不同的结果
**语法**
```sql theme={null}
obfuscateQuery(query[, tag])
```
**参数**
* `query` — 要混淆处理的 SQL 查询。[`String`](/zh/reference/data-types/string)
* `tag` — 可选。一个值，用于在多次使用相同函数调用时防止公共子表达式消除。
**返回值**
混淆后的查询，其中标识符和字面量会被替换，同时保留原始查询的结构。[`String`](/zh/reference/data-types/string)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')
```
```response title=Response theme={null}
SELECT fruit, number FROM table WHERE number > 12
```
**使用标签防止公共子表达式消除**
```sql title=Query theme={null}
SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)
```
```response title=Response theme={null}
SELECT a FROM b, SELECT c FROM d
```
**不同的行会产生不同的结果**
```sql title=Query theme={null}
SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b
```
```response title=Response theme={null}
A B
```
## obfuscateQueryWithSeed
引入版本：v26.4.0
使用指定的 seed 对 SQL 查询进行混淆，以获得确定性的结果。
与 `obfuscateQuery()` 不同，此函数在给定相同 seed 时会产生确定性的结果。
当你需要在多次运行之间保持混淆结果一致，或希望
为测试或调试复现相同的混淆查询时，这个函数非常有用。
特性：
* 基于提供的 seed 进行确定性混淆
* 相同的 seed 始终会产生相同的混淆结果
* 不同的 seed 会产生不同的结果
* 与 obfuscateQuery() 一样保留查询结构
使用场景：
* 可复现的测试用例
* 在多次运行之间保持一致的匿名化
* 使用一致的混淆查询进行调试
**语法**
```sql theme={null}
obfuscateQueryWithSeed(query, seed)
```
**参数**
* `query` — 要混淆的 SQL 查询。[`String`](/zh/reference/data-types/string)
* `seed` — 用于混淆的种子值。相同的种子会产生确定性的结果。[`Integer`](/zh/reference/data-types/int-uint) 或 [`String`](/zh/reference/data-types/string)
**返回值**
根据提供的种子确定性生成的混淆后查询。[`String`](/zh/reference/data-types/string)
**示例**
**使用整数种子进行确定性混淆**
```sql title=Query theme={null}
SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)
```
```response title=Response theme={null}
SELECT fruit FROM table
```
**使用字符串种子进行确定性混淆**
```sql title=Query theme={null}
SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')
```
```response title=Response theme={null}
SELECT a, b FROM c
```
**相同的 seed 会产生相同的结果**
```sql title=Query theme={null}
SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)
```
```response title=Response theme={null}
true
```
## parseReadableSize
引入版本：v24.6.0
给定一个包含字节大小且以 `B`、`KiB`、`KB`、`MiB`、`MB` 等为单位的字符串 (即 [ISO/IEC 80000-13](https://en.wikipedia.org/wiki/ISO/IEC_80000) 或十进制字节单位) ，此函数返回对应的字节数。
如果函数无法解析输入值，则会抛出异常。
此函数的逆向操作是 [`formatReadableSize`](#formatReadableSize) 和 [`formatReadableDecimalSize`](#formatReadableDecimalSize)。
**语法**
```sql theme={null}
parseReadableSize(x)
```
**参数**
* `x` — 使用 ISO/IEC 80000-13 或十进制字节单位表示的可读大小。[`String`](/zh/reference/data-types/string)
**返回值**
返回字节数，并向上取整到最接近的整数。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;
```
```response title=Response theme={null}
┌─readable_sizes─┬───sizes─┐
│ 1 B │ 1 │
│ 1 KiB │ 1024 │
│ 3 MB │ 3000000 │
│ 5.314 KiB │ 5442 │
└────────────────┴─────────┘
```
## parseReadableSizeOrNull
Introduced in: v24.6.0
给定一个包含字节大小的字符串，并使用 `B`、`KiB`、`KB`、`MiB`、`MB` 等单位 (即 [ISO/IEC 80000-13](https://en.wikipedia.org/wiki/ISO/IEC_80000) 或十进制字节单位) ，此函数会返回对应的字节数。
如果函数无法解析输入值，则返回 `NULL`。
此函数的逆运算为 [`formatReadableSize`](#formatReadableSize) 和 [`formatReadableDecimalSize`](#formatReadableDecimalSize)。
**Syntax**
```sql theme={null}
parseReadableSizeOrNull(x)
```
**参数**
* `x` — 采用 ISO/IEC 80000-13 或十进制字节单位表示的可读大小。[`String`](/zh/reference/data-types/string)
**返回值**
返回字节数，向上取整到最接近的整数；如果无法解析输入，则返回 `NULL` [`Nullable(UInt64)`](/zh/reference/data-types/nullable)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;
```
```response title=Response theme={null}
┌─readable_sizes─┬───sizes─┐
│ 1 B │ 1 │
│ 1 KiB │ 1024 │
│ 3 MB │ 3000000 │
│ 5.314 KiB │ 5442 │
│ invalid │ ᴺᵁᴸᴸ │
└────────────────┴─────────┘
```
## parseReadableSizeOrZero
Introduced in：v24.6.0
给定一个包含字节大小以及 `B`、`KiB`、`KB`、`MiB`、`MB` 等单位的字符串 (即 [ISO/IEC 80000-13](https://en.wikipedia.org/wiki/ISO/IEC_80000) 或十进制字节单位) ，该函数返回对应的字节数。
如果该函数无法解析输入值，则返回 `0`。
该函数的逆操作为 [`formatReadableSize`](#formatReadableSize) 和 [`formatReadableDecimalSize`](#formatReadableDecimalSize)。
**Syntax**
```sql theme={null}
parseReadableSizeOrZero(x)
```
**参数**
* `x` — 采用 ISO/IEC 80000-13 或十进制字节单位表示的可读大小值。[`String`](/zh/reference/data-types/string)
**返回值**
返回字节数，向上取整到最近的整数；如果无法解析输入，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;
```
```response title=Response theme={null}
┌─readable_sizes─┬───sizes─┐
│ 1 B │ 1 │
│ 1 KiB │ 1024 │
│ 3 MB │ 3000000 │
│ 5.314 KiB │ 5442 │
│ invalid │ 0 │
└────────────────┴─────────┘
```
## parseTimeDelta
引入版本：v22.7.0
解析由一串数字及其后类似时间单位的内容组成的序列。
时间增量字符串使用以下时间单位表示：
* `years`, `year`, `yr`, `y`
* `months`, `month`, `mo`
* `weeks`, `week`, `w`
* `days`, `day`, `d`
* `hours`, `hour`, `hr`, `h`
* `minutes`, `minute`, `min`, `m`
* `seconds`, `second`, `sec`, `s`
* `milliseconds`, `millisecond`, `millisec`, `ms`
* `microseconds`, `microsecond`, `microsec`, `μs`, `µs`, `us`
* `nanoseconds`, `nanosecond`, `nanosec`, `ns`
多个时间单位可以用分隔符 (空格、`;`、`-`、`+`、`,`、`:`) 组合在一起。
年和月的长度为近似值：1 年按 365 天计算，1 个月按 30.5 天计算。
**语法**
```sql theme={null}
parseTimeDelta(timestr)
```
**参数**
* `timestr` — 由一串数字加上类似时间单位的内容组成的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
秒数。[`Float64`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT parseTimeDelta('11s+22min')
```
```response title=Response theme={null}
┌─parseTimeDelta('11s+22min')─┐
│ 1331 │
└─────────────────────────────┘
```
**复合时间单位**
```sql title=Query theme={null}
SELECT parseTimeDelta('1yr2mo')
```
```response title=Response theme={null}
┌─parseTimeDelta('1yr2mo')─┐
│ 36806400 │
└──────────────────────────┘
```
## partitionId
引入版本：v21.4.0
计算[分区 ID](/zh/reference/engines/table-engines/mergetree-family/custom-partitioning-key)。
此函数较慢，不应在大量行上调用。
**语法**
```sql theme={null}
partitionId(column1[, column2, ...])
```
**别名**: `partitionID`
**参数**
* `column1, column2, ...` — 要返回其分区 ID 的列。
**返回值**
返回该行所属的分区 ID。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
DROP TABLE IF EXISTS tab;
CREATE TABLE tab
(
i int,
j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();
INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);
SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;
```
```response title=Response theme={null}
┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1 │ 1 │
│ 1 │ 2 │ 1 │ 1 │
│ 1 │ 3 │ 1 │ 1 │
│ 2 │ 4 │ 2 │ 2 │
│ 2 │ 5 │ 2 │ 2 │
│ 2 │ 6 │ 2 │ 2 │
└───┴───┴────────────────┴───────────────┘
```
## queryID
引入版本：v21.9.0
返回当前查询的 ID。
查询的其他参数可以从 [`system.query_log`](/zh/reference/system-tables/query_log) 表中的 `query_id` 字段提取。
与 [`initialQueryID`](#initialQueryID) 函数不同，`queryID` 在不同分片上可能返回不同的结果。
**语法**
```sql theme={null}
queryID()
```
**别名**: `query_id`
**参数**
* 无。
**返回值**
返回当前查询的 ID。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
```
```response title=Response theme={null}
┌─count(DISTINCT t)─┐
│ 3 │
└───────────────────┘
```
## revision
引入版本：v22.7.0
返回当前 ClickHouse server 的修订号。
**语法**
```sql theme={null}
revision()
```
**参数**
* 无。
**返回值**
返回当前 ClickHouse server 的修订版本。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT revision()
```
```response title=Response theme={null}
┌─revision()─┐
│ 54485 │
└────────────┘
```
## rowNumberInAllBlocks
引入版本：v1.1.0
为处理的每一行返回唯一的行号。
**语法**
```sql theme={null}
rowNumberInAllBlocks()
```
**参数**
* 无。
**返回值**
返回该行在数据块中的序号，从 `0` 开始。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT rowNumberInAllBlocks()
FROM
(
SELECT *
FROM system.numbers_mt
LIMIT 10
)
SETTINGS max_block_size = 2
```
```response title=Response theme={null}
┌─rowNumberInAllBlocks()─┐
│ 0 │
│ 1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 4 │
│ 5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 2 │
│ 3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 6 │
│ 7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 8 │
│ 9 │
└────────────────────────┘
```
## rowNumberInBlock
引入版本：v1.1.0
对于 `rowNumberInBlock` 处理的每个[块](/zh/resources/develop-contribute/introduction/architecture#block)，返回当前行的编号。
返回的编号在每个块内都从 0 开始。
**语法**
```sql theme={null}
rowNumberInBlock()
```
**参数**
* 无。
**返回值**
返回数据块中行的序号，从 `0` 开始。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT rowNumberInBlock()
FROM
(
SELECT *
FROM system.numbers_mt
LIMIT 10
) SETTINGS max_block_size = 2
```
```response title=Response theme={null}
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
```
## runningAccumulate
引入版本：v1.1.0
对数据块中每一行的聚合函数状态进行累积。
**已弃用**
每当进入新的数据块时，状态都会被重置。
由于这种行为容易出错，该函数已被弃用，建议改用[窗口函数](/zh/reference/functions/window-functions)。
你可以使用设置 [`allow_deprecated_error_prone_window_functions`](/zh/reference/settings/session-settings#allow_deprecated_error_prone_window_functions) 来允许使用此函数。
**语法**
```sql theme={null}
runningAccumulate(agg_state[, grouping])
```
**参数**
* `agg_state` — 聚合函数状态。[`AggregateFunction`](/zh/reference/data-types/aggregatefunction)
* `grouping` — 可选。分组键。如果 `grouping` 的值发生变化，函数状态将被重置。它可以是任意一种定义了相等运算符的受支持数据类型。[`Any`](/zh/reference/data-types)
**返回值**
返回每一行的累积结果。[`Any`](/zh/reference/data-types)
**示例**
**使用 initializeAggregation 的使用示例**
```sql title=Query theme={null}
WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
number,
finalizeAggregation(one_row_sum_state) AS one_row_sum,
runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);
```
```response title=Response theme={null}
┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│ 0 │ 0 │ 0 │
│ 1 │ 1 │ 1 │
│ 2 │ 2 │ 3 │
│ 3 │ 3 │ 6 │
│ 4 │ 4 │ 10 │
└────────┴─────────────┴────────────────┘
```
## runningConcurrency
引入版本：v21.3.0
计算并发事件的数量。
每个事件都有开始时间和结束时间。
开始时间计入事件，而结束时间不计入事件。
开始时间列和结束时间列必须具有相同的数据类型。
该函数会针对每个事件的开始时间，计算处于活动状态的 (并发) 事件总数。
**要求**
事件必须按开始时间升序排列。
如果不满足此要求，函数会引发异常。
每个数据块都会单独处理。
如果不同数据块中的事件发生重叠，则无法正确处理。
**已弃用**
建议改用[窗口函数](/zh/reference/functions/window-functions)。
**语法**
```sql theme={null}
runningConcurrency(start, end)
```
**参数**
* `start` — 事件开始时间所在的列。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `end` — 事件结束时间所在的列。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回每个事件开始时刻的并发事件数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT start, runningConcurrency(start, end) FROM example_table;
```
```response title=Response theme={null}
┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │ 1 │
│ 2025-03-06 │ 2 │
│ 2025-03-07 │ 3 │
│ 2025-03-11 │ 2 │
└────────────┴────────────────────────────────┘
```
## runningDifference
引入版本：v1.1.0
计算数据块中相邻两行值之间的差值。
第一行返回 `0`，后续各行返回与前一行的差值。
**已弃用**
该函数仅返回当前正在处理的数据块内的差值。
由于这种行为容易出错，该函数已被弃用。
建议改用[窗口函数](/zh/reference/functions/window-functions)。
你可以使用设置 [`allow_deprecated_error_prone_window_functions`](/zh/reference/settings/session-settings#allow_deprecated_error_prone_window_functions) 来允许使用此函数。
函数的结果取决于受影响的数据块以及块内数据的顺序。
计算 `runningDifference()` 时的行顺序可能与最终返回给用户的行顺序不同。
为避免这种情况，你可以创建一个带有 [`ORDER BY`](/zh/reference/statements/select/order-by) 的子查询，并在子查询外部调用该函数。
请注意，块大小会影响结果。
`runningDifference` 的内部状态会在每个新块开始时重置。
**语法**
```sql theme={null}
runningDifference(x)
```
**参数**
* `x` — 要计算逐行差分的列。[`Any`](/zh/reference/data-types)
**返回值**
返回相邻值之间的差值，首行为 0。
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
EventID,
EventTime,
runningDifference(EventTime) AS delta
FROM
(
SELECT
EventID,
EventTime
FROM events
WHERE EventDate = '2025-11-24'
ORDER BY EventTime ASC
LIMIT 5
);
```
```response title=Response theme={null}
┌─EventID─┬───────────EventTime─┬─delta─┐
│ 1106 │ 2025-11-24 00:00:04 │ 0 │
│ 1107 │ 2025-11-24 00:00:05 │ 1 │
│ 1108 │ 2025-11-24 00:00:05 │ 0 │
│ 1109 │ 2025-11-24 00:00:09 │ 4 │
│ 1110 │ 2025-11-24 00:00:10 │ 1 │
└─────────┴─────────────────────┴───────┘
```
**块大小影响示例**
```sql title=Query theme={null}
SELECT
number,
runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;
```
```response title=Response theme={null}
┌─number─┬─diff─┐
│ 0 │ 0 │
└────────┴──────┘
┌─number─┬─diff─┐
│ 65536 │ 0 │
└────────┴──────┘
```
## runningDifferenceStartingWithFirstValue
引入版本：v1.1.0
计算数据块中相邻行值之间的差值，但与 [`runningDifference`](#runningDifference) 不同，它返回的是第一行的实际值，而不是 `0`。
**已弃用**
仅返回当前处理的数据块内的差值。
由于这种行为容易导致错误，该函数已被弃用。
建议改用[窗口函数](/zh/reference/functions/window-functions)。
你可以使用设置 `allow_deprecated_error_prone_window_functions` 来允许使用此函数。
**语法**
```sql theme={null}
runningDifferenceStartingWithFirstValue(x)
```
**参数**
* `x` — 用于计算逐行差分的列。[`Any`](/zh/reference/data-types)
**返回值**
返回相邻值之间的差值；对于第一行，返回该行的值。[`Any`](/zh/reference/data-types)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
number,
runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);
```
```response title=Response theme={null}
┌─number─┬─diff─┐
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 1 │
│ 3 │ 1 │
│ 4 │ 1 │
└────────┴──────┘
```
## serverUUID
引入版本：v20.1.0
返回服务器首次启动时生成的随机唯一 UUID (v4) 。
该 UUID 会被持久保存，也就是说，服务器第二次、第三次等后续启动时返回的都是同一个 UUID。
**语法**
```sql theme={null}
serverUUID()
```
**参数**
* 无。
**返回值**
返回服务器的随机 UUID。[`UUID`](/zh/reference/data-types/uuid)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT serverUUID();
```
```response title=Response theme={null}
┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f │
└──────────────────────────────────────────┘
```
## shardCount
引入版本：v21.9.0
返回分布式查询的分片总数。
如果查询不是分布式查询，则返回常量值 `0`。
**语法**
```sql theme={null}
shardCount()
```
**参数**
* 无。
**返回值**
返回分片总数或 `0`。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
-- 参见上方的 shardNum() 示例，该示例同时演示了 shardCount() 的用法
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;
```
```response title=Response theme={null}
┌─shardCount()─┐
│ 2 │
│ 2 │
└──────────────┘
```
## shardNum
自 v21.9.0 引入
返回在分布式查询中处理部分数据的分片索引。
索引从 `1` 开始。
如果查询不是分布式查询，则返回常量值 `0`。
**语法**
```sql theme={null}
shardNum()
```
**参数**
* 无。
**返回值**
返回分片索引或常量 `0`。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;
```
```response title=Response theme={null}
┌─dummy─┬─shardNum()─┬─shardCount()─┐
│ 0 │ 1 │ 2 │
│ 0 │ 2 │ 2 │
└───────┴────────────┴──────────────┘
```
## showCertificate
引入版本：v22.6.0
如果已配置，将显示当前服务器的 SSL 证书信息。
有关如何将 ClickHouse 配置为使用 OpenSSL 证书验证连接的更多信息，请参见 [配置 TLS](/zh/concepts/features/security/tls/configuring-tls)。
**语法**
```sql theme={null}
showCertificate()
```
**参数**
* 无。
**返回值**
返回与已配置的 SSL 证书相关的键值对映射。[`Map(String, String)`](/zh/reference/data-types/map)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT showCertificate() FORMAT LineAsString;
```
```response title=Response theme={null}
{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May 7 17:01:21 2024 GMT','not_after':'May 7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}
```
## sleep
引入版本：v1.1.0
按指定秒数暂停查询的执行。
该函数主要用于测试和调试。
通常不应在生产环境中使用 `sleep()` 函数，因为它可能会对查询性能和系统响应速度产生负面影响。
不过，在以下场景中它可能会很有用：
1. **测试**：在测试或对 ClickHouse 进行基准测试时，你可能希望模拟延迟或引入暂停，以观察系统在特定条件下的表现。
2. **调试**：如果你需要在某个特定时间点检查系统状态或查询执行情况，可以使用 `sleep()` 引入暂停，以便检查或收集相关信息。
3. **模拟**：在某些情况下，你可能希望模拟真实场景中的延迟或暂停，例如网络延迟或对外部系统的依赖。
请谨慎使用 `sleep()` 函数，并且仅在确有必要时使用，因为它可能会影响 ClickHouse 系统的整体性能和响应速度。
出于安全原因，该函数只能在 default 用户的 profile 中执行 (且已启用 `allow_sleep`) 。
**语法**
```sql theme={null}
sleep(seconds)
```
**参数**
* `seconds` — 暂停查询执行的秒数，最长为 3 秒。可使用浮点数来指定小数秒。[`const UInt*`](/zh/reference/data-types/int-uint) 或 [`const Float*`](/zh/reference/data-types/float)
**返回值**
返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
-- 此查询将暂停 2 秒后完成。
-- 在此期间，不会返回任何结果，查询将显示为挂起或无响应状态。
SELECT sleep(2);
```
```response title=Response theme={null}
┌─sleep(2)─┐
│ 0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.
```
## sleepEachRow
Introduced in: v1.1.0
将查询执行按结果集中的每一行暂停指定的秒数。
`sleepEachRow()` 函数主要用于测试和调试，类似于 [`sleep()`](#sleep) 函数。
它可以在处理每一行时模拟延迟或插入暂停，这在以下场景中很有用：
1. **测试**：在特定条件下测试或对 ClickHouse 进行基准测试时，可以使用 `sleepEachRow()` 为处理的每一行模拟延迟或插入暂停。
2. **调试**：如果你需要针对处理的每一行检查系统状态或查询执行情况，可以使用 `sleepEachRow()` 插入暂停，以便检查或收集相关信息。
3. **模拟**：在某些情况下，你可能希望模拟真实场景中每处理一行都会发生延迟或暂停的情况，例如与外部系统交互或遇到网络延迟时。
与 `sleep()` 函数一样，应谨慎使用 `sleepEachRow()`，并且仅在必要时使用，因为它可能会显著影响 ClickHouse 系统的整体性能和响应能力，尤其是在处理大型结果集时。
**语法**
```sql theme={null}
sleepEachRow(seconds)
```
**参数**
* `seconds` — 结果集中的每一行在查询执行时暂停的秒数，最长为 3 秒。可以使用浮点值来指定秒的小数部分。[`const UInt*`](/zh/reference/data-types/int-uint) 或 [`const Float*`](/zh/reference/data-types/float)
**返回值**
每一行都返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
-- 输出将会延迟，每行之间暂停 0.5 秒。
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;
```
```response title=Response theme={null}
┌─number─┬─sleepEachRow(0.5)─┐
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 0 │
│ 3 │ 0 │
│ 4 │ 0 │
└────────┴───────────────────┘
```
## structureToCapnProtoSchema
引入版本：v23.8.0
用于将 ClickHouse 表结构转换为 CapnProto 格式 schema 的函数
**语法**
```sql theme={null}
structureToCapnProtoSchema(table_structure, message)
```
**参数**
* 无。
**返回值**
**示例**
**random**
```sql title=Query theme={null}
SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw
```
```response title=Response theme={null}
struct MessageName
{
s @0 : Data;
x @1 : UInt32;
}
```
## structureToProtobufSchema
引入版本：v23.8.0
将 ClickHouse 表结构转换为 Protobuf 格式的 schema。
此函数接收 ClickHouse 表结构定义，并将其转换为采用 proto3 语法的 Protocol Buffers (Protobuf) schema 定义。这对于生成与 ClickHouse 表结构相匹配、可用于数据交换的 Protobuf schema 非常有用。
**语法**
```sql theme={null}
structureToProtobufSchema(structure, message_name)
```
**参数**
* `structure` — 以字符串形式表示的 ClickHouse 表结构定义 (例如：'column1 Type1, column2 Type2') 。[`String`](/zh/reference/data-types/string)
* `message_name` — 生成的 schema 中的 Protobuf 消息类型名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回采用 proto3 语法、与输入 ClickHouse 结构对应的 Protobuf schema 定义。[`String`](/zh/reference/data-types/string)
**示例**
**将 ClickHouse 结构转换为 Protobuf schema**
```sql title=Query theme={null}
SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;
```
```response title=Response theme={null}
syntax = "proto3";
message MessageName
{
bytes s = 1;
uint32 x = 2;
}
```
## tcpPort
引入版本：v20.12.0
返回服务器正在监听的[原生接口](/zh/concepts/features/interfaces/tcp) TCP 端口号。
如果在分布式表的上下文中执行，此函数会生成一个普通列，其值对应各个分片。
否则会产生一个常量值。
**语法**
```sql theme={null}
tcpPort()
```
**参数**
* 无。
**返回值**
返回 TCP 端口号。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT tcpPort()
```
```response title=Response theme={null}
┌─tcpPort()─┐
│ 9000 │
└───────────┘
```
## throwIf
引入版本：v1.1.0
如果参数 x 为 true，则抛出异常。
要使用 `error_code` 参数，必须启用配置参数 `allow_custom_error_code_in_throw`。
**语法**
```sql theme={null}
throwIf(x[, message[, error_code]])
```
**参数**
* `x` — 要检查的条件。[`Any`](/zh/reference/data-types)
* `message` — 可选。自定义错误信息。[`const String`](/zh/reference/data-types/string)
* `error_code` — 可选。自定义错误代码。[`const Int8/16/32`](/zh/reference/data-types/int-uint)
**返回值**
如果条件为 `false`，则返回 `0`；如果条件为 `true`，则抛出异常。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT throwIf(number = 3, 'Too many') FROM numbers(10);
```
```response title=Response theme={null}
↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.
```
## toColumnTypeName
引入版本：v1.1.0
返回给定值的数据类型内部名称。
与函数 [`toTypeName`](#toTypeName) 不同，返回的数据类型可能包含内部包装列，如 `Const` 和 `LowCardinality`。
**语法**
```sql theme={null}
toColumnTypeName(value)
```
**参数**
* `value` — 要返回其内部数据类型名称的值。[`Any`](/zh/reference/data-types)
**返回值**
返回用于表示该值的内部数据类型名称。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));
```
```response title=Response theme={null}
┌─toColumnTypeName(CAST('2025-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32) │
└───────────────────────────────────────────────────────────┘
```
## toTypeName
引入版本：v1.1.0
返回传入参数的类型名称。
如果传入 `NULL`，该函数会返回类型 `Nullable(Nothing)`，对应于 ClickHouse 内部对 `NULL` 的表示。
**语法**
```sql theme={null}
toTypeName(x)
```
**参数**
* `x` — 任意类型的值。[`Any`](/zh/reference/data-types)
**返回值**
返回输入值的数据类型名称。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toTypeName(123)
```
```response title=Response theme={null}
┌─toTypeName(123)─┐
│ UInt8 │
└─────────────────┘
```
## tokenizeQuery
引入版本：v26.5.0
将 ClickHouse SQL 查询字符串标记化，并返回由标记组成的数组。
每个标记都是一个命名元组，包含起始位置 (以字节为单位) 、结束位置以及标记类型。
**语法**
```sql theme={null}
tokenizeQuery(query)
```
**参数**
* `query` — 一个 ClickHouse SQL 查询字符串。String。
**返回值**
一个命名元组数组 `(begin UInt64, end UInt64, type Enum8(...))`，表示该查询的各个标记。[`Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))`](/zh/reference/data-types/array)
**示例**
**simple**
```sql title=Query theme={null}
SELECT tokenizeQuery('SELECT 1')
```
```response title=Response theme={null}
[(0,6,'BareWord'),(6,7,'Whitespace'),(7,8,'Number')]
```
## transactionID
引入版本：v22.6.0
返回事务的 ID。
此函数属于 Experimental 功能集的一部分。
如需启用实验性事务支持，请将以下设置添加到你的[配置文件](/zh/concepts/features/configuration/server-config/configuration-files)中：
```xml theme={null}
1
```
更多信息请参见[事务 (ACID) 支持](/zh/concepts/features/operations/insert/transactions#transactions-commit-and-rollback)页面。
**语法**
```sql theme={null}
transactionID()
```
**参数**
* 无。
**返回值**
返回一个由 `start_csn`、`local_tid` 和 `host_id` 组成的 Tuple。
* `start_csn`：全局顺序号，即该事务开始时看到的最新提交时间戳。
* `local_tid`：本地顺序号，对于该主机在特定 start\_csn 下启动的每个事务都是唯一的。
* `host_id`：启动该事务的主机 UUID。
[`Tuple(UInt64, UInt64, UUID)`](/zh/reference/data-types/tuple)
**示例**
**用法示例**
```sql title=Query theme={null}
BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;
```
```response title=Response theme={null}
┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘
```
## transactionLatestSnapshot
引入版本：v22.6.0
返回可用于读取的某个[事务](/zh/concepts/features/operations/insert/transactions#transactions-commit-and-rollback)的最新快照 (提交序列号) 。
此函数属于 Experimental 功能集的一部分。请在配置中添加以下设置，以启用实验性事务支持：
```xml theme={null}
1
```
更多信息请参见页面 [事务 (ACID) 支持](/zh/concepts/features/operations/insert/transactions#transactions-commit-and-rollback)。
**语法**
```sql theme={null}
transactionLatestSnapshot()
```
**参数**
* 无。
**返回值**
返回事务的最新快照 (CSN) 。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;
```
```response title=Response theme={null}
┌─transactionLatestSnapshot()─┐
│ 32 │
└─────────────────────────────┘
```
## transactionOldestSnapshot
引入版本：v22.6.0
返回某个正在运行的[事务](/zh/concepts/features/operations/insert/transactions#transactions-commit-and-rollback)可见的最早快照 (提交序列号) 。
此函数属于 Experimental 功能集的一部分。请通过将以下设置添加到配置中来启用实验性事务支持：
```xml theme={null}
1
```
更多信息请参见[事务 (ACID) 支持](/zh/concepts/features/operations/insert/transactions#transactions-commit-and-rollback)页面。
**语法**
```sql theme={null}
transactionOldestSnapshot()
```
**参数**
* 无。
**返回值**
返回事务中最早的快照 (CSN) 。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;
```
```response title=Response theme={null}
┌─transactionOldestSnapshot()─┐
│ 32 │
└─────────────────────────────┘
```
## transform
在 v1.1.0 中引入
根据显式定义的元素映射关系，将一个值转换为另一个值。
此函数有两种形式：
* `transform(x, array_from, array_to, default)` - 使用映射数组转换 `x`，对未匹配的元素返回默认值
* `transform(x, array_from, array_to)` - 执行相同的转换，但如果未找到匹配项，则返回原始 `x`
该函数会在 `array_from` 中查找 `x`，并返回 `array_to` 中相同索引位置上的对应元素。
如果在 `array_from` 中未找到 `x`，则返回 `default` 值 (4 参数版本) 或原始 `x` (3 参数版本) 。
如果 `array_from` 中存在多个匹配元素，则返回与第一个匹配项对应的元素。
要求：
* `array_from` 和 `array_to` 必须包含相同数量的元素
* 对于 4 参数版本：`transform(T, Array(T), Array(U), U) -> U`，其中 `T` 和 `U` 可以是不同但兼容的类型
* 对于 3 参数版本：`transform(T, Array(T), Array(T)) -> T`，其中所有类型都必须相同
**语法**
```sql theme={null}
transform(x, array_from, array_to[, default])
```
**参数**
* `x` — 要转换的值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Decimal`](/zh/reference/data-types/decimal) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
* `array_from` — 用于查找匹配项的常量值数组。[`Array((U)Int*)`](/zh/reference/data-types/array) 或 [`Array(Decimal)`](/zh/reference/data-types/array) 或 [`Array(Float*)`](/zh/reference/data-types/array) 或 [`Array(String)`](/zh/reference/data-types/array) 或 [`Array(Date)`](/zh/reference/data-types/array) 或 [`Array(DateTime)`](/zh/reference/data-types/array)
* `array_to` — 常量值数组，用于返回与 `array_from` 中匹配项对应的值。[`Array((U)Int*)`](/zh/reference/data-types/array) 或 [`Array(Decimal)`](/zh/reference/data-types/array) 或 [`Array(Float*)`](/zh/reference/data-types/array) 或 [`Array(String)`](/zh/reference/data-types/array) 或 [`Array(Date)`](/zh/reference/data-types/array) 或 [`Array(DateTime)`](/zh/reference/data-types/array)
* `default` — 可选。如果在 `array_from` 中找不到 `x`，则返回该值。如果省略，则原样返回 `x`。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Decimal`](/zh/reference/data-types/decimal) 或 [`Float*`](/zh/reference/data-types/float) 或 [`String`](/zh/reference/data-types/string) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
如果 `x` 与 `array_from` 中的某个元素匹配，则返回 `array_to` 中对应的值；否则返回 `default` (如果提供) 或 `x` (如果未提供 `default`) 。[`Any`](/zh/reference/data-types)
**示例**
**transform(T, Array(T), Array(U), U) -> U**
```sql title=Query theme={null}
SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC
```
```response title=Response theme={null}
┌─title─────┬──────c─┐
│ Yandex │ 498635 │
│ Google │ 229872 │
│ Other │ 104472 │
└───────────┴────────┘
```
**transform(T, Array(T), Array(T)) -> T**
```sql title=Query theme={null}
SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10
```
```response title=Response theme={null}
┌─s──────────────┬───────c─┐
│ │ 2906259 │
│ www.yandex │ 867767 │
│ ███████.ru │ 313599 │
│ mail.yandex.ru │ 107147 │
│ ██████.ru │ 100355 │
│ █████████.ru │ 65040 │
│ news.yandex.ru │ 64515 │
│ ██████.net │ 59141 │
│ example.com │ 57316 │
└────────────────┴─────────┘
```
## uniqThetaIntersect
引入版本：v22.9.0
对两个 uniqThetaSketch 对象进行交集计算 (集合运算 ∩) ，结果是一个新的 uniqThetaSketch。
**语法**
```sql theme={null}
uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)
```
**参数**
* `uniqThetaSketch` — uniqThetaSketch 对象。[`Tuple`](/zh/reference/data-types/tuple) 或 [`Array`](/zh/reference/data-types/array) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
新的 uniqThetaSketch，其中包含交集结果。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);
```
```response title=Response theme={null}
┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│ 1 │ 2 │ 3 │
└───────────────┴───────────────┴───────────────┘
```
## uniqThetaNot
引入版本：v22.9.0
对两个 uniqThetaSketch 对象执行 a\_not\_b 计算 (集合运算 ×) ，返回一个新的 uniqThetaSketch。
**语法**
```sql theme={null}
uniqThetaNot(uniqThetaSketch,uniqThetaSketch)
```
**参数**
* `uniqThetaSketch` — uniqThetaSketch 对象。[`Tuple`](/zh/reference/data-types/tuple) 或 [`Array`](/zh/reference/data-types/array) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
返回一个新的 uniqThetaSketch，表示 a\_not\_b 的结果。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);
```
```response title=Response theme={null}
┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│ 2 │ 3 │ 2 │
└─────────┴───────────────┴───────────────┘
```
## uniqThetaUnion
在 v22.9.0 中引入
对两个 uniqThetaSketch 对象进行并集计算 (集合运算 ∪) ，结果为一个新的 uniqThetaSketch。
**语法**
```sql theme={null}
uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)
```
**参数**
* `uniqThetaSketch` — uniqThetaSketch 对象。[`Tuple`](/zh/reference/data-types/tuple) 或 [`Array`](/zh/reference/data-types/array) 或 [`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
返回一个新的 uniqThetaSketch，其中包含并集运算结果。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);
```
```response title=Response theme={null}
┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│ 4 │ 2 │ 3 │
└───────────┴───────────────┴───────────────┘
```
## 运行时间
引入版本：v1.1.0
返回服务器的运行时间，单位为秒。
如果在分布式表中执行，此函数会生成一个普通列，其值对应每个分片。
否则，它会生成一个常量值。
**语法**
```sql theme={null}
uptime()
```
**参数**
* 无。
**返回值**
返回服务器的运行时间 (以秒为单位) 。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT uptime() AS Uptime
```
```response title=Response theme={null}
┌─Uptime─┐
│ 55867 │
└────────┘
```
## variantElement
引入版本：v25.2.0
从 `Variant` 列中提取指定类型的列。
**语法**
```sql theme={null}
variantElement(variant, type_name[, default_value])
```
**参数**
* `variant` — Variant 列。[`Variant`](/zh/reference/data-types/variant)
* `type_name` — 要提取的 Variant 类型名称。[`String`](/zh/reference/data-types/string)
* `default_value` — 如果 `variant` 中不存在指定的 Variant 类型，则使用该默认值。可以是任意类型。可选。[`Any`](/zh/reference/data-types)
**返回值**
返回从 Variant 列中提取出的指定 Variant 类型的列。[`Any`](/zh/reference/data-types)
**示例**
**使用示例**
```sql title=Query theme={null}
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;
```
```response title=Response theme={null}
┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [] │
│ 42 │ ᴺᵁᴸᴸ │ 42 │ [] │
│ Hello, World! │ Hello, World! │ ᴺᵁᴸᴸ │ [] │
│ [1,2,3] │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [1,2,3] │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘
```
## variantType
自 v24.2.0 起引入
返回 `Variant` 列中每一行的 Variant 类型名称。如果该行为 NULL，则返回 'None'。
**语法**
```sql theme={null}
variantType(variant)
```
**参数**
* `variant` — Variant 列。[`Variant`](/zh/reference/data-types/variant)
**返回值**
返回一个 Enum 列，表示每一行的 Variant 类型名称。[`Enum`](/zh/reference/data-types/enum)
**示例**
**用法示例**
```sql title=Query theme={null}
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;
```
```response title=Response theme={null}
┌─variantType(v)─┐
│ None │
│ UInt64 │
│ String │
│ Array(UInt64) │
└────────────────┘
```
## version
引入版本：v1.1.0
以字符串形式返回 ClickHouse 的当前版本，格式为：`major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release`。
如果在分布式表的上下文中执行，此函数会生成一个普通列，其值对应各个分片。
否则，它会生成一个常量值。
**语法**
```sql theme={null}
version()
```
**参数**
* 无。
**返回值**
返回当前的 ClickHouse 版本。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT version()
```
```response title=Response theme={null}
┌─version()─┐
│ 24.2.1.1 │
└───────────┘
```
## visibleWidth
引入版本：v1.1.0
计算以文本格式 (制表符分隔) 将值输出到控制台时的大致宽度。
系统使用该函数来实现 Pretty formats。
在 Pretty formats 中，`NULL` 表示为与 `NULL` 对应的字符串。
**语法**
```sql theme={null}
visibleWidth(x)
```
**参数**
* `x` — 任意数据类型的值。[`Any`](/zh/reference/data-types)
**返回值**
返回该值以文本格式显示时的近似宽度。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**计算 NULL 的可见宽度**
```sql title=Query theme={null}
SELECT visibleWidth(NULL)
```
```response title=Response theme={null}
┌─visibleWidth(NULL)─┐
│ 4 │
└────────────────────┘
```
## zookeeperSessionUptime
引入版本：v21.11.0
返回当前 ZooKeeper 会话的运行时间 (以秒为单位) 。
**语法**
```sql theme={null}
zookeeperSessionUptime()
```
**参数**
* 无。
**返回值**
返回当前 ZooKeeper 会话的运行时间 (以秒为单位) 。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT zookeeperSessionUptime();
```
```response title=Response theme={null}
┌─zookeeperSessionUptime()─┐
│ 286 │
└──────────────────────────┘
```