其他函数

注意

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

FQDN

首次引入于：v20.1

返回 ClickHouse 服务器的完全限定域名（FQDN，Fully Qualified Domain Name）。

语法

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;

authenticatedUser

引入于：v25.11

如果会话 USER 已通过 EXECUTE AS 命令被切换，则此函数返回最初用于身份验证并创建会话的原始 USER 名称。别名：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 中，查询是按块（chunk）进行处理的。此函数返回调用该函数所在块的大小（行数）。

语法

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

colorOKLABToSRGB

引入版本：v26.2

将颜色从 OKLab 知觉色彩空间转换为 sRGB 色彩空间。

输入颜色在 OKLab 色彩空间中指定。如果输入值超出典型的 OKLab 取值范围，则结果由具体实现决定。

OKLab 使用三个分量：

L：知觉亮度（通常在 [0..1] 范围内）
- a：绿-红对立轴
- b：蓝-黄对立轴

a 和 b 分量在理论上不受限制，但在实践中通常介于 -0.4 到 0.4 之间。 OKLab 旨在在保持计算成本较低的同时，实现知觉上的均匀性。

该转换设计为 colorSRGBToOKLAB 的逆变换，并包括以下阶段：

从 OKLab 转换为线性 sRGB。 2) 从线性 sRGB 转换为伽马编码的 sRGB。

可选参数 gamma 指定从线性 sRGB 转换为伽马编码 RGB 值时使用的指数。如果未指定，则使用默认的 gamma 值，以与 colorSRGBToOKLAB 保持一致。

有关 OKLab 色彩空间及其与 sRGB 关系的更多信息，请参阅 https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab 。

语法

colorOKLABToSRGB(tuple [, gamma])

参数

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

返回值

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

示例

将 OKLAB 转换为 sRGB（浮点型）

SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;

┌─rgb──────────────────────┐
│ (198.07056923258935,0,0) │
└──────────────────────────┘

将 OKLAB 转换为 sRGB（UInt8）

WITH colorOKLABToSRGB((0.7, 0.1, 0.54)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB──────────┐
│ (255,0,0)    │
└──────────────┘

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。 2) OKLab 转换为线性 sRGB 3) 线性 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 — 可选。用于通过对每个通道 x 应用 (x ^ (1 / gamma)) * 255 将线性 sRGB 转换回 sRGB 的指数。默认值为 2.2。Float64

返回值

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

示例

将 OKLCH 转换为 sRGB

SELECT colorOKLCHToSRGB((0.6, 0.12, 40)) AS rgb;

┌─rgb───────────────────────────────────────────────────────┐
│ (186.02058688365264,100.68677189684993,71.67819977081575) │
└───────────────────────────────────────────────────────────┘

将 OKLCH 转换为 sRGB（UInt8）

WITH colorOKLCHToSRGB((0.6, 0.12, 40)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB──────────┐
│ (186,100,71) │
└──────────────┘

colorSRGBToOKLAB

引入于：v26.2

将以 sRGB 色彩空间编码的颜色转换为感知均匀的 OKLAB 色彩空间。

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

注意

OKLAB 是一种感知均匀的色彩空间。它的三个坐标分别是 L（亮度，范围为 [0...1]）、a (Green-Red axis) 和 b (Blue-Yellow axis)。 OKLab 的设计目标是在保持感知均匀的同时，尽量降低计算成本。

转换过程由两个阶段组成：

sRGB 到 Linear sRGB 2) Linear sRGB 到 OKLab

语法

colorSRGBToOKLAB(tuple[, gamma])

参数

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

返回值

返回一个 (L, a, b) 元组，表示 OKLAB 颜色空间的值。Tuple(Float64, Float64, Float64)

示例

将 sRGB 转换为 OKLAB

SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;

┌─lab──────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.07266246769242975,0.07500108778529994) │
└──────────────────────────────────────────────────────────────┘

colorSRGBToOKLCH

自 v25.7 引入

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

如果任一输入通道超出 [0...255] 范围或 gamma 值小于等于 0，则行为由具体实现自行定义。

注意

OKLCH 是 OKLab 色彩空间的圆柱坐标形式。它的三个坐标分别为 L（亮度，范围 [0...1]）、C（色度，>= 0）和 H（色相，角度范围 [0...360]）。 OKLab/OKLCH 的设计目标是在保持计算开销较低的同时，实现感知上的均匀性。

转换由三个阶段组成：

sRGB 到线性 sRGB 2) 线性 sRGB 到 OKLab 3) 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

返回值

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

示例

将 sRGB 转换为 OKLCH

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

┌─lch───────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.1044269954567863,45.90734548193018) │
└───────────────────────────────────────────────────────────┘

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

引入版本：v25.2

返回当前查询 ID。

语法

currentQueryID()

别名: current_query_id

参数

返回值

示例

SELECT currentQueryID();

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

currentRoles

自 v21.9 版本引入

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

语法

currentRoles()

参数

无。

返回值

返回一个数组，其中包含授予当前用户的角色。Array(String)

示例

使用示例

SELECT currentRoles();

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

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:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

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

参数

无。

返回值

返回一个数组，包含当前 USER 已启用的设置配置文件名称。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:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────────────────────┘

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 "Available space";

┌─Available space─┐
│ 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 "Free space";

┌─Free space─┐
│ 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

对几何对象的 x 和 y 坐标进行翻转。该操作会交换纬度和经度，这对于在不同坐标系之间转换或纠正坐标顺序非常有用。

对于 Point，它会交换 x 和 y 坐标。对于复杂几何对象（LineString、Polygon、MultiPolygon、Ring、MultiLineString），它会递归地对每一对坐标应用此变换。

该函数同时支持各个几何类型（Point、Ring、Polygon、MultiPolygon、LineString、MultiLineString）以及 Geometry 变体类型。

语法

flipCoordinates(geometry)

参数

geometry — 要变换的几何对象。支持的类型：Point (Tuple(Float64, Float64))、Ring (Array(Point))、Polygon (Array(Ring))、MultiPolygon (Array(Polygon))、LineString (Array(Point))、MultiLineString (Array(LineString)) 或 Geometry（包含上述任一类型的 variant 类型）。

返回值

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

示例

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

geometry_wkt

SELECT flipCoordinates(readWkt('POINT(10 20)'));

(20, 10)

geometry_polygon_wkt

SELECT flipCoordinates(readWkt('POLYGON((0 0, 5 0, 5 5, 0 5, 0 0))'));

[[(0, 0), (0, 5), (5, 5), (5, 0), (0, 0)]]

formatQuery

引入于：v23.10

返回给定 SQL 查询的格式化版本，可能为多行格式。解析出错时将抛出异常。 [example:multiline]

语法

formatQuery(query)

参数

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

返回值

格式化后的查询 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)

formatQueryOrNull

引入于：v23.11

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

语法

formatQueryOrNull(query)

参数

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

返回值

格式化后的查询 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

引入版本：v23.10

类似于 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

引入于：v23.11

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

语法

formatQuerySingleLineOrNull(query)

参数

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

返回值

格式化后的 SQL 查询 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

给定一个数字，此函数返回一个四舍五入后的、带有后缀（thousand、million、billion 等）的数值字符串。

此函数接受任意数值类型作为输入，但在内部会将其转换为 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 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

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 minute and 40 seconds                                        │
│      12345 │ 3 hours, 25 minutes and 45 seconds                             │
│  432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds│
└────────────┴────────────────────────────────────────────────────────────────┘

使用最大单位

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

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                         │
│      12345 │ 205 minutes and 45 seconds                                      │
│  432546534 │ 7209108 minutes and 54 seconds                                  │
└────────────┴─────────────────────────────────────────────────────────────────┘

fuzzQuery

引入于：v26.2

解析给定的查询字符串，并对其应用随机的 AST 变异（fuzzing）。返回变异后的查询字符串。该函数是非确定性的：每次调用都可能产生不同结果。需要设置 allow_fuzz_query_functions = 1。

语法

fuzzQuery(query)

参数

query — 要进行模糊测试的 SQL 查询。String

返回值

模糊后的查询字符串 String

示例

基本示例

SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');

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

带 start 参数

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

返回值

返回该 HTTP 头的值。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

引入版本：v25.1

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

语法

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 起引入

返回一个表示操作系统内核版本的字符串。

语法

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

返回指定服务器设置名称对应的当前值。

语法

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 引入

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

语法

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

自 v23.3 版本引入。

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

返回从该表达式中提取的指定子列。

语法

getSubcolumn(nested_value, subcolumn_name)

参数

无。

返回值

示例

getSubcolumn

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

getTypeSerializationStreams

引入版本：v22.6

枚举某个数据类型的流路径。该 FUNCTION 主要用于开发用途。

语法

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}']

map

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。此 FUNCTION 仅在测试和调试时有用。

语法

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 变换的逻辑：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

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

在索引分析期间，假定此函数的参数未被 indexHint 包裹。这使你可以根据相应条件在索引范围内选择数据，但不会再基于该条件进行进一步过滤。 ClickHouse 中的索引是稀疏的，使用 indexHint 返回的数据会比直接指定相同条件更多。

Explanation

当你运行：

SELECT * FROM test WHERE key = 123;

ClickHouse 会做两件事：

使用索引查找哪些 granule（约 8192 行的块）可能包含 key = 123
读取这些 granule，并逐行过滤，只返回满足 key = 123 的行

因此即使它从磁盘读取了 8,192 行，也只会返回实际匹配的那 1 行。

使用 indexHint 时，当你运行：

SELECT * FROM test WHERE indexHint(key = 123);

ClickHouse 只会做一件事：

使用索引查找哪些 granule 可能包含 key = 123，并从这些 granule 中返回所有行，不进行过滤。

它会返回全部 8,192 行，包括 key = 456、key = 789 等行。（即所有恰好存储在同一 granule 中的内容。） indexHint() 并非用于性能优化，而是用于调试并理解 ClickHouse 索引的工作方式：

我的条件选择了哪些 granule？
这些 granule 中有多少行？
我的索引是否被有效使用？

注意：无法使用 indexHint 函数来优化查询。indexHint 函数不会优化查询，因为它不会为查询分析提供任何额外信息。将某个表达式放到 indexHint 函数内部，并不比不使用 indexHint 函数更好。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 — 关联键列表。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

返回值

该值在当前数据部分的字典中的位置。UInt64

示例

使用示例

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

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;

-- create two parts:

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

示例

用法示例

-- In the example below the `countMatches` function expects a constant second argument.
-- This behaviour can be debugged by using the `materialize` function to turn a constant into a full column,
-- verifying that the function throws an error for a non-constant argument.

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 - II 类错误概率）。Float*
alpha — 所需检验显著性水平（I 类错误概率）。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

引入版本：v20.1

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

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

语法

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

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 引入

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

已弃用

对于每个新的数据块，状态都会被重置。由于这种易出错的行为，此函数已弃用，建议改用窗口函数。您可以通过设置 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

计算并发事件的数量。每个事件都有开始时间和结束时间。开始时间包含在事件的持续区间内，而结束时间不包含在事件内。具有开始时间和结束时间的列必须是相同的数据类型。该函数针对每个事件的开始时间计算活动（并发）事件的总数。

Requirements

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

Deprecated

建议改为使用 window functions。

语法

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，对于后续各行返回其与前一行之间的差值。

已弃用

只会返回当前正在处理的数据块内部的差值。由于这种容易出错的行为，该函数已被弃用。建议改用 window functions。

你可以通过设置 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。

Deprecated

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

你可以通过设置项 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

示例

用法示例

-- See shardNum() example above which also demonstrates 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 证书来验证连接的详细信息，请参阅 Configuring 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

示例

用法示例

-- This query will pause for 2 seconds before completing.
-- During this time, no results will be returned, and the query will appear to be hanging or unresponsive.
SELECT sleep(2);

┌─sleep(2)─┐
│        0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.

sleepEachRow

引入版本：v1.1

使查询在结果集的每一行上暂停执行指定的秒数。

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

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

注意

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

语法

sleepEachRow(seconds)

参数

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

返回值

对结果集中的每一行返回 0。UInt8

示例

用法示例

-- The output will be delayed, with a 0.5-second pause between each row.
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

引入版本：v23.8

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

语法

structureToCapnProtoSchema(table_structure, message)

参数

无。

返回值

示例

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

返回服务器监听的 native interface 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, 'Too many') FROM numbers(10);

↙ 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

返回给定值对应数据类型的内部名称。与函数 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）。

注意

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

<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 计算（Set 操作 ×），返回一个新的 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 中不包含指定类型的 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​

authenticatedUser​

bar​

blockNumber​

blockSerializedSize​

blockSize​

buildId​

byteSize​

catboostEvaluate​

colorOKLABToSRGB​

colorOKLCHToSRGB​

colorSRGBToOKLAB​

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​

fuzzQuery​

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​

FQDN

MACNumToString

MACStringToNum

MACStringToOUI

authenticatedUser

bar

blockNumber

blockSerializedSize

blockSize

buildId

byteSize

catboostEvaluate

colorOKLABToSRGB

colorOKLCHToSRGB

colorSRGBToOKLAB

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

fuzzQuery

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