其他函数

注意

以下函数文档是从 system.functions 系统表中生成的。

FQDN

自 v20.1 版本起引入

返回 ClickHouse 服务器的完全限定域名（FQDN）。

语法

fqdn()

别名：fullHostName

参数

无。

返回值

返回 ClickHouse 服务器的完全限定域名。String

示例

使用示例

SELECT fqdn()

┌─FQDN()──────────────────────────┐
│ clickhouse.us-east-2.internal │
└─────────────────────────────────┘

MACNumToString

自 v1.1 起提供

将一个 UInt64 数字按大端格式解释为 MAC 地址。以字符串形式返回对应的 MAC 地址，格式为 AA:BB:CC:DD:EE:FF（用冒号分隔的十六进制数字）。

语法

MACNumToString(num)

参数

num — UInt64 类型的数值。UInt64

返回值

返回格式为 AA:BB:CC:DD:EE:FF 的 MAC 地址字符串。String

示例

用法示例

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:00:11:22:33:44 │
└───────────────────┘

MACStringToNum

自 v1.1 版本引入

MACNumToString 的逆函数。如果 MAC 地址格式无效，则返回 0。

语法

MACStringToNum(s)

参数

s — MAC 地址字符串。String

返回值

返回一个 UInt64 整数值。UInt64

示例

使用示例

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

1108152157446

MACStringToOUI

引入版本：v1.1

给定一个格式为 AA:BB:CC:DD:EE:FF（以冒号分隔的十六进制数）的 MAC 地址，返回其前三个字节，作为一个 UInt64 值。如果 MAC 地址格式无效，则返回 0。

语法

MACStringToOUI(s)

参数

s — MAC 地址字符串。String

返回值

以 UInt64 数值返回前三个八位字节。UInt64

示例

用法示例

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

__applyFilter

引入于：v25.10

用于 JOIN 运行时过滤的特殊函数。

语法

__applyFilter(filter_name, key)

参数

filter_name — 运行时过滤器的内部名称，由 BuildRuntimeFilterStep 构建。String
key — 任意类型的值，用于检查其是否存在于过滤器中

返回值

如果应当过滤该 key，则返回 False Bool

示例

此函数不应在用户查询中使用。在优化过程中,它可能会被添加到查询计划中。

__patchPartitionID

引入版本：v25.5

内部函数。接受一个 part 的名称以及 patch part 的列名哈希值，返回该 patch part 的分区名称。参数必须是合法的 part 名称，否则行为未定义。

语法

参数

无。

返回值

示例

authenticatedUser

引入版本：v25.11

如果使用 EXECUTE AS 命令切换了会话用户，此函数返回用于身份验证并创建会话的原始用户的名称。别名：authUser()

语法

authenticatedUser()

别名：authUser

参数

无。

返回值

已认证用户的名称。String

示例

使用示例

EXECUTE as u1;
            SELECT currentUser(), authenticatedUser();

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

bar

引入版本：v1.1

构建一个柱状图。绘制一条条带，其宽度与 (x - min) 成正比，当 x = max 时其宽度等于 width 个字符。该条带的绘制精度可细化到单个符号的八分之一。

语法

bar(x, min, max[, width])

参数

x — 要显示的数值。(U)Int* 或 Float* 或 Decimal
min — 最小值。(U)Int* 或 Float* 或 Decimal
max — 最大值。(U)Int* 或 Float* 或 Decimal
width — 可选。条形的字符宽度。默认值为 80。const (U)Int* 或 const Float* 或 const Decimal

返回值

返回一个基于 Unicode 的条形字符串。String

示例

使用示例

SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600000, 20) AS bar
FROM test.hits
GROUP BY h
ORDER BY h ASC

┌──h─┬──────c─┬─bar────────────────┐
│  0 │ 292907 │ █████████▋         │
│  1 │ 180563 │ ██████             │
│  2 │ 114861 │ ███▋               │
│  3 │  85069 │ ██▋                │
│  4 │  68543 │ ██▎                │
│  5 │  78116 │ ██▌                │
│  6 │ 113474 │ ███▋               │
│  7 │ 170678 │ █████▋             │
│  8 │ 278380 │ █████████▎         │
│  9 │ 391053 │ █████████████      │
│ 10 │ 457681 │ ███████████████▎   │
│ 11 │ 493667 │ ████████████████▍  │
│ 12 │ 509641 │ ████████████████▊  │
│ 13 │ 522947 │ █████████████████▍ │
│ 14 │ 539954 │ █████████████████▊ │
│ 15 │ 528460 │ █████████████████▌ │
│ 16 │ 539201 │ █████████████████▊ │
│ 17 │ 523539 │ █████████████████▍ │
│ 18 │ 506467 │ ████████████████▊  │
│ 19 │ 520915 │ █████████████████▎ │
│ 20 │ 521665 │ █████████████████▍ │
│ 21 │ 542078 │ ██████████████████ │
│ 22 │ 493642 │ ████████████████▍  │
│ 23 │ 400397 │ █████████████▎     │
└────┴────────┴────────────────────┘

blockNumber

引入自：v1.1

返回包含该行的块的单调递增序列号。返回的块号基于尽力保证原则进行更新，因此可能并不完全精确。

语法

blockNumber()

参数

无。

返回值

该行所在数据块的序列号。UInt64

示例

基本用法

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

┌─blockNumber()─┐
│             7 │
│             7 │
└───────────────┘
┌─blockNumber()─┐
│             8 │
│             8 │
└───────────────┘
┌─blockNumber()─┐
│             9 │
│             9 │
└───────────────┘
┌─blockNumber()─┐
│            10 │
│            10 │
└───────────────┘
┌─blockNumber()─┐
│            11 │
│            11 │
└───────────────┘

blockSerializedSize

引入版本：v20.3

返回磁盘上一个值块未压缩时的大小（字节）。

语法

blockSerializedSize(x1[, x2[, ...]])

参数

x1[, x2, ...] — 任意数量的参数值，用于获取其所在数据块在未压缩时的大小。Any

返回值

返回在不进行压缩时，包含这些值的数据块写入磁盘的字节数。UInt64

示例

用法示例

SELECT blockSerializedSize(maxState(1)) AS x;

┌─x─┐
│ 2 │
└───┘

blockSize

引入于：v1.1

在 ClickHouse 中，查询是按块（block）进行处理的。此函数返回调用该函数所在块的大小（行数）。

语法

blockSize()

参数

无。

返回值

返回当前块中的行数。UInt64

示例

用法示例

SELECT blockSize()
FROM system.numbers LIMIT 5

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

buildId

引入版本：v20.5

返回编译器为当前运行的 ClickHouse 服务器二进制文件生成的构建 ID。如果在分布式表的上下文中执行，该函数会生成一个普通列，包含每个分片对应的值。否则，它会返回一个常量值。

语法

buildId()

参数

无。

返回值

返回构建 ID。String

示例

使用示例

SELECT buildId()

┌─buildId()────────────────────────────────┐
│ AB668BEF095FAA6BD26537F197AC2AF48A927FB4 │
└──────────────────────────────────────────┘

byteSize

引入版本：v21.1

返回其参数在内存中未压缩字节大小的估计值。对于 String 参数，该函数返回字符串长度 + 8（长度）。如果函数有多个参数，则会累加它们的字节大小。

语法

byteSize(arg1[, arg2, ...])

参数

arg1[, arg2, ...] — 需要估算未压缩字节大小的任意数据类型的值。Any

返回值

返回参数在内存中字节大小的估算值。UInt64

示例

使用示例

SELECT byteSize('string')

┌─byteSize('string')─┐
│                 15 │
└────────────────────┘

多个参数

SELECT byteSize(NULL, 1, 0.3, '')

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         19 │
└────────────────────────────┘

catboostEvaluate

引入于：v22.9

评估外部 catboost 模型。CatBoost 是由 Yandex 开发的开源梯度提升机器学习库。接受 catboost 模型文件路径以及模型参数（特征）作为输入。

前置条件

构建 catboost 评估库

在评估 catboost 模型之前，必须先准备好 libcatboostmodel.<so|dylib> 库。关于如何编译该库，请参阅 CatBoost 文档。

接下来，在 ClickHouse 配置中指定 libcatboostmodel.<so|dylib> 的路径：

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

出于安全和隔离方面的考虑，模型评估不会在服务器进程中运行，而是在 clickhouse-library-bridge 进程中运行。在首次执行 catboostEvaluate() 时，如果该库桥接进程尚未运行，服务器会启动该进程。两个进程通过 HTTP 接口进行通信。默认使用端口 9012。如果端口 9012 已被其他服务占用，可以按如下方式指定其他端口。

<library_bridge>
    <port>9019</port>
</library_bridge>

使用 libcatboost 训练 CatBoost 模型

有关如何使用训练数据集来训练 CatBoost 模型，请参见 Training and applying models。

语法

catboostEvaluate(path_to_model, feature_1[, feature_2, ..., feature_n])

参数

path_to_model — CatBoost 模型的路径。const String
feature — 一个或多个模型特征/参数。Float*

返回值

返回模型评估结果。Float64

示例

catboostEvaluate

SELECT catboostEvaluate('/root/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

4.695691092573497

colorOKLCHToSRGB

引入于：v25.7

将 OKLCH 感知颜色空间中的颜色转换为常见的 sRGB 颜色空间。

如果 L 超出 [0...1] 范围、C 为负数，或 H 超出 [0...360] 范围，则结果由具体实现定义。

注意

OKLCH 是 OKLab 颜色空间的圆柱坐标版本。它的三个坐标分别是 L（亮度，范围为 [0...1]）、C（色度 >= 0）以及 H（色相，以度为单位，范围为 [0...360]）。 OKLab/OKLCH 的设计目标是在计算成本较低的前提下实现感知上的均匀性。

该转换是 colorSRGBToOKLCH 的逆运算：

OKLCH 到 OKLab。
OKLab 到线性 sRGB。
线性 sRGB 到 sRGB。

第二个参数 gamma 会在最后一个阶段使用。

关于 OKLCH 空间中的颜色参考，以及它们与 sRGB 颜色的对应关系，请参见 https://oklch.com/。

语法

colorOKLCHToSRGB(tuple [, gamma])

参数

tuple — 一个包含三个数值 L、C、H 的元组，其中 L 的取值范围为 [0...1]，C >= 0，H 的取值范围为 [0...360]。Tuple(Float64, Float64, Float64)
gamma — 可选。用于将线性 sRGB 转换回 sRGB 的指数，对每个通道 x 应用 (x ^ (1 / gamma)) * 255。默认值为 2.2。Float64

返回值

返回一个表示 sRGB 颜色值的元组 (R, G, B)。Tuple(Float64, Float64, Float64)

示例

将 OKLCH 转换为 sRGB

SELECT colorOKLCHToSRGB((0.4466, 0.0991, 45.44), 2.2) AS rgb
WITH colorOKLCHToSRGB((0.7, 0.1, 54)) as t SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB

┌─rgb──────────────────────────────────────────────────────┐
│ (127.03349738778945,66.06672044472008,37.11802592155851) │
└──────────────────────────────────────────────────────────┘
┌─RGB──────────┐
│ (205,139,97) │
└──────────────┘

colorSRGBToOKLCH

引入版本：v25.7

将编码在 sRGB 颜色空间中的颜色转换为感知均匀的 OKLCH 颜色空间。

如果任一输入通道超出 [0...255] 范围，或 gamma 值为非正数，其行为由具体实现定义。

注意

OKLCH 是 OKLab 颜色空间的圆柱坐标版本。它的三个坐标分别是 L（亮度，范围为 [0...1]）、C（色度，>= 0）和 H（色相，单位为度，范围为 [0...360]）。 OKLab/OKLCH 被设计为在保持计算开销较低的同时尽可能做到感知均匀。

转换包括三个阶段：

sRGB 到线性 sRGB
线性 sRGB 到 OKLab
OKLab 到 OKLCH。

关于 OKLCH 空间中的颜色参考，以及它们与 sRGB 颜色之间的对应关系，请参见 https://OKLCH.com/。

语法

colorSRGBToOKLCH(tuple[, gamma])

参数

tuple — 一个由 R、G、B 三个通道值组成的元组，每个通道取值范围为 [0...255]。Tuple(UInt8, UInt8, UInt8)
gamma — 可选。用于将 sRGB 线性化的指数，通过对每个通道 x 应用 (x / 255)^gamma 实现。默认值为 2.2。Float64

返回值

返回一个表示 OKLCH 颜色空间值的元组 (L, C, H)。Tuple(Float64, Float64, Float64)

示例

将 sRGB 转换为 OKLCH

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch

┌─lch─────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.10442699545678624,45.907345481930236) │
└─────────────────────────────────────────────────────────────┘

connectionId

引入版本：v21.3

返回提交当前查询的客户端的连接 ID。此函数在调试场景中最有用。它是为与 MySQL 的 CONNECTION_ID 函数兼容而创建的。它通常不会在生产环境中的查询中使用。

语法

connectionId()

参数

无。

返回值

返回当前客户端的连接 ID。UInt64

示例

使用示例

SELECT connectionId();

┌─connectionId()─┐
│              0 │
└────────────────┘

countDigits

引入版本：v20.8

返回表示一个值所需的十进制数字个数。

注意

该函数会考虑十进制数值的 scale，也就是说，它是在底层整数类型（即 (value * scale)）上计算结果的。

例如：

countDigits(42) = 2
countDigits(42.000) = 5
countDigits(0.04200) = 4

提示

你可以使用 countDigits(x) > 18 来检查 Decimal64 是否溢出，尽管这比 isDecimalOverflow 要慢。

语法

countDigits(x)

参数

x — 一个整数或小数。(U)Int* 或 Decimal

返回值

返回表示 x 所需的位数。UInt8

示例

用法示例

SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
       countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
       countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));

┌─countDigits(toDecimal32(1, 9))─┬─countDigits(toDecimal32(-1, 9))─┬─countDigits(toDecimal64(1, 18))─┬─countDigits(toDecimal64(-1, 18))─┬─countDigits(toDecimal128(1, 38))─┬─countDigits(toDecimal128(-1, 38))─┐
│                             10 │                              10 │                              19 │                               19 │                               39 │                                39 │
└────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

currentDatabase

自 v1.1 引入

返回当前数据库的名称。在需要在 CREATE TABLE 查询的表引擎参数中指定数据库时非常有用。

另请参阅 SET 语句。

语法

currentDatabase()

别名: current_database, SCHEMA, DATABASE

参数

无。

返回值

返回当前数据库的名称。String

示例

使用示例

SELECT currentDatabase()

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

currentProfiles

引入版本：v21.9

返回一个数组，包含当前用户的设置配置集。

语法

currentProfiles()

参数

无。

返回值

返回当前用户的设置配置文件数组。Array(String)

示例

使用示例

SELECT currentProfiles();

┌─currentProfiles()─────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics'] │
└───────────────────────────────────────────────┘

currentQueryID

自 v 版本起引入。

返回当前查询 ID。

语法

currentQueryID()

别名: current_query_id

参数

无。

返回值

示例

SELECT currentQueryID();

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

currentRoles

自 v21.9 起引入

返回一个数组，包含当前用户被授予的所有角色。

语法

currentRoles()

参数

无。

返回值

返回一个 Array(String) 类型的数组，其中包含分配给当前用户的所有角色。Array(String)

示例

使用示例

SELECT currentRoles();

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:[email protected]'] │
└────────────────────────────────────────────────┘

currentSchemas

自 v23.7 引入

与函数 currentDatabase 相同，但是

接受一个会被忽略的布尔参数
以只包含一个值的数组形式返回数据库名称。

函数 currentSchemas 仅为与 PostgreSQL 兼容而存在。请改用 currentDatabase。

另请参阅 SET 语句。

语法

currentSchemas(bool)

别名：current_schemas

参数

bool — 一个布尔值，会被忽略。Bool

返回值

返回一个仅包含当前数据库名称的、只含一个元素的数组。Array(String)

示例

用法示例

SELECT currentSchemas(true)

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

currentUser

自 v20.1 引入

返回当前用户的名称。
在分布式查询中，返回发起该查询的用户的名称。

语法

currentUser()

别名: current_user, user

参数

无。

返回值

返回当前用户的名称；否则返回发起该查询的用户的登录名。String

示例

用法示例

SELECT currentUser()

┌─currentUser()─┐
│ default       │
└───────────────┘

defaultProfiles

引入版本：v21.9

返回当前用户默认设置配置文件名称的数组。

语法

defaultProfiles()

参数

无。

返回值

返回当前用户的默认设置配置文件名数组。Array(String)

示例

用法示例

SELECT defaultProfiles();

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

defaultRoles

于 v21.9 引入

返回当前用户的默认角色数组。

语法

defaultRoles()

参数

无。

返回值

返回当前用户的默认角色构成的数组。Array(String)

示例

使用示例

SELECT defaultRoles();

┌─defaultRoles()─────────────────────────────────┐
│ ['sql-console-role:[email protected]'] │
└────────────────────────────────────────────────┘

defaultValueOfArgumentType

自 v1.1 起提供

返回指定数据类型的默认值。不包括用户为自定义列设置的默认值。

语法

defaultValueOfArgumentType(expression)

参数

expression — 任意类型的值，或计算结果为任意类型的表达式。Any

返回值

对于数值返回 0，对于字符串返回空字符串，对于 Nullable 类型返回 NULL。返回类型为 UInt8 或 String 或 NULL

示例

使用示例

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

Nullable 示例

SELECT defaultValueOfArgumentType(CAST(1 AS Nullable(Int8)));

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

defaultValueOfTypeName

自 v1.1 起引入

返回指定类型名称的默认值。

语法

defaultValueOfTypeName(type)

参数

type — 表示类型名的字符串。String

返回值

返回给定类型名的默认值：数字类型为 0，字符串类型为空字符串，而 Nullable UInt8、String 或 NULL 的值为 NULL。

示例

用法示例

SELECT defaultValueOfTypeName('Int8');

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

Nullable 示例

SELECT defaultValueOfTypeName('Nullable(Int8)');

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

displayName

引入于：v22.11

返回 config 中 display_name 的值；如果未设置该参数，则返回服务器的完全限定域名（FQDN）。

语法

displayName()

参数

无。

返回值

返回配置中的 display_name 值，如果未设置则返回服务器的 FQDN（完全限定域名）。String

示例

用法示例

SELECT displayName();

┌─displayName()─┐
│ production    │
└───────────────┘

dumpColumnStructure

自 v1.1 起引入

输出列及其数据类型内部结构的详细说明。

语法

dumpColumnStructure(x)

参数

x — 需要获取其描述的值。Any

返回值

返回用于表示该值的列结构的描述。String

示例

用法示例

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'));

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

enabledProfiles

引入版本：v21.9

返回一个包含当前用户已启用的设置配置文件名称的数组。

语法

enabledProfiles()

参数

无。

返回值

返回一个数组，包含为当前用户启用的设置配置文件（setting profile）的名称。Array(String)

示例

使用示例

SELECT enabledProfiles();

┌─enabledProfiles()─────────────────────────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics', 'batch_processing'] │
└───────────────────────────────────────────────────────────────────┘

enabledRoles

自 v21.9 引入

返回一个数组，包含当前用户已启用的角色。

语法

enabledRoles()

参数

无。

返回值

返回由当前用户已启用的角色名称组成的数组。Array(String)

示例

使用示例

SELECT enabledRoles();

┌─enabledRoles()─────────────────────────────────────────────────┐
│ ['general_data', 'sql-console-role:[email protected]'] │
└────────────────────────────────────────────────────────────────┘

errorCodeToName

引入版本：v20.12

返回 ClickHouse 数值错误码对应的文本名称。
数值错误码到错误名称的映射可在此处查看。

语法

errorCodeToName(error_code)

参数

error_code — ClickHouse 错误代码。(U)Int* 或 Float* 或 Decimal

返回值

返回 error_code 的文本名称。String

示例

用法示例

SELECT errorCodeToName(252);

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

file

自 v21.3 版本引入

以字符串形式读取文件内容，并将数据加载到指定的列中。文件内容不会被解释。

另请参阅 file 表函数。

语法

file(path[, default])

参数

path — 文件在 user_files_path 下的相对路径。支持通配符 *、**、?、{abc,def} 和 {N..M}，其中 N、M 为数字，'abc'、'def' 为字符串。String
default — 当文件不存在或无法访问时返回的值。String 或 NULL

返回值

以字符串形式返回文件内容。String

示例

将文件内容插入表中

INSERT INTO table SELECT file('a.txt'), file('b.txt');

filesystemAvailable

引入版本：v20.1

返回用于持久化数据库数据的文件系统中可用的空闲空间大小。返回值始终小于文件系统的总可用空间（filesystemUnreserved），因为一部分空间被预留给操作系统。

语法

filesystemAvailable([disk_name])

参数

disk_name — 可选。要查询可用空间的磁盘名称。如果省略，则使用默认磁盘。String 或 FixedString

返回值

返回剩余可用空间的字节数。UInt64

示例

使用示例

SELECT formatReadableSize(filesystemAvailable()) AS "可用空间";

┌─可用空间─┐
│ 30.75 GiB       │
└─────────────────┘

filesystemCapacity

自 v20.1 引入

以字节为单位返回文件系统的容量。
需要配置数据目录的 path。

语法

filesystemCapacity([disk_name])

参数

disk_name — 可选。要查询容量的磁盘名称。如果省略，则使用默认磁盘。String 或 FixedString

返回值

返回文件系统的容量（以字节为单位）。UInt64

示例

用法示例

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

filesystemUnreserved

引入自：v22.12

返回承载数据库持久化数据的文件系统上的总空闲空间（之前为 filesystemFree）。另请参阅 filesystemAvailable。

语法

filesystemUnreserved([disk_name])

参数

disk_name — 可选。要查询其可用空间总量的磁盘名称。若省略，则使用默认磁盘。String 或 FixedString

返回值

返回以字节为单位的可用空间大小。UInt64

示例

使用示例

SELECT formatReadableSize(filesystemUnreserved()) AS "可用空间";

┌─可用空间─┐
│ 32.39 GiB  │
└──────────┘

finalizeAggregation

引入于：v1.1

给定一个聚合状态时，此函数返回聚合结果（在使用 -State 组合器时则返回最终状态）。

语法

finalizeAggregation(state)

参数

state — 聚合状态。AggregateFunction

返回值

返回聚合的最终结果。Any

示例

使用示例

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

┌─finalizeAggregation(arrayReduce('maxState', [1, 2, 3]))─┐
│                                                       3 │
└─────────────────────────────────────────────────────────┘

与 initializeAggregation 一起使用

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);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

flipCoordinates

自 v25.10 版本引入

对 Point、Ring、Polygon 或 MultiPolygon 的坐标进行翻转。对于 Point，会交换其坐标值。对于数组，会对每个坐标对递归应用相同的变换。

语法

flipCoordinates(geometry)

参数

geometry — 要转换的几何对象。支持的类型：Point (Tuple(Float64, Float64))、Ring (Array(Point))、Polygon (Array(Ring))、MultiPolygon (Array(Polygon))。

返回值

坐标被翻转后的几何对象。类型与输入相同。Point 或 Ring 或 Polygon 或 MultiPolygon

示例

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2.0, 1.0)

ring（环）

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

[(2.0, 1.0), (4.0, 3.0)]

多边形

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

[[(2.0, 1.0), (4.0, 3.0)], [(6.0, 5.0), (8.0, 7.0)]]

formatQuery

引入版本：v

返回给定 SQL 查询的格式化结果，可能为多行。若发生解析错误则抛出异常。 [example:multiline]

语法

formatQuery(query)

参数

query — 要格式化的 SQL 查询。String

返回值

格式化后的查询 String

示例

multiline

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

formatQueryOrNull

引入于：v

返回给定 SQL 查询的格式化版本，可能为多行格式。若解析出错，则返回 NULL。 [example:multiline]

语法

formatQueryOrNull(query)

参数

query — 要格式化的 SQL 查询。String

返回值

格式化后的 SQL 查询 String

示例

多行

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

formatQuerySingleLine

引入版本：v

与 formatQuery() 类似，但返回的格式化字符串不包含换行符。解析出错时将抛出异常。 [example:multiline]

语法

formatQuerySingleLine(query)

参数

query — 要格式化的 SQL 查询。String

返回值

格式化后的查询 String

示例

multiline

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatQuerySingleLineOrNull

引入版本：v

与 formatQuery() 类似，但返回的格式化字符串不包含换行符。在发生解析错误时返回 NULL。 [example:multiline]

语法

formatQuerySingleLineOrNull(query)

参数

query — 要进行格式化的 SQL 查询。String

返回值

格式化后的查询字符串 String

示例

多行

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatReadableDecimalSize

引入版本：v22.11

给定一个大小（以字节数表示），此函数返回一个带有后缀（KB、MB 等）的可读性更好的、四舍五入后的大小字符串。

此函数的反向操作为 parseReadableSize。

语法

formatReadableDecimalSize(x)

参数

x — 以字节为单位的大小。UInt64

返回值

返回经过四舍五入、带有后缀的人类可读大小字符串。String

示例

格式化文件大小

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.02 KB    │
│        1048576 │ 1.05 MB    │
│      192851925 │ 192.85 MB  │
└────────────────┴────────────┘

formatReadableQuantity

引入版本：v20.10

给定一个数字，此函数返回一个经过四舍五入并带有后缀（千、百万、十亿等）的字符串。

该函数接受任意数值类型作为输入，但在内部会将其转换为 Float64。对于非常大的数值，结果可能不够理想。

语法

formatReadableQuantity(x)

参数

x — 要格式化的数字。UInt64

返回值

返回一个带有后缀的四舍五入数字，类型为字符串。String

示例

将数字格式化为带后缀的形式

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 千           │
│        1234000 │ 1.23 百万         │
│     4567000000 │ 4.57 十亿         │
│ 98765432101234 │ 98.77 万亿        │
└────────────────┴───────────────────┘

formatReadableSize

引入于：v1.1

给定一个表示大小的值（字节数），此函数返回带有后缀（KiB、MiB 等）的可读、四舍五入后的大小字符串。

执行与之相反操作的函数为 parseReadableSize、parseReadableSizeOrZero 和 parseReadableSizeOrNull。该函数接受任意数值类型作为输入，但在内部会将其转换为 Float64。对于非常大的数值，结果可能不够理想。

语法

formatReadableSize(x)

别名：FORMAT_BYTES

参数

x — 以字节为单位的大小。UInt64

返回值

返回带有后缀的人类可读、四舍五入后的大小字符串。String

示例

格式化文件大小

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

formatReadableTimeDelta

引入版本：v20.12

给定一个以秒为单位的时间间隔（delta），此函数返回一个包含年/月/日/时/分/秒/毫秒/微秒/纳秒的可读时间间隔字符串。

该函数接受任意数值类型作为输入，但在内部会将其转换为 Float64。对于非常大的数值，结果可能不是最优的。

语法

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

参数

column — 包含数值时间差的列。Float64
maximum_unit — 可选。要显示的最大时间单位。可接受的取值：nanoseconds、microseconds、milliseconds、seconds、minutes、hours、days、months、years。默认值：years。const String
minimum_unit — 可选。要显示的最小时间单位。所有更小的单位都会被截断。可接受的取值：nanoseconds、microseconds、milliseconds、seconds、minutes、hours、days、months、years。如果显式指定的值大于 maximum_unit，将抛出异常。默认值：如果 maximum_unit 为 seconds 或更大，则为 seconds，否则为 nanoseconds。const String

返回值

以字符串形式返回时间差。String

示例

用法示例

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1分40秒                                        │
│      12345 │ 3小时25分45秒                             │
│  432546534 │ 13年8个月17天7小时48分54秒│
└────────────┴────────────────────────────────────────────────────────────────┘

采用最大单位

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1分40秒                                                          │
│      12345 │ 205分45秒                                                        │
│  432546534 │ 7209108分54秒                                                    │
└────────────┴─────────────────────────────────────────────────────────────────┘

generateRandomStructure

引入版本：v23.5

生成格式为 column1_name column1_type, column2_name column2_type, ... 的随机表结构。

语法

generateRandomStructure([number_of_columns, seed])

参数

number_of_columns — 结果表结构中期望的列数。如果设置为 0 或 Null，则列数将在 1 到 128 之间随机选择。默认值：Null。UInt64
seed — 用于生成稳定结果的随机种子。如果未指定 seed 或将其设置为 Null，则会随机生成该值。UInt64

返回值

随机生成的表结构。String

示例

用法示例

SELECT generateRandomStructure()

c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime

具有指定列数

SELECT generateRandomStructure(1)

c1 Map(UInt256, UInt16)

使用指定的随机种子

SELECT generateRandomStructure(NULL, 33)

c1 DateTime, c2 Enum8('c2V0' = 0, 'c2V1' = 1, 'c2V2' = 2, 'c2V3' = 3), c3 LowCardinality(Nullable(FixedString(30))), c4 Int16, c5 Enum8('c5V0' = 0, 'c5V1' = 1, 'c5V2' = 2, 'c5V3' = 3), c6 Nullable(UInt8), c7 String, c8 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(70)))

generateSerialID

引入版本：v25.1

生成并返回从前一个计数器值开始的连续数字。该函数接受一个字符串参数——序列标识符，以及一个可选的起始值。服务器需要配置 Keeper。序列存储在 Keeper 节点下的路径中，该路径可以在服务器配置中的 series_keeper_path 进行配置。

语法

generateSerialID(series_identifier[, start_value])

参数

series_identifier — 序列标识符 const String
start_value — 可选。计数器的起始值。默认为 0。注意：该值仅在创建新序列时生效，如果序列已存在则会被忽略 UInt*

返回值

返回从计数器上一次取值开始递增的数字序列。UInt64

示例

首次调用

SELECT generateSerialID('id1')

┌─generateSerialID('id1')──┐
│                        1 │
└──────────────────────────┘

第二次调用

SELECT generateSerialID('id1')

┌─generateSerialID('id1')──┐
│                        2 │
└──────────────────────────┘

列调用

SELECT *, generateSerialID('id1') FROM test_table

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')──┐
│         1 │      3 │   3 │                        3 │
│         1 │      1 │   1 │                        4 │
│         1 │      2 │   2 │                        5 │
│         1 │      5 │   5 │                        6 │
│         1 │      4 │   4 │                        7 │
└───────────┴────────┴─────┴──────────────────────────┘

包含起始值

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)──┐
│                           100 │
└───────────────────────────────┘

带有 start 值的第二次调用

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)──┐
│                           101 │
└───────────────────────────────┘

getClientHTTPHeader

引入于：v24.5

获取指定 HTTP 头部的值。如果该头部不存在，或者当前请求不是通过 HTTP 接口执行的，函数会返回空字符串。某些 HTTP 头部（例如 Authentication 和 X-ClickHouse-*）是受限制的。

注意

必须设置 allow_get_client_http_header

该函数要求启用 allow_get_client_http_header 设置。出于安全原因，该设置默认未启用，因为某些头部（例如 Cookie）可能包含敏感信息。

对于该函数，HTTP 头部是区分大小写的。如果在分布式查询上下文中使用该函数，它只会在发起查询的节点返回非空结果。

语法

getClientHTTPHeader(name)

参数

name — HTTP 头部名称。String

返回值

返回该头部的值。String

示例

使用示例

SELECT getClientHTTPHeader('Content-Type');

┌─getClientHTTPHeader('Content-Type')─┐
│ application/x-www-form-urlencoded   │
└─────────────────────────────────────┘

getMacro

引入版本：v20.1

返回服务器配置文件中某个宏的值。宏在配置文件的 <macros> 部分中定义，即使主机名很复杂，也可以用更便捷的名称来区分不同服务器。如果在分布式表的上下文中执行该函数，则会生成一个普通列，其中的值对应于各个分片。

语法

getMacro(name)

参数

name — 要获取的宏名称。const String

返回值

返回指定宏的值。String

示例

基本用法

SELECT getMacro('test');

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

getMaxTableNameLengthForDatabase

引入版本：v

返回指定数据库中表名允许的最大长度。

语法

getMaxTableNameLengthForDatabase(database_name)

参数

database_name — 指定数据库的名称。String

返回值

返回表名允许的最大长度，类型为 Integer。

示例

典型示例

SELECT getMaxTableNameLengthForDatabase('default');

┌─getMaxTableNameLengthForDatabase('default')─┐
            │                                         206 │
            └─────────────────────────────────────────────┘

getMergeTreeSetting

引入版本：v25.6

返回当前 MergeTree 设置的值。

语法

getMergeTreeSetting(setting_name)

参数

setting_name — 设置名称。String

返回值

返回 MergeTree 设置的当前值。

示例

使用示例

SELECT getMergeTreeSetting('index_granularity');

┌─getMergeTreeSetting('index_granularity')─┐
│                                     8192 │
└──────────────────────────────────────────┘

getOSKernelVersion

自 v21.11 起引入

返回表示 OS 内核版本的字符串。

语法

getOSKernelVersion()

参数

无。

返回值

返回当前操作系统的内核版本。String

示例

使用示例

SELECT getOSKernelVersion();

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

getServerPort

引入于：v21.10

返回指定协议的服务器端口号。

语法

getServerPort(port_name)

参数

port_name — 端口名。String

返回值

返回服务器端口号。UInt16

示例

用法示例

SELECT getServerPort('tcp_port');

┌─getServerPort('tcp_port')─┐
│                      9000 │
└───────────────────────────┘

getServerSetting

引入于：v25.6

根据给定的服务器 SETTING 名称返回当前已设置的值。

语法

getServerSetting(setting_name')

参数

setting_name — 服务器设置的名称。String

返回值

返回该服务器设置的当前值。Any

示例

用法示例

SELECT getServerSetting('allow_use_jemalloc_memory');

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

getSetting

引入版本：v20.7

返回指定设置的当前值。

语法

getSetting(setting_name)

参数

setting_Name — 设置名称。const String

返回值

返回该设置的当前值。Any

示例

用法示例

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

┌─getSetting('⋯_analyzer')─┐
│ true                     │
└──────────────────────────┘
┌─getSetting('⋯_analyzer')─┐
│ false                    │
└──────────────────────────┘

getSettingOrDefault

引入版本：v24.10

返回当前 setting 的值；如果在当前 profile 中未配置该 setting，则返回第二个参数中指定的默认值。

语法

getSettingOrDefault(setting_name, default_value)

参数

setting_name — 设置名称。String
default_value — 当未设置 custom_setting 时要返回的值。该值可以是任意数据类型或 Null。

返回值

返回指定设置的当前值；如果该设置未设置，则返回 default_value。

示例

使用示例

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

my_value
100
NULL

getSizeOfEnumType

自 v1.1 引入

返回给定 Enum 类型中枚举成员的数量。

语法

getSizeOfEnumType(x)

参数

x — Enum 类型的值。Enum

返回值

返回 Enum 类型输入值的字段数量。UInt8/16

示例

使用示例

SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;

┌─x─┐
│ 2 │
└───┘

getSubcolumn

引入于：v

接收一个表达式或标识符，以及一个包含子列名的常量字符串。

返回从该表达式中提取出的所请求子列。

语法

参数

无。

返回值

示例

getSubcolumn

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')

getTypeSerializationStreams

引入于：v22.6

列出某个数据类型的序列化流路径。此函数仅供开发用途。

语法

getTypeSerializationStreams(col)

参数

col — 将从中检测数据类型的列，或表示该数据类型的字符串。Any

返回值

返回一个包含所有序列化子流路径的数组。Array(String)

示例

tuple

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))

['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

映射

SELECT getTypeSerializationStreams('Map(String, Int64)')

['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

globalVariable

自 v20.5 引入

接受一个常量字符串参数，并返回具有该名称的全局变量的值。此函数主要用于兼容 MySQL，在 ClickHouse 的正常运行中既非必需，也无实际用途。仅定义了少量虚拟的全局变量。

语法

globalVariable(name)

参数

name — 全局变量的名称。String

返回值

返回名为 name 的变量值。Any

示例

globalVariable

SELECT globalVariable('max_allowed_packet')

67108864

hasColumnInTable

自 v1.1 起提供

检查数据库表中是否存在指定列。对于嵌套数据结构中的元素，该函数会检查对应列是否存在。对于嵌套数据结构本身，该函数返回 0。

语法

hasColumnInTable([hostname[, username[, password]],]database, table, column)

参数

database — 数据库名称。const String
table — 表名。const String
column — 列名。const String
hostname — 可选。用于执行检查的远程服务器名称。const String
username — 可选。远程服务器的用户名。const String
password — 可选。远程服务器的密码。const String

返回值

如果指定的列存在，则返回 1，否则返回 0。UInt8

示例

检查已存在的列

SELECT hasColumnInTable('system','metrics','metric')

检查不存在的列

SELECT hasColumnInTable('system','metrics','non-existing_column')

hasThreadFuzzer

引入版本：v20.6

返回线程 fuzzer 当前是否已启用。此函数仅在测试和调试时有用。

语法

hasThreadFuzzer()

参数

无。

返回值

返回 Thread Fuzzer 是否启用。UInt8

示例

检查 Thread Fuzzer 状态

SELECT hasThreadFuzzer()

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

hostName

自 v20.5 起引入

返回执行此函数的主机名。如果函数在远程服务器上执行（分布式处理），则返回远程服务器的名称。如果函数在分布式表的上下文中执行，则会生成一个普通列，其中的值对应各个分片。否则，它会生成一个常量值。

语法

hostName()

别名: hostname

参数

无。

返回值

返回主机名。String

示例

用法示例

SELECT hostName()

┌─hostName()─┐
│ clickhouse │
└────────────┘

icebergBucket

自 v25.5 引入

实现了 Iceberg bucket transform 的逻辑。

语法

icebergBucket(N, value)

参数

N — 桶的数量，即取模基数。const (U)Int*
value — 要转换的源值。类型可以是 (U)Int*、Bool、Decimal、Float*、String、FixedString、UUID、Date、Time 或 DateTime

返回值

返回源值的 32 位哈希值。Int32

示例

SELECT icebergBucket(5, 1.0 :: Float32)

icebergTruncate

引入于：v25.3

实现 Iceberg 截断转换（truncate transform）的逻辑：https://iceberg.apache.org/spec/#truncate-transform-details。

语法

icebergTruncate(N, value)

参数

value — 要转换的值。String 或 (U)Int* 或 Decimal

返回值

与参数类型相同

示例

SELECT icebergTruncate(3, 'iceberg')

ice

identity

引入版本：v1.1

此函数返回传入的参数，本身对调试和测试非常有用。它允许你绕过索引的使用，从而观察全表扫描的性能。查询分析器在查找可用索引时，会忽略 identity 函数内部的任何内容，并且还会禁用常量折叠。

语法

identity(x)

参数

x — 输入值。Any

返回值

返回原始输入值。Any

示例

用法示例

SELECT identity(42)

ignore

自 v1.1 版本引入

接受任意参数并无条件返回 0。

语法

ignore(x)

参数

x — 仅用于避免语法错误而传入的输入值，本身不会被使用。Any

返回值

始终返回 0。UInt8

示例

用法示例

SELECT ignore(0, 'ClickHouse', NULL)

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

indexHint

引入版本：v1.1

此函数用于调试和内部分析。它会忽略其参数并始终返回 1。这些参数不会被求值。

但在进行索引分析时，假定该函数的参数没有被 indexHint 包裹。这允许根据相应条件在索引范围内选取数据，但不会再基于该条件执行后续过滤。 ClickHouse 中的索引是稀疏的，使用 indexHint 会比直接指定相同条件返回更多数据。

语法

indexHint(expression)

参数

expression — 用于索引范围选择的任意表达式。Expression

返回值

在所有情况下返回 1。UInt8

示例

带日期过滤的示例用法

SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

┌──────────k─┬─count()─┐
│ 2025-09-14 │    7071 │
│ 2025-09-15 │   16428 │
│ 2025-09-16 │    1077 │
│ 2025-09-30 │    8167 │
└────────────┴─────────┘

initialQueryID

引入版本：v1.1

返回当前初始查询的 ID。查询的其他参数可以从 system.query_log 中的 initial_query_id 字段中提取。

与 queryID 函数不同，initialQueryID 在不同分片上返回相同的结果。

语法

initialQueryID()

别名: initial_query_id

参数

无。

返回值

返回当前会话初始查询的 ID。String

示例

用法示例

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());

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initialQueryStartTime

自 v25.4 版本引入

返回初始查询的开始时间。 initialQueryStartTime 在不同分片上返回相同结果。

语法

initialQueryStartTime()

别名: initial_query_start_time

参数

无。

返回值

返回当前初始查询的开始时间。DateTime

示例

使用示例

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());

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initializeAggregation

引入于：v20.6

基于单个值计算聚合函数的结果。此函数可用于初始化带有组合器 -State 的聚合函数。可以创建聚合函数的状态并将其插入到类型为 AggregateFunction 的列中，或者将已初始化的聚合结果用作默认值。

语法

initializeAggregation(aggregate_function, arg1[, arg2, ...])

参数

aggregate_function — 要初始化的聚合函数名称。String
arg1[, arg2, ...] — 聚合函数的参数。Any

返回值

对传递给函数的每一行返回其聚合结果。返回类型与作为第一个参数传给 initializeAggregation 的函数的返回类型相同。Any

示例

使用 uniqState 的基本用法

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

与 sumState 和 finalizeAggregation 搭配使用

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

┌─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

返回其参数是否为常量表达式。常量表达式是在查询分析阶段（即执行之前）其结果就已知的表达式。例如，基于字面量的表达式就是常量表达式。此函数主要用于开发、调试和演示。

语法

isConstant(x)

参数

x — 待检查的表达式。Any

返回值

如果 x 是常量则返回 1，如果 x 不是常量则返回 0。UInt8

示例

常量表达式

SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

带函数的常量

WITH 3.14 AS pi
SELECT isConstant(cos(pi))

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

非常量表达式

SELECT isConstant(number)
FROM numbers(1)

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

now() 函数的行为

SELECT isConstant(now())

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

isDecimalOverflow

引入版本：v20.8

检查某个十进制数的位数是否超出限制，从而无法在指定精度的 Decimal 数据类型中正确存储。

语法

isDecimalOverflow(value[, precision])

参数

value — 要检查的 Decimal 值。Decimal
precision — 可选。Decimal 类型的精度。如果省略，则使用第一个参数的初始精度。UInt8

返回值

如果 Decimal 值的位数超过其精度允许的位数，则返回 1；如果 Decimal 值满足指定的精度，则返回 0。UInt8

示例

用法示例

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

┌─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 版本引入

允许你以与字典相同的方式从表中提取数据。使用指定的 join 键从 Join 表中获取数据。

注意

仅支持使用 ENGINE = Join(ANY, LEFT, <join_keys>) 语句创建的表。

语法

joinGet(join_storage_table_name, value_column, join_keys)

参数

join_storage_table_name — 指示在何处执行查找的标识符。该标识符会在默认数据库中进行查找（参见配置文件中的 default_database 参数）。要更改默认数据库，请使用 USE database_name 查询，或者通过点号指定数据库和表，例如 database_name.table_name。String
value_column — 表中包含所需数据的列名。const String
join_keys — 连接键的列表。Any

返回值

返回与键列表一一对应的值列表。Any

示例

用法示例

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));

┌─joinGet(db_test.id_val, 'val', toUInt32(1))─┐
│                                          11 │
└─────────────────────────────────────────────┘

在当前数据库中的表上使用

USE db_test;
SELECT joinGet(id_val, 'val', toUInt32(2));

┌─joinGet(id_val, 'val', toUInt32(2))─┐
│                                  12 │
└─────────────────────────────────────┘

使用数组作为 JOIN 键

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);

┌─joinGet(some_table, 'name', 1, 11)─┐
│ a                                  │
└────────────────────────────────────┘

joinGetOrNull

引入版本：v20.4

允许以与从字典中提取数据相同的方式，从表中提取数据。使用指定的 join 键从 Join 引擎表中获取数据。与 joinGet 不同，当键不存在时返回 NULL。

注意

仅支持通过 ENGINE = Join(ANY, LEFT, <join_keys>) 语句创建的表。

语法

joinGetOrNull(join_storage_table_name, value_column, join_keys)

参数

join_storage_table_name — 指示在哪个位置执行查找的标识符。该标识符会在默认数据库中进行查找（参见配置文件中的参数 default_database）。要覆盖默认数据库设置，请使用 USE database_name 查询，或者通过点号指定数据库和表，例如 database_name.table_name。String
value_column — 表中包含所需数据的列名。const String
join_keys — join 键的列表。Any

返回值

返回与键列表对应的值列表，如果找不到某个键，则返回 NULL。Any

示例

用法示例

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));

┌─joinGetOrNull(db_test.id_val, 'val', toUInt32(1))─┬─joinGetOrNull(db_test.id_val, 'val', toUInt32(999))─┐
│                                                11 │                                                ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

lowCardinalityIndices

引入版本：v18.12

返回 LowCardinality 列中某个值在字典中的位置。位置从 1 开始。由于 LowCardinality 列在每个分区片段上都有各自的字典，此函数在不同分区片段中对相同值可能返回不同的位置。

语法

lowCardinalityIndices(col)

参数

col — 低基数列。LowCardinality

返回值

当前 part 的字典中该值的位置。UInt64

示例

使用示例

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;

┌─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

返回 LowCardinality 列的字典值。如果数据块的大小小于或大于字典大小，结果将分别被截断或使用默认值进行扩展。由于 LowCardinality 为每个分区片段维护独立字典，此函数在不同分区片段中可能返回不同的字典值。

语法

lowCardinalityKeys(col)

参数

col — 一个低基数列。LowCardinality

返回值

返回字典键。UInt64

示例

lowCardinalityKeys

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;

┌─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 中引入

将常量转换为包含单个值的完整列。完整列和常量在内存中的表示方式不同。函数通常会针对普通参数和常量参数执行不同的代码，尽管结果通常应当相同。此函数可用于调试这种行为。

语法

materialize(x)

参数

x — 常量。Any

返回值

返回一个由该常量值填充的整列。Any

示例

使用示例

-- 在下面的示例中,`countMatches` 函数要求第二个参数为常量。
-- 可以通过使用 `materialize` 函数将常量转换为完整的列来调试此行为,
-- 以验证该函数在接收非常量参数时会抛出错误。

SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));

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

用于计算在两个样本之间比较某个连续型指标的均值时，进行 A/B 测试所需的最小样本量。

使用这篇文章中描述的公式。假设实验组和对照组的样本量相等。返回的是单个分组所需的样本量（即整个实验所需的总样本量是返回值的两倍）。同时假设实验组和对照组中该测试指标的方差相等。

语法

minSampleSizeContinuous(baseline, sigma, mde, power, alpha)

别名：minSampleSizeContinous

参数

baseline — 指标的基线值。(U)Int* 或 Float*
sigma — 指标的基线标准差。(U)Int* 或 Float*
mde — 以基线值百分比表示的最小可检测效应（MDE）（例如，对于基线值 112.25，MDE 为 0.03 表示预期变动为 112.25 ± 112.25*0.03）。(U)Int* 或 Float*
power — 检验所需的统计功效（1 - 第二类错误的概率）。(U)Int* 或 Float*
alpha — 检验所需的显著性水平（第一类错误的概率）。(U)Int* 或 Float*

返回值

返回一个包含 3 个元素的具名 Tuple：minimum_sample_size、detect_range_lower 和 detect_range_upper。它们分别表示：所需样本量；在该样本量下无法检测到的取值范围下界，计算方式为 baseline * (1 - mde)；以及在该样本量下无法检测到的取值范围上界，计算方式为 baseline * (1 + mde)（Float64）。Tuple(Float64, Float64, Float64)

示例

minSampleSizeContinuous

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

(616.2931945826209,108.8825,115.6175)

minSampleSizeConversion

引入于：v22.6

用于 A/B 测试中，计算在两个样本间比较转化率（比例）所需的最小样本量。

使用这篇文章中描述的公式。假设试验组与对照组样本量相等。返回的是单个分组所需的样本量（即整个实验所需的总样本量是返回值的两倍）。

语法

minSampleSizeConversion(baseline, mde, power, alpha)

参数

baseline — 基准转化率。Float*
mde — 最小可检测效应（MDE），以百分点表示（例如，对于基准转化率 0.25，mde 为 0.03 表示期望变化为 0.25 ± 0.03）。Float*
power — 检验所需的统计检验功效（1 - Ⅱ类错误的概率）。Float*
alpha — 检验所需的显著性水平（Ⅰ类错误的概率）。Float*

返回值

返回一个包含 3 个元素的具名 Tuple：minimum_sample_size、detect_range_lower、detect_range_upper。它们分别表示：所需的样本量；在该样本量下无法检测到的取值范围的下界，计算为 baseline - mde；在该样本量下无法检测到的取值范围的上界，计算为 baseline + mde。Tuple(Float64, Float64, Float64)

示例

minSampleSizeConversion

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size

(3396.077603219163,0.22,0.28)

neighbor

Introduced in: v20.1

返回距离当前行指定偏移量处的列值。由于该函数基于数据块的物理顺序进行操作，而这可能与用户期望的逻辑顺序不一致，因此它已被弃用且容易出错。建议改用合适的窗口函数。

可以通过设置 allow_deprecated_error_prone_window_functions = 1 来启用该函数。

Syntax

neighbor(column, offset[, default_value])

参数

column — 源列。Any
offset — 相对于当前行的偏移量。正值向后查找，负值向前查找。Integer
default_value — 可选。当偏移超出数据范围时返回的值。若未指定，则使用该列类型的默认值。Any

返回值

返回指定偏移处的值，若越界则返回默认值。Any

示例

使用示例

SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

使用默认值

SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

┌─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 │
└────────┴──────────────────────────┘

嵌套

引入版本：v

这是 ClickHouse 引擎内部使用的一个函数，并非用于直接调用。

从多个数组返回一个由元组组成的数组。

第一个参数必须是一个由 String 类型构成的常量数组，用于指定结果 Tuple 的名称。其余参数必须是大小相同的数组。

语法

参数

无。

返回值

示例

嵌套

SELECT nested(['keys', 'values'], ['key_1', 'key_2'], ['value_1','value_2'])

normalizeQuery

自 v20.8 引入

将字面量、字面量序列以及复杂别名（包含空白字符、超过两位数字，或长度至少为 36 字节的值，如 UUID）替换为占位符 ?。

语法

normalizeQuery(x)

参数

x — 字符序列。String

返回值

返回包含占位符的指定字符序列。String

示例

使用示例

SELECT normalizeQuery('[1, 2, 3, x]') AS query

┌─query────┐
│ [?.., x] │
└──────────┘

normalizeQueryKeepNames

自 v21.2 引入

将字面量和字面量序列替换为占位符 ?，但不会替换复杂别名（包含空白字符、超过两位数字或长度至少为 36 字节的值，例如 UUID）。这有助于更好地分析复杂的查询日志。

语法

normalizeQueryKeepNames(x)

参数

x — 字符串。String

返回值

返回带有占位符的给定字符串。String

示例

使用示例

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

normalizedQueryHash

引入自：v20.8

对于相似的查询，在不考虑字面量值的情况下，返回相同的 64 位哈希值。这在分析查询日志时非常有用。

语法

normalizedQueryHash(x)

参数

x — 字符序列。String

返回值

返回一个 64 位哈希值。UInt64

示例

用法示例

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res

┌─res─┐
│   1 │
└─────┘

normalizedQueryHashKeepNames

引入版本：v21.2

与 normalizedQueryHash 类似，它在对相似查询计算哈希时，会返回相同的 64 位哈希值，并忽略字面量的取值，但在计算哈希之前不会将复杂别名（包含空白字符、超过两位数字，或长度至少为 36 字节（例如 UUID））替换为占位符。在分析查询日志时可能会有帮助。

语法

normalizedQueryHashKeepNames(x)

参数

x — 字符序列。String

返回值

返回一个 64 位哈希值。UInt64

示例

使用示例

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;

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

parseReadableSize

引入版本：v24.6

给定一个以 B、KiB、KB、MiB、MB 等作为单位来表示字节大小的字符串（即 ISO/IEC 80000-13 或十进制字节单位），此函数返回对应的字节数。如果函数无法解析输入值，则会抛出异常。

此函数的逆操作是 formatReadableSize 和 formatReadableDecimalSize。

语法

parseReadableSize(x)

参数

x — 使用 ISO/IEC 80000-13 或十进制字节单位表示的可读大小值。String

返回值

返回以字节为单位的数值，并向上取整为最接近的整数值。UInt64

示例

使用示例

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

parseReadableSizeOrNull

自 v24.6 引入

给定一个包含字节大小以及 B、KiB、KB、MiB、MB 等作为单位的字符串（即 ISO/IEC 80000-13 或十进制字节单位），该函数返回对应的字节数。如果函数无法解析输入值，则返回 NULL。

该函数的逆操作是 formatReadableSize 和 formatReadableDecimalSize。

语法

parseReadableSizeOrNull(x)

参数

x — 使用 ISO/IEC 80000-13 或十进制字节单位表示的人类可读大小。String

返回值

返回向上取整到最接近整数的字节数；如果无法解析输入，则返回 NULL。Nullable(UInt64)

示例

用法示例

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

parseReadableSizeOrZero

引入于：v24.6

给定一个包含字节大小及其单位（如 B、KiB、KB、MiB、MB 等）的字符串（即 ISO/IEC 80000-13 或十进制字节单位），该函数返回对应的字节数。如果函数无法解析输入值，则返回 0。

该函数的逆操作是 formatReadableSize 和 formatReadableDecimalSize。

语法

parseReadableSizeOrZero(x)

参数

x — 使用 ISO/IEC 80000-13 或十进制字节单位表示的可读大小。String

返回值

返回字节数，向上取整为最接近的整数；如果无法解析输入，则返回 0。UInt64

示例

使用示例

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

parseTimeDelta

自 v22.7 引入

解析由一串数字加上类似时间单位的内容所组成的字符串。

时间间隔字符串使用以下时间单位说明：

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

可以使用分隔符（空格、;、-、+、,、:）组合多个时间单位。

年份和月份的时长是近似值：year 为 365 天，month 为 30.5 天。

语法

parseTimeDelta(timestr)

参数

timestr — 由一串数字组成，后面跟着类似时间单位的标记。String

返回值

以秒为单位的数值。Float64

示例

用法示例

SELECT parseTimeDelta('11s+22min')

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

复合时间单位

SELECT parseTimeDelta('1yr2mo')

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

partitionId

自 v21.4 引入

计算分区 ID。

注意

此函数较慢，不应对大量行进行调用。

语法

partitionId(column1[, column2, ...])

别名：partitionID

参数

column1, column2, ... — 要返回其分区 ID 的列。

返回值

返回该行所属的分区 ID。String

示例

使用示例

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;

┌─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 版本引入

返回当前查询的 ID。查询的其他参数可以从 system.query_log 表中的 query_id 字段中获取。

与 initialQueryID 函数不同，queryID 在不同分片上可能返回不同的结果。

语法

queryID()

别名：query_id

参数

无。

返回值

返回当前查询的 ID，类型为 String。

示例

使用示例

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());

┌─count(DISTINCT t)─┐
│                 3 │
└───────────────────┘

revision

引入版本：v22.7

返回当前 ClickHouse 服务器的修订版本号。

语法

revision()

参数

无。

返回值

返回当前 ClickHouse 服务器的修订号。UInt32

示例

使用示例

SELECT revision()

┌─revision()─┐
│      54485 │
└────────────┘

rowNumberInAllBlocks

引入于：v1.1

为处理的每一行返回一个唯一的行号。

语法

rowNumberInAllBlocks()

参数

无。

返回值

返回数据块中行的序号，从 0 开始计数。UInt64

示例

使用示例

SELECT rowNumberInAllBlocks()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
)
SETTINGS max_block_size = 2

┌─rowNumberInAllBlocks()─┐
│                      0 │
│                      1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      4 │
│                      5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      2 │
│                      3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      6 │
│                      7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      8 │
│                      9 │
└────────────────────────┘

rowNumberInBlock

引入版本：v1.1

对于每个由 rowNumberInBlock 处理的块，返回当前行的行号。

在每个块内，返回的行号从 0 开始计数。

语法

rowNumberInBlock()

参数

无。

返回值

返回数据块中行的序号，从 0 开始。UInt64

示例

用法示例

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘

runningAccumulate

在 v1.1 中引入

对数据块中每一行累积该聚合函数的状态。

已弃用

对于每个新的数据块，状态都会被重置。由于这种容易出错的行为，该函数已被弃用，建议改用窗口函数。您可以使用 setting allow_deprecated_error_prone_window_functions 来允许继续使用此函数。

语法

runningAccumulate(agg_state[, grouping])

参数

agg_state — 聚合函数的状态。AggregateFunction
grouping — 可选。分组键。当 grouping 的值发生变化时，函数状态会被重置。它可以是任意支持等值运算符的数据类型。Any

返回值

为每一行返回累计结果。Any

示例

结合 initializeAggregation 的用法示例

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);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

runningConcurrency

引入于：v21.3

计算并发事件的数量。每个事件都有开始时间和结束时间。开始时间包含在事件内，而结束时间被排除在外。包含开始时间和结束时间的列必须使用相同的数据类型。该函数会针对每个事件的开始时间计算处于活动状态（并发）的事件总数。

要求

事件必须按照开始时间升序排序。如果不满足此要求，函数将抛出异常。每个数据块会被单独处理。如果来自不同数据块的事件发生重叠，则无法被正确处理。

已弃用

建议改用窗口函数。

语法

runningConcurrency(start, end)

参数

start — 包含事件开始时间的列。Date 或 DateTime 或 DateTime64
end — 包含事件结束时间的列。Date 或 DateTime 或 DateTime64

返回值

返回在每个事件开始时间的并发事件数量。UInt32

示例

用法示例

SELECT start, runningConcurrency(start, end) FROM example_table;

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │                              1 │
│ 2025-03-06 │                              2 │
│ 2025-03-07 │                              3 │
│ 2025-03-11 │                              2 │
└────────────┴────────────────────────────────┘

runningDifference

自 v1.1 起提供

计算数据块中相邻两行数值之间的差值。对于第一行返回 0，对于后续各行返回其与前一行的差值。

Deprecated

只会计算当前正在处理的数据块内的差值。由于这种易出错的行为，该函数已被弃用。建议改用窗口函数。

你可以通过设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

函数结果依赖于参与计算的数据块以及块内数据的顺序。在计算 runningDifference() 时，行的顺序可能与返回给用户的行顺序不同。为避免这一点，你可以先创建带有 ORDER BY 的子查询，然后在子查询外部调用该函数。请注意，块大小会影响结果。 runningDifference 的内部状态会在每个新块时重置。

语法

runningDifference(x)

参数

x — 要计算逐行差值的列。Any

返回值

返回相邻值之间的差值，首行返回 0。

示例

用法示例

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2025-11-24'
    ORDER BY EventTime ASC
    LIMIT 5
);

┌─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 │
└─────────┴─────────────────────┴───────┘

块大小影响的示例

SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;

┌─number─┬─diff─┐
│      0 │    0 │
└────────┴──────┘
┌─number─┬─diff─┐
│  65536 │    0 │
└────────┴──────┘

runningDifferenceStartingWithFirstValue

引入版本：v1.1

计算数据块中相邻行值之间的差值，但与 runningDifference 不同，它返回第一行的实际值，而不是 0。

已弃用

仅返回当前正在处理的数据块内部的差值。由于这种容易出错的特性，该函数已被弃用。建议改用窗口函数。

你可以通过设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

语法

runningDifferenceStartingWithFirstValue(x)

参数

x — 要计算逐行差值的列。Any

返回值

返回相邻行值之间的差，对于第一行返回该行自身的值。Any

示例

用法示例

SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

┌─number─┬─diff─┐
│      0 │    0 │
│      1 │    1 │
│      2 │    1 │
│      3 │    1 │
│      4 │    1 │
└────────┴──────┘

serverUUID

自 v20.1 版本引入

返回在服务器首次启动时生成的随机且唯一的 UUID（v4）。该 UUID 会被持久化，因此在第二次、第三次等后续服务器启动时会返回相同的 UUID。

语法

serverUUID()

参数

无。

返回值

返回服务器的随机 UUID 值。UUID

示例

用法示例

SELECT serverUUID();

┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f     │
└──────────────────────────────────────────┘

shardCount

自 v21.9 引入

返回分布式查询的分片总数。如果查询不是分布式的，则返回常量值 0。

语法

shardCount()

参数

无。

返回值

返回分片的总数或 0。UInt32

示例

用法示例

-- 参见上文 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;

┌─shardCount()─┐
│            2 │
│            2 │
└──────────────┘

shardNum

自 v21.9 起引入

返回在分布式查询中处理部分数据的分片的索引。索引从 1 开始。如果查询不是分布式查询，则返回常量值 0。

语法

shardNum()

参数

无。

返回值

返回分片索引或常量 0，类型为 UInt32。

示例

用法示例

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;

┌─dummy─┬─shardNum()─┬─shardCount()─┐
│     0 │          1 │            2 │
│     0 │          2 │            2 │
└───────┴────────────┴──────────────┘

showCertificate

自 v22.6 引入

如果当前服务器已配置安全套接字层 (SSL) 证书，则显示该证书的信息。有关如何配置 ClickHouse 使用 OpenSSL 证书来验证连接的详细信息，请参阅配置 SSL-TLS。

语法

showCertificate()

参数

无。

返回值

返回一个与已配置 SSL 证书相关的键值对映射。Map(String, String)

示例

用法示例

SELECT showCertificate() FORMAT LineAsString;

{'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

按指定的秒数暂停查询的执行。该函数主要用于测试和调试。

在生产环境中通常不应使用 sleep() 函数，因为它可能会对查询性能和系统响应性产生负面影响。不过，在以下场景中它可能会很有用：

测试：在测试或基准测试 ClickHouse 时，你可能希望模拟延迟或引入暂停，以观察系统在特定条件下的行为。
调试：如果你需要在某个特定时间点检查系统状态或查询的执行情况，可以使用 sleep() 引入暂停，从而检查或收集相关信息。
模拟：在某些情况下，你可能希望模拟现实场景中出现的延迟或暂停，例如网络延迟或对外部系统的依赖。

注意

务必谨慎且仅在必要时使用 sleep() 函数，因为它可能会影响 ClickHouse 系统的整体性能和响应性。

出于安全原因，该函数只能在默认用户配置中执行（且需启用 allow_sleep）。

语法

sleep(seconds)

参数

seconds — 暂停查询执行的时间（秒），上限为 3 秒。可以为浮点数，以指定小数秒数。const UInt* 或 const Float*

返回值

返回 0。UInt8

示例

用法示例

-- 此查询将在完成前暂停 2 秒。
-- 在此期间不会返回任何结果,查询将呈现挂起或无响应状态。
SELECT sleep(2);

┌─sleep(2)─┐
│        0 │
└──────────┘
返回 1 行。用时：2.012 秒。

sleepEachRow

引入于：v1.1

对结果集中的每一行，将查询执行暂停指定的秒数。

sleepEachRow() 函数主要用于测试和调试，类似于 sleep() 函数。它允许在处理每一行时模拟延迟或引入暂停，在以下场景中十分有用：

测试：在特定条件下测试或基准评估 ClickHouse 性能时，可以使用 sleepEachRow() 来模拟延迟或为每一行的处理引入暂停。
调试：如果需要在每一行被处理时检查系统状态或查询执行情况，可以使用 sleepEachRow() 引入暂停，从而检查或收集相关信息。
模拟：在某些情况下，可能希望模拟真实场景中每处理一行都会发生延迟或暂停的情况，例如与外部系统交互或存在网络延迟时。

注意

与 sleep() 函数类似，务必要谨慎并仅在必要时使用 sleepEachRow()，因为它可能会显著影响 ClickHouse 系统的整体性能和响应能力，尤其是在处理大型结果集时。

语法

sleepEachRow(seconds)

参数

seconds — 在结果集中的每一行暂停执行查询的秒数，最大为 3 秒。可以是浮点数以指定小数秒。const UInt* 或 const Float*

返回值

针对每一行返回 0。UInt8

示例

用法示例

-- 输出将被延迟，每行之间暂停 0.5 秒。
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

┌─number─┬─sleepEachRow(0.5)─┐
│      0 │                 0 │
│      1 │                 0 │
│      2 │                 0 │
│      3 │                 0 │
│      4 │                 0 │
└────────┴───────────────────┘

structureToCapnProtoSchema

引入于：v

将 ClickHouse 表结构转换为 CapnProto 格式 schema 的函数

语法

参数

无。

返回值

示例

random

SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw

struct MessageName
{
    s @0 : Data;
    x @1 : UInt32;
}

structureToProtobufSchema

引入版本：v23.8

将 ClickHouse 表结构转换为 Protobuf 格式的 schema 定义。

该函数接受一个 ClickHouse 表结构定义，并将其转换为采用 proto3 语法的 Protocol Buffers（Protobuf） schema 定义。这对于生成与 ClickHouse 表结构相匹配、用于数据交换的 Protobuf schema 非常有用。

语法

structureToProtobufSchema(structure, message_name)

参数

structure — 以字符串形式表示的 ClickHouse 表结构定义（例如，'column1 Type1, column2 Type2'）。String
message_name — 生成的 schema 中 Protobuf 消息类型的名称。String

返回值

返回一个与输入 ClickHouse 表结构相对应、使用 proto3 语法的 Protobuf schema 定义。String

示例

将 ClickHouse 结构转换为 Protobuf schema

SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;

syntax = "proto3";

message MessageName
{
    bytes s = 1;
    uint32 x = 2;
}

tcpPort

引入版本：v20.12

返回服务器监听的原生接口 TCP 端口号。如果在分布式表的上下文中执行，该函数会生成一个普通列，其中的值对应各个分片。否则将返回一个常量。

语法

tcpPort()

参数

无。

返回值

返回 TCP 端口号。UInt16

示例

使用示例

SELECT tcpPort()

┌─tcpPort()─┐
│      9000 │
└───────────┘

throwIf

自 v1.1 起提供

当参数 x 为 true 时抛出异常。要使用 error_code 参数，必须启用配置参数 allow_custom_error_code_in_throw。

语法

throwIf(x[, message[, error_code]])

参数

x — 要检查的条件。Any
message — 可选。自定义错误信息。const String
error_code — 可选。自定义错误代码。const Int8/16/32

返回值

如果条件为假，则返回 0；如果条件为真，则抛出异常。UInt8

示例

用法示例

SELECT throwIf(number = 3, '太多了') FROM numbers(10);

↙ 进度：0.00 行，0.00 B（0.00 行/秒，0.00 B/秒）从服务器接收到异常（版本 19.14.1）：
代码：395. DB::Exception: 从 localhost:9000 接收。DB::Exception: 太多。

toColumnTypeName

引入于：v1.1

返回给定值的数据类型的内部名称。与函数 toTypeName 不同，返回的数据类型可能包含诸如 Const 和 LowCardinality 等内部封装列。

语法

toColumnTypeName(value)

参数

value — 要获取其内部数据类型的值。Any

返回值

返回用于表示该值的内部数据类型名称。String

示例

用法示例

SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));

┌─toColumnTypeName(CAST('2025-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32)                                             │
└───────────────────────────────────────────────────────────┘

toTypeName

自 v1.1 引入

返回传入参数的类型名称。如果传入 NULL，函数返回类型 Nullable(Nothing)，它对应于 ClickHouse 内部的 NULL 表示形式。

语法

toTypeName(x)

参数

x — 任意数据类型的值。Any

返回值

返回输入值所属的数据类型名称。String

示例

用法示例

SELECT toTypeName(123)

┌─toTypeName(123)─┐
│ UInt8           │
└─────────────────┘

transactionID

自 v22.6 引入

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

返回事务的 ID。

注意

此函数属于一组实验性特性。通过在您的配置中添加以下设置来启用实验性事务支持：

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

有关更多信息，请参阅事务（ACID）支持页面。

语法

transactionID()

参数

无。

返回值

返回一个由 start_csn、local_tid 和 host_id 组成的元组。

start_csn：全局顺序号，即在该事务开始时所见到的最新提交时间戳。
local_tid：本地主机内的顺序号，在给定 start_csn 下由该主机启动的每个事务都唯一。
host_id：启动该事务的主机的 UUID。 Tuple(UInt64, UInt64, UUID)

示例

使用示例

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘

transactionLatestSnapshot

自 v22.6 引入

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

返回可供读取的某个事务的最新快照（提交序列号 Commit Sequence Number）。

注意

此函数属于一组实验性功能。可通过在配置中添加以下 SETTING 启用实验性事务支持：

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

有关更多信息，请参阅事务（ACID）支持页面。

语法

transactionLatestSnapshot()

参数

无。

返回值

返回事务的最新快照（CSN）。UInt64

示例

使用示例

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

┌─transactionLatestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transactionOldestSnapshot

自 v22.6 引入

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

返回对某个正在运行的事务可见的最早快照（提交序列号，Commit Sequence Number）。

注意

此函数属于一组实验性功能。通过在配置中添加以下设置项来启用事务的实验性支持：

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

更多信息请参见事务（ACID）支持页面。

语法

transactionOldestSnapshot()

参数

无。

返回值

返回事务的最早快照（CSN）。UInt64

示例

用法示例

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

┌─transactionOldestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transform

引入版本：v1.1

根据显式定义的若干元素到其他元素的映射来转换一个值。

此函数有两种变体：

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，其中所有类型必须相同

语法

transform(x, array_from, array_to[, default])

参数

x — 要转换的值。(U)Int* 或 Decimal 或 Float* 或 String 或 Date 或 DateTime
array_from — 用于匹配查找的常量数组。Array((U)Int*) 或 Array(Decimal) 或 Array(Float*) 或 Array(String) 或 Array(Date) 或 Array(DateTime)
array_to — 当在 array_from 中找到匹配项时要返回的对应值的常量数组。Array((U)Int*) 或 Array(Decimal) 或 Array(Float*) 或 Array(String) 或 Array(Date) 或 Array(DateTime)
default — 可选。当在 array_from 中找不到 x 时要返回的值。如果省略，则返回未改变的 x。(U)Int* 或 Decimal 或 Float* 或 String 或 Date 或 DateTime

返回值

如果 x 与 array_from 中的某个元素匹配，则返回 array_to 中对应的值；否则返回 default（如果提供）或 x（如果未提供 default）。返回类型为 Any

示例

transform(T, Array(T), Array(U), U) -> U

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

┌─title─────┬──────c─┐
│ Yandex    │ 498635 │
│ Google    │ 229872 │
│ Other     │ 104472 │
└───────────┴────────┘

transform(T, Array(T), Array(T)) -> T

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

┌─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 中引入

对两个 uniqThetaSketch 对象执行交集运算（集合运算 ∩），结果是一个新的 uniqThetaSketch。

语法

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

参数

uniqThetaSketch — uniqThetaSketch 对象。Tuple 或 Array 或 Date 或 DateTime 或 String 或 (U)Int* 或 Float* 或 Decimal

返回值

一个新的 uniqThetaSketch 对象，包含交集结果。UInt64

示例

使用示例

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);

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

uniqThetaNot

引入版本：v22.9

对两个 uniqThetaSketch 对象执行 a_not_b 计算（集合运算 ×），返回一个新的 uniqThetaSketch。

语法

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

参数

uniqThetaSketch — uniqThetaSketch 对象。Tuple 或 Array 或 Date 或 DateTime 或 String 或 (U)Int* 或 Float* 或 Decimal

返回值

返回一个新的 uniqThetaSketch 对象，其中包含 a_not_b 结果。UInt64

示例

使用示例

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);

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

uniqThetaUnion

自 v22.9 版本引入

对两个 uniqThetaSketch 对象进行并集计算（集合运算 ∪），结果是一个新的 uniqThetaSketch。

语法

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

参数

uniqThetaSketch — uniqThetaSketch 对象。Tuple 或 Array 或 Date 或 DateTime 或 String 或 (U)Int* 或 Float* 或 Decimal

返回值

返回一个新的 uniqThetaSketch，其中包含并集结果。UInt64

示例

使用示例

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);

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

uptime

引入版本：v1.1

返回服务器的运行时间（以秒为单位）。如果在分布式表的上下文中执行，此函数会生成一个普通列，其值对应各个分片。否则，它会返回一个常量值。

语法

uptime()

参数

无。

返回值

返回服务器的运行时间（以秒为单位）。UInt32

示例

使用示例

SELECT uptime() AS Uptime

┌─Uptime─┐
│  55867 │
└────────┘

variantElement

自 v25.2 起引入

从 Variant 列中提取具有指定类型的列。

语法

variantElement(variant, type_name[, default_value])

参数

variant — Variant 列。Variant
type_name — 要提取的 Variant 类型名称。String
default_value — 当 Variant 中不存在指定类型的值时所使用的默认值。可以为任意类型。可选。Any

返回值

返回一个从 Variant 列中提取出指定 Variant 类型值的列。Any

示例

用法示例

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;

┌─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

对 Variant 列的每一行，返回其变体类型名称。如果该行包含 NULL，则返回 'None'。

语法

variantType(variant)

参数

variant — Variant 列。Variant

返回值

返回一个 Enum 列，其中每一行的值为对应的 Variant 类型名称。Enum

示例

用法示例

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;

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

version

引入于：v1.1

以字符串形式返回当前 ClickHouse 的版本：major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release。如果在分布式表的上下文中执行，则该函数会生成一个普通列，其中的值对应各个分片。否则，它会生成一个常量值。

语法

version()

参数

无。

返回值

返回当前 ClickHouse 版本号。String

示例

用法示例

SELECT version()

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

visibleWidth

引入版本：v1.1

计算以文本格式（制表符分隔）将值输出到控制台时的大致宽度。系统使用此函数来实现 Pretty 系列输出格式。在 Pretty 格式中，NULL 使用与 NULL 对应的字符串表示。

语法

visibleWidth(x)

参数

x — 任意数据类型的值。Any

返回值

返回该值在以文本格式显示时的近似宽度。UInt64

示例

计算 NULL 的可见宽度

SELECT visibleWidth(NULL)

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

zookeeperSessionUptime

自 v21.11 起引入

返回当前 ZooKeeper 会话的运行时间（以秒为单位）。

语法

zookeeperSessionUptime()

参数

无。

返回值

返回当前 ZooKeeper 会话的运行时长（秒）。UInt32

示例

用法示例

SELECT zookeeperSessionUptime();

┌─zookeeperSessionUptime()─┐
│                      286 │
└──────────────────────────┘

FQDN​

MACNumToString​

MACStringToNum​

MACStringToOUI​

__applyFilter​

__patchPartitionID​

authenticatedUser​

bar​

blockNumber​

blockSerializedSize​

blockSize​

buildId​

byteSize​

catboostEvaluate​

colorOKLCHToSRGB​

colorSRGBToOKLCH​

connectionId​

countDigits​

currentDatabase​

currentProfiles​

currentQueryID​

currentRoles​

currentSchemas​

currentUser​

defaultProfiles​

defaultRoles​

defaultValueOfArgumentType​

defaultValueOfTypeName​

displayName​

dumpColumnStructure​

enabledProfiles​

enabledRoles​

errorCodeToName​

file​

filesystemAvailable​

filesystemCapacity​

filesystemUnreserved​

finalizeAggregation​

flipCoordinates​

formatQuery​

formatQueryOrNull​

formatQuerySingleLine​

formatQuerySingleLineOrNull​

formatReadableDecimalSize​

formatReadableQuantity​

formatReadableSize​

formatReadableTimeDelta​

generateRandomStructure​

generateSerialID​

getClientHTTPHeader​

getMacro​

getMaxTableNameLengthForDatabase​

getMergeTreeSetting​

getOSKernelVersion​

getServerPort​

getServerSetting​

getSetting​

getSettingOrDefault​

getSizeOfEnumType​

getSubcolumn​

getTypeSerializationStreams​

globalVariable​

hasColumnInTable​

hasThreadFuzzer​

hostName​

icebergBucket​

icebergTruncate​

identity​

ignore​

indexHint​

initialQueryID​

initialQueryStartTime​

initializeAggregation​

isConstant​

isDecimalOverflow​

joinGet​

joinGetOrNull​

lowCardinalityIndices​

lowCardinalityKeys​

materialize​

FQDN

MACNumToString

MACStringToNum

MACStringToOUI

__applyFilter

__patchPartitionID

authenticatedUser

bar

blockNumber

blockSerializedSize

blockSize

buildId

byteSize

catboostEvaluate

colorOKLCHToSRGB

colorSRGBToOKLCH

connectionId

countDigits

currentDatabase

currentProfiles

currentQueryID

currentRoles

currentSchemas

currentUser

defaultProfiles

defaultRoles

defaultValueOfArgumentType

defaultValueOfTypeName

displayName

dumpColumnStructure

enabledProfiles

enabledRoles

errorCodeToName

file

filesystemAvailable

filesystemCapacity

filesystemUnreserved

finalizeAggregation

flipCoordinates

formatQuery

formatQueryOrNull

formatQuerySingleLine

formatQuerySingleLineOrNull

formatReadableDecimalSize

formatReadableQuantity

formatReadableSize

formatReadableTimeDelta

generateRandomStructure

generateSerialID

getClientHTTPHeader

getMacro

getMaxTableNameLengthForDatabase

getMergeTreeSetting

getOSKernelVersion

getServerPort

getServerSetting

getSetting

getSettingOrDefault

getSizeOfEnumType

getSubcolumn

getTypeSerializationStreams

globalVariable

hasColumnInTable

hasThreadFuzzer

hostName

icebergBucket

icebergTruncate

identity

ignore

indexHint

initialQueryID

initialQueryStartTime

initializeAggregation

isConstant

isDecimalOverflow

joinGet

joinGetOrNull

lowCardinalityIndices

lowCardinalityKeys

materialize