其他函数 - ClickHouse Documentation

下方的函数文档由 system.functions 系统表自动生成。

FQDN

引入于：v20.1.0 返回 ClickHouse 服务器的全限定域名。语法

FQDN()

别名：fullHostName 参数

无。

返回值 返回 ClickHouse 服务器的全限定域名。String 示例 使用示例

Query

SELECT fqdn()

Response

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

MACNumToString

引入版本：v1.1.0 将一个 UInt64 数值按大端格式解释为 MAC 地址。返回对应的 MAC 地址字符串，格式为 AA:BB:CC:DD:EE:FF (以冒号分隔的十六进制数字) 。语法

MACNumToString(num)

参数

num — UInt64 数字。UInt64

返回值 返回格式为 AA:BB:CC:DD:EE:FF 的 MAC 地址。String 示例 使用示例

Query

SELECT MACNumToString(149809441867716) AS mac_address;

Response

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

MACStringToNum

引入版本：v1.1.0 MACNumToString 的反函数。如果 MAC 地址格式无效，则返回 0。语法

MACStringToNum(s)

参数

s — MAC 地址字符串。String

返回值 返回 UInt64 数值。UInt64 示例 使用示例

Query

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

Response

1108152157446

MACStringToOUI

引入版本：v1.1.0 给定格式为 AA:BB:CC:DD:EE:FF 的 MAC 地址 (以冒号分隔的十六进制数字) ，返回其前三个八位字节对应的 UInt64 数值。如果 MAC 地址格式无效，则返回 0。语法

MACStringToOUI(s)

参数

s — MAC 地址字符串。String

返回值 前 3 个八位字节，类型为 UInt64。UInt64 示例 使用示例

Query

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

Response

authenticatedUser

引入版本：v25.11.0 如果使用 EXECUTE AS 命令切换了 session 用户，此函数会返回用于身份验证和创建 session 的原始用户名称。别名：authUser() 语法

authenticatedUser()

别名: authUser 参数

无。

返回值 通过身份验证的用户名称。String 示例 用法示例

Query

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

Response

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

bar

引入版本：v1.1.0 生成条形图。绘制一个条带，其宽度与 (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 示例 使用示例

Query

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

Response

┌──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.0 返回包含该块中的行所属的单调递增序列号。返回的块编号会尽力保持更新，也就是说，它可能并不完全准确。语法

blockNumber()

参数

无。

返回值 该行所在数据块的序列号。UInt64 示例 基本用法

Query

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

Response

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

blockSerializedSize

引入版本：v20.3.0 返回磁盘上一块值数据的未压缩大小 (以字节为单位) 。语法

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

参数

x1[, x2, ...] — 任意数量的值，用于获取该值块的未压缩大小。Any

返回值 返回在未压缩情况下，一个值块写入磁盘时所占的字节数。UInt64 示例 用法示例

Query

SELECT blockSerializedSize(maxState(1)) AS x;

Response

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

blockSize

引入版本：v1.1.0 在 ClickHouse 中，查询按块 (chunks) 处理。此函数返回调用它时所在块的大小 (行数) 。语法

blockSize()

参数

无。

返回值 返回当前块中的行数。UInt64 示例 用法示例

Query

SELECT blockSize()
FROM system.numbers LIMIT 5

Response

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

buildId

引入版本：v20.5.0 返回编译器为正在运行的 ClickHouse 服务器可执行文件生成的构建 ID。如果在分布式表的上下文中执行，此函数会生成一个普通列，其值对应每个分片。否则，它会返回一个常量值。语法

buildId()

参数

无。

返回值 返回构建 ID。String 示例 使用示例

Query

SELECT buildId()

Response

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

byteSize

Introduced in: v21.1.0 返回其参数在内存中未压缩字节大小的估算值。对于 String 参数，该函数返回字符串长度 + 8 (长度) 。如果函数有多个参数，则会累加它们的字节大小。 Syntax

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

参数

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

返回值 返回参数在内存中所占字节大小的估算值。UInt64 示例 使用示例

Query

SELECT byteSize('string')

Response

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

多个参数

Query

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

Response

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

catboostEvaluate

引入版本：v22.9.0 评估外部 catboost 模型。CatBoost 是由 Yandex 开发的开源梯度提升库，用于机器学习。接受 catboost 模型路径和模型参数 (特征) 作为输入。 前置条件

构建 catboost 评估库

在评估 catboost 模型之前，必须先提供 libcatboostmodel.<so|dylib> 库。有关如何编译该库，请参阅 CatBoost documentation。接下来，在 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 模型，请参见训练和应用模型。语法

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

参数

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

返回值 返回模型评估结果。Float64 示例 catboostEvaluate

Query

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

Response

4.695691092573497

colorOKLABToSRGB

引入版本：v26.2.0 将颜色从 OKLab 感知色彩空间转换为 sRGB 色彩空间。输入颜色以 OKLab 色彩空间表示。如果输入值超出 OKLab 的典型范围，则结果由具体实现决定。 OKLab 使用三个分量：

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

a 和 b 分量在理论上没有界限，但在实际中通常位于 -0.4 到 0.4 之间。 OKLab 的设计目标是在保持感知均匀的同时，具备较低的计算开销。此转换旨在作为 colorSRGBToOKLAB 的逆变换，并由以下阶段组成：

从 OKLab 转换为线性 sRGB。 2) 从线性 sRGB 转换为经过 gamma 编码的 sRGB。

可选的 gamma 参数指定了从线性 sRGB 转换为经过 gamma 编码的 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 组成的 Tuple，其中 L 的取值范围为 [0...1]。Tuple(Float64, Float64, Float64)
gamma — 可选。用于将线性 sRGB 转换回 sRGB 的指数，即对每个通道 x 应用 (x ^ (1 / gamma)) * 255。默认值为 2.2。Float64

返回值 返回表示 sRGB 颜色值的 Tuple (R, G, B)。Tuple(Float64, Float64, Float64) 示例 将 OKLAB 转换为 sRGB (Float)

Query

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

Response

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

将 OKLAB 转换为 sRGB (UInt8)

Query

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

Response

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

colorOKLCHToSRGB

引入版本：v25.7.0 将颜色从 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 到 Linear sRGB 3) Linear sRGB 到 sRGB

第二个参数 gamma 用于最后一步。有关 OKLCH 空间中的颜色及其与 sRGB 颜色的对应关系，请参见 https://oklch.com/。语法

colorOKLCHToSRGB(tuple [, gamma])

参数

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

返回值 返回一个表示 sRGB 颜色值的 Tuple (R, G, B)。Tuple(Float64, Float64, Float64) 示例 将 OKLCH 转换为 sRGB

Query

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

Response

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

将 OKLCH 转换为 sRGB (UInt8)

Query

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

Response

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

colorSRGBToOKLAB

引入版本：v26.2.0 将以 sRGB 色彩空间编码的颜色转换为感知均匀的 OKLAB 色彩空间。如果任一输入通道超出 [0...255]，或 gamma 值非正，则其行为由具体实现决定。

OKLAB 是一种感知均匀的色彩空间。它的三个坐标分别是 L (范围为 [0...1] 的明度) 、a（绿色-红色轴） 和 b（蓝色-黄色轴）。 OKLab 旨在实现感知均匀，同时保持较低的计算成本。

该转换分为两个阶段：

sRGB 到 Linear sRGB 2) Linear sRGB 到 OKLab

语法

colorSRGBToOKLAB(tuple[, gamma])

参数

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

返回值 返回一个表示 OKLAB 色彩空间值的 Tuple (L, a, b)。Tuple(Float64, Float64, Float64) 示例 将 sRGB 转换为 OKLAB

Query

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

Response

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

colorSRGBToOKLCH

首次引入版本：v25.7.0 将以 sRGB 色彩空间编码的颜色转换为感知均匀的 OKLCH 色彩空间。如果任一输入通道超出 [0...255]，或者 gamma 值为非正数，则其行为由具体实现决定。

OKLCH 是 OKLab 色彩空间的圆柱形式。它有三个坐标：L (范围为 [0...1] 的明度) 、C (色度 >= 0) 和 H (范围为 [0...360]、以度为单位的色相) 。 OKLab/OKLCH 旨在实现感知均匀，同时保持较低的计算开销。

该转换分为三个阶段：

sRGB 到 Linear sRGB 2) Linear sRGB 到 OKLab 3) OKLab 到 OKLCH。

有关 OKLCH 空间中的颜色参考及其与 sRGB 颜色的对应关系，请参阅 https://OKLCH.com/。语法

colorSRGBToOKLCH(tuple[, gamma])

参数

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

返回值 返回一个表示 OKLCH 色彩空间值的Tuple (L, C, H)。Tuple(Float64, Float64, Float64) 示例 将 sRGB 转换为 OKLCH

Query

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

Response

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

connectionId

引入版本：v21.3.0 返回提交当前查询的客户端连接 ID。此函数在调试场景下最有用。它的创建是为了兼容 MySQL 的 CONNECTION_ID 函数。它通常不用于生产环境中的查询。语法

connectionId()

参数

无。

返回值 返回当前客户端的连接 ID。UInt64 示例 使用示例

Query

SELECT connectionId();

Response

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

countDigits

引入版本：v20.8.0 返回表示某个值所需的十进制位数。

此函数会考虑十进制值的标度，也就是说，它是基于底层整数类型 (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 示例 使用示例

Query

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

Response

┌─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.0 返回当前数据库的名称。在需要指定数据库的 CREATE TABLE 查询表引擎参数中，此函数非常有用。另请参阅 SET 语句。语法

currentDatabase()

别名: current_database, SCHEMA, DATABASE 参数

无。

返回值 返回当前数据库名称。String 示例 用法示例

Query

SELECT currentDatabase()

Response

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

不带括号的 SQL 标准语法

Query

SELECT CURRENT_DATABASE

Response

┌─CURRENT_DATABASE─┐
│ default          │
└──────────────────┘

currentProfiles

引入于：v21.9.0 返回当前用户的 profile 数组。语法

currentProfiles()

参数

无。

返回值 返回当前用户的 profile 数组。Array(String) 示例 用法示例

Query

SELECT currentProfiles();

Response

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

currentQueryID

引入版本：v25.2.0 返回当前 Query id。语法

currentQueryID()

别名：current_query_id 参数

无。

返回值 示例示例

Query

SELECT currentQueryID();

Response

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

currentRoles

引入于：v21.9.0 返回分配给当前用户的角色组成的数组。语法

currentRoles()

参数

无。

返回值 返回当前用户被授予的角色数组。Array(String) 示例 使用示例

Query

SELECT currentRoles();

Response

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

currentSchemas

引入版本：v23.7.0 与函数 currentDatabase 相同，但

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

函数 currentSchemas 仅为兼容 PostgreSQL 而存在。请改用 currentDatabase。另请参见 SET 语句。语法

currentSchemas(bool)

别名: current_schemas 参数

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

返回值 返回一个仅包含当前数据库名称的单元素数组。Array(String) 示例 用法示例

Query

SELECT currentSchemas(true)

Response

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

currentUser

引入版本：v20.1.0 返回当前用户的用户名。对于分布式查询，返回发起该查询的用户名。语法

currentUser()

别名: session_user, user, current_user 参数

无。

返回值 返回当前用户的名称；否则，返回发起查询的用户的登录名。String 示例 使用示例

Query

SELECT currentUser()

Response

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

不带括号的 SQL 标准语法

Query

SELECT CURRENT_USER

Response

┌─CURRENT_USER─┐
│ default      │
└──────────────┘

defaultProfiles

引入版本：v21.9.0 返回当前用户的默认 profile 名称数组。语法

defaultProfiles()

参数

无。

返回值 返回由当前用户的默认 profile 名称组成的数组。Array(String) 示例 使用示例

Query

SELECT defaultProfiles();

Response

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

defaultRoles

引入版本：v21.9.0 返回当前用户的默认角色数组。语法

defaultRoles()

参数

无。

返回值 返回由当前用户的默认角色组成的数组。Array(String) 示例 使用示例

Query

SELECT defaultRoles();

Response

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

defaultValueOfArgumentType

引入版本：v1.1.0 返回给定数据类型的默认值。不包括用户为自定义列设置的默认值。语法

defaultValueOfArgumentType(expression)

参数

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

返回值 对数值返回 0，对 String 返回空字符串，对 Nullable 类型返回 NULL。UInt8 或 String 或 NULL 示例 使用示例

Query

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

Response

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

Nullable 示例

Query

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

Response

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

defaultValueOfTypeName

自 v1.1.0 起引入返回给定类型名称的默认值。语法

defaultValueOfTypeName(type)

参数

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

返回值 返回给定类型名称的默认值：数值类型返回 0，字符串类型返回空字符串，而 Nullable UInt8、String 或 NULL 则返回 NULL 示例 使用示例

Query

SELECT defaultValueOfTypeName('Int8');

Response

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

Nullable 示例

Query

SELECT defaultValueOfTypeName('Nullable(Int8)');

Response

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

displayName

引入版本：v22.11.0 返回配置中 display_name 的值；如果未设置，则返回服务器的完全限定域名 (FQDN) 。语法

displayName()

参数

无。

返回值 返回 config 中 display_name 的值；如果未设置，则返回服务器的 FQDN。String 示例 使用示例

Query

SELECT displayName();

Response

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

dumpColumnStructure

引入版本：v1.1.0 输出列及其数据类型内部结构的详细说明。语法

dumpColumnStructure(x)

参数

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

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

Query

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

Response

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

enabledProfiles

引入于：v21.9.0 返回当前用户已启用的 profile 名称数组。语法

enabledProfiles()

参数

无。

返回值 返回由当前用户已启用的 profile 名称组成的数组。Array(String) 示例 使用示例

Query

SELECT enabledProfiles();

Response

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

enabledRoles

引入版本：v21.9.0 返回当前用户已启用角色的数组。语法

enabledRoles()

参数

无。

返回值 返回当前用户已启用的角色名称数组。Array(String) 示例 使用示例

Query

SELECT enabledRoles();

Response

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

errorCodeToName

在 v20.12.0 中引入返回数值型 ClickHouse 错误代码对应的文本名称。数值错误代码与错误名称之间的映射可在此处查看。语法

errorCodeToName(error_code)

参数

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

返回值 返回 error_code 的文本名称。String 示例 用法示例

Query

SELECT errorCodeToName(252);

Response

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

file

自 v21.3.0 起引入将文件作为字符串读取，并将数据加载到指定列中。文件内容不会被解析。另请参见 file 表函数。语法

file(path[, default])

参数

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

返回值 以字符串形式返回文件内容。String 示例 将文件插入表中

Query

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

Response

filesystemAvailable

引入版本：v20.1.0 返回承载数据库持久化存储的文件系统中的可用空间大小。返回值始终小于总可用空间 (filesystemUnreserved) ，因为其中一部分空间会保留给操作系统。语法

filesystemAvailable([disk_name])

参数

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

返回值 返回剩余可用空间的字节数。UInt64 示例 使用示例

Query

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

Response

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

filesystemCapacity

自 v20.1.0 起引入返回文件系统的容量，单位为字节。需要配置指向数据目录的 path。语法

filesystemCapacity([disk_name])

参数

disk_name — 可选。要获取容量的磁盘名称。若省略，则使用默认磁盘。String 或 FixedString

返回值 返回文件系统的容量，单位为字节。UInt64 示例 用法示例

Query

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

Response

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

filesystemUnreserved

引入版本：v22.12.0 返回承载数据库持久化存储的文件系统上未保留的总可用空间 (此前为 filesystemFree) 。另请参见 filesystemAvailable。语法

filesystemUnreserved([disk_name])

参数

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

返回值 返回可用空间总量 (以字节为单位) 。UInt64 示例 使用示例

Query

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

Response

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

finalizeAggregation

引入版本：v1.1.0 给定一个聚合状态，该函数会返回聚合结果 (如果使用了 -State 组合器，则返回最终状态) 。语法

finalizeAggregation(state)

参数

state — 聚合状态。AggregateFunction

返回值 返回聚合的最终结果。Any 示例 使用示例

Query

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

Response

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

与 initializeAggregation 配合使用

Query

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

Response

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

flipCoordinates

引入版本：v25.11.0 翻转几何对象的 x 和 y 坐标。该操作会交换纬度和经度，这对于在不同坐标系之间转换或纠正坐标顺序非常有用。对于 Point，它会交换 x 和 y 坐标。对于复杂几何对象 (LineString、Polygon、MultiPolygon、Ring、MultiLineString) ，它会递归地将此转换应用到每一对坐标上。该函数既支持单独的几何类型 (Point、Ring、Polygon、MultiPolygon、LineString、MultiLineString) ，也支持 Geometry Variant 类型。语法

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

Query

SELECT flipCoordinates((1.0, 2.0));

Response

(2.0, 1.0)

ring

Query

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

Response

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

Polygon

Query

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

Response

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

geometry_wkt

Query

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

Response

(20, 10)

geometry_polygon_wkt

Query

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

Response

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

formatQuery

引入版本：v23.10.0 返回给定 SQL 查询格式化后的版本，可能为多行。发生解析错误时会抛出异常。 [example:multiline] 语法

formatQuery(query)

参数

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

返回值 格式化后的查询 String 示例多行

Query

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

Response

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

formatQueryOrNull

引入于：v23.11.0 返回给定 SQL 查询的格式化版本，可能为多行。若发生解析错误，则返回 NULL。 [example:multiline] 语法

formatQueryOrNull(query)

参数

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

返回值 格式化后的查询 String 示例多行

Query

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

Response

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

formatQuerySingleLine

引入版本：v23.10.0 与 formatQuery() 类似，但返回的格式化字符串不包含换行符。发生解析错误时会抛出异常。 [example:multiline] 语法

formatQuerySingleLine(query)

参数

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

返回值 格式化后的查询 String 示例多行

Query

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

Response

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

formatQuerySingleLineOrNull

引入版本：v23.11.0 类似于 formatQuery()，但返回的格式化字符串不包含换行符。发生解析错误时返回 NULL。 [example:multiline] 语法

formatQuerySingleLineOrNull(query)

参数

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

返回值 格式化后的查询 String 示例多行

Query

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

Response

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

formatReadableDecimalSize

引入版本：v22.11.0 给定一个大小 (字节数) ，此函数会返回一个带后缀 (KB、MB 等) 、经过舍入且便于阅读的大小字符串。此函数的逆操作是 parseReadableSize。语法

formatReadableDecimalSize(value[, precision])

参数

value — 以字节为单位的大小。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64 或 Decimal
precision — 可选。小数点后的位数。默认值为 2。const UInt8

返回值 返回一个带后缀、经过四舍五入且便于阅读的大小字符串。String 示例 格式化文件大小

Query

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

Response

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

使用显式精度

Query

SELECT
    formatReadableDecimalSize(192851925, 0) AS no_decimals,
    formatReadableDecimalSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals─┐
│ 193 MB      │ 192.8519 MB   │
└─────────────┴───────────────┘

formatReadableQuantity

引入版本：v20.10.0 给定一个数字，此函数会返回一个四舍五入后的字符串，并带有后缀 (千、百万、十亿等) 。此函数接受任意数值类型作为输入，但在内部会将其转换为 Float64。对于较大的值，结果可能不够理想。语法

formatReadableQuantity(value[, precision])

参数

value — 要格式化的数值。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64 或 Decimal
precision — 可选。小数点后的位数。默认为 2。const UInt8

返回值 返回一个带后缀的四舍五入数值字符串。String 示例 使用后缀格式化数值

Query

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

Response

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

显式指定精度

Query

SELECT
    formatReadableQuantity(98765432101234, 0) AS no_decimals,
    formatReadableQuantity(98765432101234, 4) AS four_decimals

Response

┌─no_decimals──┬─four_decimals─────┐
│ 99 trillion  │ 98.7654 trillion  │
└──────────────┴───────────────────┘

formatReadableSize

Introduced in: v1.1.0 给定一个大小 (字节数) ，此函数会返回一个易于读懂、经过四舍五入并带有后缀 (KiB、MiB 等) 的大小字符串。此函数的反向操作是 parseReadableSize、parseReadableSizeOrZero 和 parseReadableSizeOrNull。此函数接受任意数值类型作为输入，但内部会将其转换为 Float64。对于较大的值，结果可能不够理想。语法

formatReadableSize(value[, precision])

别名：FORMAT_BYTES 参数

value — 以字节为单位的大小。Int8 或 Int16 或 Int32 或 Int64 或 UInt8 或 UInt16 或 UInt32 或 UInt64 或 Float32 或 Float64 或 Decimal
precision — 可选。小数点后的位数。默认为 2。const UInt8

返回值 返回带后缀、经过四舍五入且便于阅读的大小字符串。String 示例 格式化文件大小

Query

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

Response

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

显式指定精度

Query

SELECT
    formatReadableSize(192851925, 0) AS no_decimals,
    formatReadableSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals──┐
│ 184 MiB     │ 183.9179 MiB   │
└─────────────┴────────────────┘

formatReadableTimeDelta

引入版本：v20.12.0 给定一个以秒为单位的时间间隔 (delta) 或 INTERVAL 表达式，此函数会将其格式化为包含年/月/日/小时/分钟/秒/毫秒/微秒/纳秒的时间间隔字符串。此函数接受任何数值类型作为输入，但在内部会将其转换为 Float64。对于较大的值，结果可能不够理想。传入 INTERVAL 表达式时，其值会被转换为秒。MONTH 及更大的 Interval 单位 (MONTH、QUARTER、YEAR) 不受支持，因为它们并不表示以秒为单位的固定长度时间间隔。语法

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

参数

column — 具有数值型时间增量的列，或 INTERVAL 表达式。不支持 MONTH 及更大单位的时间间隔。Float64 或 Interval
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 示例 用法示例

Query

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

Response

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

使用最大计量单位

Query

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

Response

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

使用 INTERVAL 表达式

Query

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

Response

┌─time_delta─────────────────────────┐
│ 3 hours, 25 minutes and 45 seconds │
└────────────────────────────────────┘

fuzzQuery

引入版本：v26.2.0 解析给定的查询字符串，并对其施加随机 AST 变更 (fuzzing) 。以字符串形式返回模糊处理后的查询。非确定性：每次调用都可能产生不同的结果。需要 allow_fuzz_query_functions = 1。语法

fuzzQuery(query)

参数

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

返回值 模糊测试后的查询字符串 String 示例 基本示例

Query

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

Response

generateRandomStructure

引入版本：v23.5.0 生成格式为 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 示例 使用示例

Query

SELECT generateRandomStructure()

Response

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

指定列数

Query

SELECT generateRandomStructure(1)

Response

c1 Map(UInt256, UInt16)

使用指定种子

Query

SELECT generateRandomStructure(NULL, 33)

Response

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.0 生成并返回从上一个计数器值开始的连续编号。该函数接受一个字符串参数——序列标识符，以及一个可选的起始值。 server 应配置为使用 Keeper。这些序列存储在 Keeper 节点下的 path 中，该 path 可在 server configuration 的 series_keeper_path 中配置。语法

generateSerialID(series_identifier[, start_value])

参数

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

返回值 返回从上一个计数器值开始的连续数字。UInt64 示例 首次调用

Query

SELECT generateSerialID('id1')

Response

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

第二次调用

Query

SELECT generateSerialID('id1')

Response

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

对列的调用

Query

SELECT *, generateSerialID('id1') FROM test_table

Response

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

使用初始值

Query

SELECT generateSerialID('id2', 100)

Response

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

第二次调用 (带起始值)

Query

SELECT generateSerialID('id2', 100)

Response

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

getClientHTTPHeader

引入版本：v24.5.0 获取 HTTP 请求头的值。如果不存在该请求头，或者当前请求不是通过 HTTP 接口执行的，则该函数返回空字符串。某些 HTTP 请求头 (例如 Authentication 和 X-ClickHouse-*) 会受到限制。

需要启用设置 allow_get_client_http_header该函数要求启用设置 allow_get_client_http_header。出于安全原因，此设置默认未启用，因为某些请求头 (如 Cookie) 可能包含敏感信息。

对于此函数，HTTP 请求头区分大小写。如果该函数在分布式查询的上下文中使用，则只有在发起节点上才会返回非空结果。语法

getClientHTTPHeader(name)

参数

name — HTTP 请求头的名称。String

返回值 返回请求头的值。String 示例 使用示例

Query

SELECT getClientHTTPHeader('Content-Type');

Response

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

getMacro

引入版本：v20.1.0 返回服务器配置文件中某个宏的值。宏在配置文件的 <macros> 部分中定义，即使服务器的主机名很复杂，也可以使用便于识别的名称来区分服务器。如果该函数是在分布式表的上下文中执行的，它会生成一个普通列，其中的值与各个分片相关。语法

getMacro(name)

参数

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

返回值 返回指定 macro 的值。String 示例 基本用法

Query

SELECT getMacro('test');

Response

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

getMaxTableNameLengthForDatabase

首次引入于：v25.1.0 返回指定数据库中表名的最大长度。语法

getMaxTableNameLengthForDatabase(database_name)

参数

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

返回值 返回最长表名的长度，为整数。示例 典型用法

Query

SELECT getMaxTableNameLengthForDatabase('default');

Response

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

getMergeTreeSetting

引入于：v25.6.0 返回 MergeTree 设置的当前值。语法

getMergeTreeSetting(setting_name)

参数

setting_name — 设置名称。String

返回值 返回 MergeTree 设置的当前值。示例 用法示例

Query

SELECT getMergeTreeSetting('index_granularity');

Response

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

getOSKernelVersion

引入版本：v21.11.0 返回包含操作系统内核版本的字符串。语法

getOSKernelVersion()

参数

无。

返回值 返回当前操作系统内核版本。String 示例 使用示例

Query

SELECT getOSKernelVersion();

Response

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

getServerPort

引入版本：v21.10.0 返回给定协议对应的服务器端口号。语法

getServerPort(port_name)

参数

port_name — 端口名称。String

返回值 返回 server 的端口号。UInt16 示例 用法示例

Query

SELECT getServerPort('tcp_port');

Response

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

getServerSetting

首次引入于：v25.6.0 给定服务器设置名称，返回当前设置的值。语法

getServerSetting(setting_name')

参数

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

返回值 返回该服务器设置的当前值。Any 示例 用法示例

Query

SELECT getServerSetting('allow_use_jemalloc_memory');

Response

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

getSetting

引入版本：v20.7.0 返回某个设置的当前值。语法

getSetting(setting_name)

参数

setting_Name — 设置名。const String

返回值 返回该设置的当前值。Any 示例 使用示例

Query

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

Response

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

getSettingOrDefault

自 v24.10.0 起引入返回某个设置的当前值；如果该设置在当前 profile 中未设置，则返回第二个参数指定的默认值。语法

getSettingOrDefault(setting_name, default_value)

参数

setting_name — 设置名称。String
default_value — 若未设置 custom_setting，则返回该值。该值可以是任意数据类型，也可以为 NULL。

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

Query

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

Response

my_value
100
NULL

getSizeOfEnumType

引入版本：v1.1.0 返回给定 Enum 的字段数量。语法

getSizeOfEnumType(x)

参数

x — 类型为 Enum 的值。Enum

返回值 返回输入值为 Enum 的字段个数。UInt8/16 示例 使用示例

Query

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

Response

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

getSubcolumn

引入版本：v23.3.0 接收表达式或标识符，以及表示子列名称的常量字符串。返回从表达式中提取的指定子列。语法

getSubcolumn(nested_value, subcolumn_name)

参数

无。

返回值 示例 getSubcolumn

Query

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

Response

getTypeSerializationStreams

引入版本：v22.6.0 枚举数据类型的 stream 路径。此函数仅供开发使用。语法

getTypeSerializationStreams(col)

参数

col — 用于检测数据类型的列，或数据类型的字符串表示形式。Any

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

Query

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

Response

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

Map

Query

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

Response

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

globalVariable

Introduced in：v20.5.0 接受一个常量字符串参数，并返回同名全局变量的值。此函数仅用于兼容 MySQL，对于 ClickHouse 的正常运行既非必需，也没有实际作用。只定义了少数几个虚拟的全局变量。 Syntax

globalVariable(name)

参数

name — 全局变量名。String

返回值 返回变量 name 的值。Any 示例 globalVariable

Query

SELECT globalVariable('max_allowed_packet')

Response

67108864

hasColumnInTable

引入版本：v1.1.0 检查数据库表中是否存在指定列。对于嵌套数据结构中的元素，该函数会检查相应列是否存在。对于嵌套数据结构本身，该函数返回 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 示例 检查现有列

Query

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

Response

检查不存在的列

Query

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

Response

hasThreadFuzzer

引入版本：v20.6.0 返回 Thread Fuzzer 是否处于启用状态。此函数仅用于测试和调试。语法

hasThreadFuzzer()

参数

无。

返回值 返回 Thread Fuzzer 是否有效。UInt8 示例 检查 Thread Fuzzer 的状态

Query

SELECT hasThreadFuzzer()

Response

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

highlightQuery

Introduced in: v26.5.0 解析 ClickHouse SQL 查询字符串，并返回一组用于语法高亮的高亮范围。每个范围都是一个命名元组，包含起始位置 (以字节为单位) 、结束位置以及高亮类型。高亮类型描述片段在语法中的角色 (关键字、标识符、函数等) ，可用于在 UI 中指定颜色。在 LIKE 和 REGEXP 字符串模式中，元字符和转义字符会分别高亮显示。语法

highlightQuery(query)

参数

query — ClickHouse SQL 查询字符串。String。

返回值 由命名元组 (begin UInt64, end UInt64, type Enum8(...)) 组成的数组，表示高亮范围。Array(Tuple(begin UInt64, end UInt64, type Enum8(...))) 示例简单

Query

SELECT highlightQuery('SELECT 1')

Response

[(0,6,'keyword'),(7,8,'number')]

hostName

引入版本：v20.5.0 返回执行此函数的主机名。如果该函数在远程服务器上执行 (分布式处理) ，则返回远程服务器的名称。如果该函数在分布式表的上下文中执行，则会生成一个常规列，其值对应各个分片。否则，它会产生一个常量值。语法

hostName()

别名：hostname 参数

无。

返回值 返回主机名。String 示例 用法示例

Query

SELECT hostName()

Response

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

icebergBucket

引入版本：v25.5.0 实现了 Iceberg bucket 转换的逻辑语法

icebergBucket(N, value)

参数

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

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

Query

SELECT icebergBucket(5, 1.0 :: Float32)

Response

icebergTruncate

在 v25.3.0 中引入实现了 Iceberg truncate transform 的逻辑：https://iceberg.apache.org/spec/#truncate-transform-details。语法

icebergTruncate(N, value)

参数

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

返回值 与参数类型相同示例示例

Query

SELECT icebergTruncate(3, 'iceberg')

Response

ice

identity

引入版本：v1.1.0 此函数会返回传入的参数，这对调试和测试很有帮助。它可以绕过索引的使用，从而查看全表扫描的性能。查询分析器在查找可用索引时，会忽略 identity 函数中的任何内容，同时也会禁用常量折叠。语法

identity(x)

参数

x — 输入值。Any

返回值 返回原始输入值，不做任何更改。Any 示例 用法示例

Query

SELECT identity(42)

Response

ignore

引入于：v1.1.0 接受任意参数，并始终返回 0。语法

ignore(x)

参数

x — 一个未使用的输入值，传入它仅仅是为了避免语法错误。Any

返回值 始终返回 0。UInt8 示例 用法示例

Query

SELECT ignore(0, 'ClickHouse', NULL)

Response

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

indexHint

引入版本：v1.1.0 此函数用于调试和查看内部信息。它会忽略其参数，并始终返回 1。参数不会被求值。在索引分析过程中，此函数的参数会被视为没有包裹在 indexHint 中。这样一来，你可以根据相应条件选出索引范围内的数据，但不会再按该条件进一步过滤。 ClickHouse 中的索引是稀疏的，因此使用 indexHint 返回的数据会比直接指定相同条件更多。

说明

当你运行：

SELECT * FROM test WHERE key = 123;

ClickHouse 会做两件事：

使用索引查找哪些粒度 (约由 8192 行组成的块) 可能包含 key = 123
读取这些粒度，并逐行过滤，只返回 key = 123 的行

因此，即使它从磁盘读取了 8,192 行，最终也只会返回实际匹配的那 1 行。而当你使用 indexHint 运行：

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

ClickHouse 只会做一件事：

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

它会返回全部 8,192 行，其中包括 key = 456、key = 789 等对应的行。 (也就是恰好存储在同一粒度中的所有内容。) indexHint() 不是用来提升性能的。它是为了调试，以及帮助你理解 ClickHouse 的索引如何工作：

我的条件选中了哪些粒度？
这些粒度中有多少行？
我的索引是否得到了有效利用？

注意：无法使用 indexHint 函数来优化查询。indexHint 函数不会优化查询，因为它不会为查询分析提供任何额外信息。把表达式放在 indexHint 函数中，并不会比不使用 indexHint 更好。indexHint 函数只能用于查看内部信息和调试，并不能提升性能。如果你看到除 ClickHouse 贡献者之外的人在使用 indexHint，那很可能是个错误，应当将其移除。语法

indexHint(expression)

参数

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

返回值 始终返回 1。UInt8 示例 按日期过滤的用法示例

Query

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

Response

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

initialQueryID

Introduced in: v1.1.0 返回初始查询的 ID。查询的其他参数可从 system.query_log 的 initial_query_id 字段中提取。与 queryID 函数不同，initialQueryID 在不同分片上返回相同的结果。语法

initialQueryID()

别名: initial_query_id 参数

无。

返回值 返回初始查询的 ID。String 示例 使用示例

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

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

initialQueryStartTime

引入版本：v25.4.0 返回当前初始查询的开始时间。 initialQueryStartTime 在不同分片上返回相同的结果。语法

initialQueryStartTime()

别名: initial_query_start_time 参数

无。

返回值 返回当前初始查询的开始时间。DateTime 示例 用法示例

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

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

initializeAggregation

引入版本：v20.6.0 根据单个值计算聚合函数的结果。此函数可用于通过组合器 -State 初始化聚合函数。你可以创建聚合函数的状态，并将其插入到类型为 AggregateFunction 的列中，或者将已初始化的聚合结果用作默认值。语法

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

参数

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

返回值 返回传递给该函数的每一行的聚合结果。其返回类型与 initializeAggregation 的第一个参数指定的函数返回类型相同。Any 示例 uniqState 的基本用法

Query

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

Response

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

与 sumState 和 finalizeAggregation 配合使用

Query

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

Response

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

isConstant

引入版本：v20.3.0 返回参数是否为常量表达式。常量表达式是指其结果在查询分析阶段即可确定的表达式，也就是在执行之前就能确定结果的表达式。例如，基于literals的表达式就是常量表达式。此函数主要用于开发、调试和演示。语法

isConstant(x)

参数

x — 要检查的表达式。Any

返回值 如果 x 是常量，则返回 1；如果 x 不是常量，则返回 0。UInt8 示例 常量表达式

Query

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

Response

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

含函数的常量

Query

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

Response

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

非常量表达式

Query

SELECT isConstant(number)
FROM numbers(1)

Response

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

now() 函数的行为

Query

SELECT isConstant(now())

Response

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

isDecimalOverflow

引入版本：v20.8.0 检查十进制数的位数是否过多，导致其无法适配给定精度的 Decimal 数据类型。语法

isDecimalOverflow(value[, precision])

参数

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

返回值 如果 Decimal 值的位数超出其精度允许的范围，则返回 1；如果 Decimal 值符合指定精度，则返回 0。UInt8 示例 使用示例

Query

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

Response

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

joinGet

引入版本：v18.16.0 允许你像从字典中取值一样从表中提取数据。使用指定的连接键从 Join 表中获取数据。

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

语法

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 示例 用法示例

Query

CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGet(db_test.id_val, 'val', toUInt32(1));

Response

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

与当前数据库中的表一起使用

Query

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

Response

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

将数组用作连接键

Query

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', 1, 11);

Response

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

joinGetOrNull

引入版本：v20.4.0 允许你像从字典中取值一样从表中提取数据。使用指定的连接键从 Join 表中获取数据。与 joinGet 不同的是，当键不存在时，它返回 NULL。

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

语法

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 示例 使用示例

Query

CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGetOrNull(db_test.id_val, 'val', toUInt32(1)), joinGetOrNull(db_test.id_val, 'val', toUInt32(999));

Response

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

lowCardinalityIndices

引入版本：v18.12.0 返回某个值在 LowCardinality 列的字典中的位置。位置从 1 开始。由于 LowCardinality 会为每个分片分别维护字典，因此同一个值在不同的分片中，此函数可能返回不同的位置。语法

lowCardinalityIndices(col)

参数

col — 一个低基数列。LowCardinality

返回值 该值在当前数据分片的字典中的位置。UInt64 示例 用法示例

Query

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

-- 创建两个分片：

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityIndices(s) FROM test;

Response

┌─s──┬─lowCardinalityIndices(s)─┐
│ ab │                        1 │
│ cd │                        2 │
│ ab │                        1 │
│ ab │                        1 │
│ df │                        3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
│ ef │                        1 │
│ cd │                        2 │
│ ab │                        3 │
│ cd │                        2 │
│ ef │                        1 │
└────┴──────────────────────────┘

lowCardinalityKeys

引入版本：v18.12.0 返回 LowCardinality 列的字典值。如果块的大小小于或大于字典大小，结果将被截断，或用默认值补齐。由于 LowCardinality 的字典是按分片分别维护的，因此此函数在不同的分片中可能返回不同的字典值。语法

lowCardinalityKeys(col)

参数

col — 低基数列。LowCardinality

返回值 返回字典键。UInt64 示例 lowCardinalityKeys

Query

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

-- 创建两个分片：

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

Response

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

materialize

引入版本：v1.1.0 将常量转换为仅包含单一值的普通列。普通列和常量在内存中的表示方式不同。对于普通参数和常量参数，函数通常会执行不同的代码路径，但结果一般应当相同。此函数可用于调试这种行为。语法

materialize(x)

参数

x — 常量。Any

返回值 返回一个包含该常量值的普通列。Any 示例 用法示例

Query

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

Response

2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String

minSampleSizeContinuous

引入版本：v23.10.0 计算在 A/B 测试中比较两个样本的连续指标均值时所需的最小样本量。使用这篇文章中描述的公式。假设实验组和对照组的样本量相同。返回单个组所需的样本量 (即整个实验所需的样本量是返回值的两倍) 。还假设实验组和对照组中测试指标的方差相同。语法

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 - II 类错误的概率) 。(U)Int* 或 Float*
alpha — 检验所需的显著性水平 (I 类错误的概率) 。(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

Query

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

Response

(616.2931945826209,108.8825,115.6175)

minSampleSizeConversion

引入版本：v22.6.0 计算在 A/B 测试中比较两个样本的转化率 (比例) 时所需的最小样本量。使用这篇文章中描述的公式。假设 treatment 组和 control 组的规模相同。返回单个组所需的样本量 (即整个实验所需的样本量是返回值的两倍) 。语法

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

Query

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

Response

(3396.077603219163,0.22,0.28)

neighbor

引入版本：v20.1.0 返回当前行相对指定偏移量处的某列值。此函数已弃用，且容易出错，因为它基于数据块的物理顺序进行操作，而该顺序可能与用户预期的逻辑顺序不一致。建议改用适当的窗口函数。可通过设置 allow_deprecated_error_prone_window_functions = 1 启用此函数。语法

neighbor(column, offset[, default_value])

参数

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

返回值 返回指定偏移量处的值；如果超出范围，则返回默认值。Any 示例 用法示例

Query

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

Response

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

使用默认值

Query

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

Response

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

normalizeQuery

引入版本：v20.8.0 将字面量、由字面量组成的序列以及复杂别名 (包含空白字符、两个以上数字，或长度至少为 36 字节，例如 UUIDs) 替换为占位符 ?。语法

normalizeQuery(x)

参数

x — 字符序列。String

返回值 返回用占位符替换后的给定字符序列。String 示例 使用示例

Query

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

Response

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

normalizeQueryKeepNames

引入版本：v21.2.0 将字面量及其序列替换为占位符 ?，但不会替换复杂别名 (包含空白字符、超过两位数字，或长度至少为 36 字节，例如 UUIDs) 。这有助于更好地分析复杂的查询日志。语法

normalizeQueryKeepNames(x)

参数

x — 字符序列。String

返回值 返回给定字符序列的占位符形式。String 示例 使用示例

Query

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

Response

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

normalizedQueryHash

引入版本：v20.8.0 对于相似查询，在忽略字面量值的情况下会返回相同的 64 位哈希值。这有助于分析查询日志。语法

normalizedQueryHash(x)

参数

x — 字符序列。String

返回值 返回一个 64 位哈希值。UInt64 示例 使用示例

Query

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

Response

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

normalizedQueryHashKeepNames

引入版本：v21.2.0 与 normalizedQueryHash 类似，它会为相似查询返回相同的 64 位哈希值，且不包含字面量的值；但不同的是，它不会在哈希计算前将复杂别名 (包含空白字符、超过两个数字，或长度至少为 36 字节，例如 UUIDs) 替换为占位符。这有助于分析查询日志。语法

normalizedQueryHashKeepNames(x)

参数

x — 字符序列。String

返回值 返回一个 64位哈希值。UInt64 示例 用法示例

Query

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

Response

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

obfuscateQuery

引入版本：v26.4.0 通过将标识符替换为随机词、将字面量替换为随机值，同时保留查询结构，对 SQL 查询进行混淆。此函数适合在出于调试目的将查询写入日志或共享之前，对其进行匿名化处理。即使输入的查询相同，不同的行也会生成不同的混淆结果，这有助于在处理多个查询时保护隐私。可选的 tag 参数可防止在同一函数调用在一个查询中被多次使用时发生 common subexpression elimination。这样可确保每次调用都会生成不同的混淆结果。特性：

将表名、列名和别名替换为随机词
将数字和字符串字面量替换为随机值
保留整体查询结构和 SQL 语法
对不同的行生成不同的结果

语法

obfuscateQuery(query[, tag])

参数

query — 要混淆处理的 SQL 查询。String
tag — 可选。一个值，用于在多次使用相同函数调用时防止公共子表达式消除。

返回值 混淆后的查询，其中标识符和字面量会被替换，同时保留原始查询的结构。String 示例 基本用法

Query

SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')

Response

SELECT fruit, number FROM table WHERE number > 12

使用标签防止公共子表达式消除

Query

SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)

Response

SELECT a FROM b, SELECT c FROM d

不同的行会产生不同的结果

Query

SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b

Response

A B

obfuscateQueryWithSeed

引入版本：v26.4.0 使用指定的 seed 对 SQL 查询进行混淆，以获得确定性的结果。与 obfuscateQuery() 不同，此函数在给定相同 seed 时会产生确定性的结果。当你需要在多次运行之间保持混淆结果一致，或希望为测试或调试复现相同的混淆查询时，这个函数非常有用。特性：

基于提供的 seed 进行确定性混淆
相同的 seed 始终会产生相同的混淆结果
不同的 seed 会产生不同的结果
与 obfuscateQuery() 一样保留查询结构

使用场景：

可复现的测试用例
在多次运行之间保持一致的匿名化
使用一致的混淆查询进行调试

语法

obfuscateQueryWithSeed(query, seed)

参数

query — 要混淆的 SQL 查询。String
seed — 用于混淆的种子值。相同的种子会产生确定性的结果。Integer 或 String

返回值 根据提供的种子确定性生成的混淆后查询。String 示例 使用整数种子进行确定性混淆

Query

SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)

Response

SELECT fruit FROM table

使用字符串种子进行确定性混淆

Query

SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')

Response

SELECT a, b FROM c

相同的 seed 会产生相同的结果

Query

SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)

Response

true

parseReadableSize

引入版本：v24.6.0 给定一个包含字节大小且以 B、KiB、KB、MiB、MB 等为单位的字符串 (即 ISO/IEC 80000-13 或十进制字节单位) ，此函数返回对应的字节数。如果函数无法解析输入值，则会抛出异常。此函数的逆向操作是 formatReadableSize 和 formatReadableDecimalSize。语法

parseReadableSize(x)

参数

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

返回值 返回字节数，并向上取整到最接近的整数。UInt64 示例 使用示例

Query

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

Response

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

parseReadableSizeOrNull

Introduced in: v24.6.0 给定一个包含字节大小的字符串，并使用 B、KiB、KB、MiB、MB 等单位 (即 ISO/IEC 80000-13 或十进制字节单位) ，此函数会返回对应的字节数。如果函数无法解析输入值，则返回 NULL。此函数的逆运算为 formatReadableSize 和 formatReadableDecimalSize。 Syntax

parseReadableSizeOrNull(x)

参数

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

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

Query

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

Response

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

parseReadableSizeOrZero

Introduced in：v24.6.0 给定一个包含字节大小以及 B、KiB、KB、MiB、MB 等单位的字符串 (即 ISO/IEC 80000-13 或十进制字节单位) ，该函数返回对应的字节数。如果该函数无法解析输入值，则返回 0。该函数的逆操作为 formatReadableSize 和 formatReadableDecimalSize。 Syntax

parseReadableSizeOrZero(x)

参数

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

返回值 返回字节数，向上取整到最近的整数；如果无法解析输入，则返回 0。UInt64 示例 使用示例

Query

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

Response

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

parseTimeDelta

引入版本：v22.7.0 解析由一串数字及其后类似时间单位的内容组成的序列。时间增量字符串使用以下时间单位表示：

years, year, yr, y
months, month, mo
weeks, week, w
days, day, d
hours, hour, hr, h
minutes, minute, min, m
seconds, second, sec, s
milliseconds, millisecond, millisec, ms
microseconds, microsecond, microsec, μs, µs, us
nanoseconds, nanosecond, nanosec, ns

多个时间单位可以用分隔符 (空格、;、-、+、,、:) 组合在一起。年和月的长度为近似值：1 年按 365 天计算，1 个月按 30.5 天计算。语法

parseTimeDelta(timestr)

参数

timestr — 由一串数字加上类似时间单位的内容组成的字符串。String

返回值 秒数。Float64 示例 使用示例

Query

SELECT parseTimeDelta('11s+22min')

Response

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

复合时间单位

Query

SELECT parseTimeDelta('1yr2mo')

Response

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

partitionId

引入版本：v21.4.0 计算分区 ID。

此函数较慢，不应在大量行上调用。

语法

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

别名: partitionID 参数

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

返回值 返回该行所属的分区 ID。String 示例 用法示例

Query

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;

Response

┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

queryID

引入版本：v21.9.0 返回当前查询的 ID。查询的其他参数可以从 system.query_log 表中的 query_id 字段提取。与 initialQueryID 函数不同，queryID 在不同分片上可能返回不同的结果。语法

queryID()

别名: query_id 参数

无。

返回值 返回当前查询的 ID。String 示例 使用示例

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

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

revision

引入版本：v22.7.0 返回当前 ClickHouse server 的修订号。语法

revision()

参数

无。

返回值 返回当前 ClickHouse server 的修订版本。UInt32 示例 使用示例

Query

SELECT revision()

Response

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

rowNumberInAllBlocks

引入版本：v1.1.0 为处理的每一行返回唯一的行号。语法

rowNumberInAllBlocks()

参数

无。

返回值 返回该行在数据块中的序号，从 0 开始。UInt64 示例 用法示例

Query

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

Response

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

rowNumberInBlock

引入版本：v1.1.0 对于 rowNumberInBlock 处理的每个块，返回当前行的编号。返回的编号在每个块内都从 0 开始。语法

rowNumberInBlock()

参数

无。

返回值 返回数据块中行的序号，从 0 开始。UInt64 示例 用法示例

Query

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

Response

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

runningAccumulate

引入版本：v1.1.0 对数据块中每一行的聚合函数状态进行累积。

已弃用每当进入新的数据块时，状态都会被重置。由于这种行为容易出错，该函数已被弃用，建议改用窗口函数。你可以使用设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

语法

runningAccumulate(agg_state[, grouping])

参数

agg_state — 聚合函数状态。AggregateFunction
grouping — 可选。分组键。如果 grouping 的值发生变化，函数状态将被重置。它可以是任意一种定义了相等运算符的受支持数据类型。Any

返回值 返回每一行的累积结果。Any 示例 使用 initializeAggregation 的使用示例

Query

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

Response

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

runningConcurrency

引入版本：v21.3.0 计算并发事件的数量。每个事件都有开始时间和结束时间。开始时间计入事件，而结束时间不计入事件。开始时间列和结束时间列必须具有相同的数据类型。该函数会针对每个事件的开始时间，计算处于活动状态的 (并发) 事件总数。

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

已弃用建议改用窗口函数。

语法

runningConcurrency(start, end)

参数

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

返回值 返回每个事件开始时刻的并发事件数。UInt32 示例 用法示例

Query

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

Response

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

runningDifference

引入版本：v1.1.0 计算数据块中相邻两行值之间的差值。第一行返回 0，后续各行返回与前一行的差值。

已弃用该函数仅返回当前正在处理的数据块内的差值。由于这种行为容易出错，该函数已被弃用。建议改用窗口函数。你可以使用设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

函数的结果取决于受影响的数据块以及块内数据的顺序。计算 runningDifference() 时的行顺序可能与最终返回给用户的行顺序不同。为避免这种情况，你可以创建一个带有 ORDER BY 的子查询，并在子查询外部调用该函数。请注意，块大小会影响结果。 runningDifference 的内部状态会在每个新块开始时重置。语法

runningDifference(x)

参数

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

返回值 返回相邻值之间的差值，首行为 0。示例 用法示例

Query

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

Response

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

块大小影响示例

Query

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

Response

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

runningDifferenceStartingWithFirstValue

引入版本：v1.1.0 计算数据块中相邻行值之间的差值，但与 runningDifference 不同，它返回的是第一行的实际值，而不是 0。

已弃用仅返回当前处理的数据块内的差值。由于这种行为容易导致错误，该函数已被弃用。建议改用窗口函数。你可以使用设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

语法

runningDifferenceStartingWithFirstValue(x)

参数

x — 用于计算逐行差分的列。Any

返回值 返回相邻值之间的差值；对于第一行，返回该行的值。Any 示例 使用示例

Query

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

Response

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

serverUUID

引入版本：v20.1.0 返回服务器首次启动时生成的随机唯一 UUID (v4) 。该 UUID 会被持久保存，也就是说，服务器第二次、第三次等后续启动时返回的都是同一个 UUID。语法

serverUUID()

参数

无。

返回值 返回服务器的随机 UUID。UUID 示例 使用示例

Query

SELECT serverUUID();

Response

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

shardCount

引入版本：v21.9.0 返回分布式查询的分片总数。如果查询不是分布式查询，则返回常量值 0。语法

shardCount()

参数

无。

返回值 返回分片总数或 0。UInt32 示例 用法示例

Query

-- 参见上方的 shardNum() 示例，该示例同时演示了 shardCount() 的用法
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

Response

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

shardNum

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

shardNum()

参数

无。

返回值 返回分片索引或常量 0。UInt32 示例 使用示例

Query

CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;

Response

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

showCertificate

引入版本：v22.6.0 如果已配置，将显示当前服务器的 SSL 证书信息。有关如何将 ClickHouse 配置为使用 OpenSSL 证书验证连接的更多信息，请参见配置 TLS。语法

showCertificate()

参数

无。

返回值 返回与已配置的 SSL 证书相关的键值对映射。Map(String, String) 示例 使用示例

Query

SELECT showCertificate() FORMAT LineAsString;

Response

{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May  7 17:01:21 2024 GMT','not_after':'May  7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}

sleep

引入版本：v1.1.0 按指定秒数暂停查询的执行。该函数主要用于测试和调试。通常不应在生产环境中使用 sleep() 函数，因为它可能会对查询性能和系统响应速度产生负面影响。不过，在以下场景中它可能会很有用：

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

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

出于安全原因，该函数只能在 default 用户的 profile 中执行 (且已启用 allow_sleep) 。语法

sleep(seconds)

参数

seconds — 暂停查询执行的秒数，最长为 3 秒。可使用浮点数来指定小数秒。const UInt* 或 const Float*

返回值 返回 0。UInt8 示例 使用示例

Query

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

Response

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

sleepEachRow

Introduced in: v1.1.0 将查询执行按结果集中的每一行暂停指定的秒数。 sleepEachRow() 函数主要用于测试和调试，类似于 sleep() 函数。它可以在处理每一行时模拟延迟或插入暂停，这在以下场景中很有用：

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

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

语法

sleepEachRow(seconds)

参数

seconds — 结果集中的每一行在查询执行时暂停的秒数，最长为 3 秒。可以使用浮点值来指定秒的小数部分。const UInt* 或 const Float*

返回值 每一行都返回 0。UInt8 示例 用法示例

Query

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

Response

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

structureToCapnProtoSchema

引入版本：v23.8.0 用于将 ClickHouse 表结构转换为 CapnProto 格式 schema 的函数语法

structureToCapnProtoSchema(table_structure, message)

参数

无。

返回值 示例 random

Query

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

Response

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

structureToProtobufSchema

引入版本：v23.8.0 将 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

返回值 返回采用 proto3 语法、与输入 ClickHouse 结构对应的 Protobuf schema 定义。String 示例 将 ClickHouse 结构转换为 Protobuf schema

Query

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

Response

syntax = "proto3";

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

tcpPort

引入版本：v20.12.0 返回服务器正在监听的原生接口 TCP 端口号。如果在分布式表的上下文中执行，此函数会生成一个普通列，其值对应各个分片。否则会产生一个常量值。语法

tcpPort()

参数

无。

返回值 返回 TCP 端口号。UInt16 示例 使用示例

Query

SELECT tcpPort()

Response

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

throwIf

引入版本：v1.1.0 如果参数 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

返回值 如果条件为 false，则返回 0；如果条件为 true，则抛出异常。UInt8 示例 用法示例

Query

SELECT throwIf(number = 3, 'Too many') FROM numbers(10);

Response

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.

toColumnTypeName

引入版本：v1.1.0 返回给定值的数据类型内部名称。与函数 toTypeName 不同，返回的数据类型可能包含内部包装列，如 Const 和 LowCardinality。语法

toColumnTypeName(value)

参数

value — 要返回其内部数据类型名称的值。Any

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

Query

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

Response

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

toTypeName

引入版本：v1.1.0 返回传入参数的类型名称。如果传入 NULL，该函数会返回类型 Nullable(Nothing)，对应于 ClickHouse 内部对 NULL 的表示。语法

toTypeName(x)

参数

x — 任意类型的值。Any

返回值 返回输入值的数据类型名称。String 示例 使用示例

Query

SELECT toTypeName(123)

Response

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

tokenizeQuery

引入版本：v26.5.0 将 ClickHouse SQL 查询字符串标记化，并返回由标记组成的数组。每个标记都是一个命名元组，包含起始位置 (以字节为单位) 、结束位置以及标记类型。语法

tokenizeQuery(query)

参数

query — 一个 ClickHouse SQL 查询字符串。String。

返回值 一个命名元组数组 (begin UInt64, end UInt64, type Enum8(...))，表示该查询的各个标记。Array(Tuple(begin UInt64, end UInt64, type Enum8(...))) 示例 simple

Query

SELECT tokenizeQuery('SELECT 1')

Response

[(0,6,'BareWord'),(6,7,'Whitespace'),(7,8,'Number')]

transactionID

引入版本：v22.6.0 返回事务的 ID。

此函数属于 Experimental 功能集的一部分。如需启用实验性事务支持，请将以下设置添加到你的配置文件中：

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

更多信息请参见事务 (ACID) 支持页面。

语法

transactionID()

参数

无。

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

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

示例 用法示例

Query

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

Response

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

transactionLatestSnapshot

引入版本：v22.6.0 返回可用于读取的某个事务的最新快照 (提交序列号) 。

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

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

更多信息请参见页面事务 (ACID) 支持。

语法

transactionLatestSnapshot()

参数

无。

返回值 返回事务的最新快照 (CSN) 。UInt64 示例 使用示例

Query

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

Response

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

transactionOldestSnapshot

引入版本：v22.6.0 返回某个正在运行的事务可见的最早快照 (提交序列号) 。

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

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

更多信息请参见事务 (ACID) 支持页面。

语法

transactionOldestSnapshot()

参数

无。

返回值 返回事务中最早的快照 (CSN) 。UInt64 示例 用法示例

Query

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

Response

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

transform

在 v1.1.0 中引入根据显式定义的元素映射关系，将一个值转换为另一个值。此函数有两种形式：

transform(x, array_from, array_to, default) - 使用映射数组转换 x，对未匹配的元素返回默认值
transform(x, array_from, array_to) - 执行相同的转换，但如果未找到匹配项，则返回原始 x

该函数会在 array_from 中查找 x，并返回 array_to 中相同索引位置上的对应元素。如果在 array_from 中未找到 x，则返回 default 值 (4 参数版本) 或原始 x (3 参数版本) 。如果 array_from 中存在多个匹配元素，则返回与第一个匹配项对应的元素。要求：

array_from 和 array_to 必须包含相同数量的元素
对于 4 参数版本：transform(T, Array(T), Array(U), U) -> U，其中 T 和 U 可以是不同但兼容的类型
对于 3 参数版本：transform(T, Array(T), Array(T)) -> T，其中所有类型都必须相同

语法

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

Query

SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC

Response

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

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

Query

SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10

Response

┌─s──────────────┬───────c─┐
│                │ 2906259 │
│ www.yandex     │  867767 │
│ ███████.ru     │  313599 │
│ mail.yandex.ru │  107147 │
│ ██████.ru      │  100355 │
│ █████████.ru   │   65040 │
│ news.yandex.ru │   64515 │
│ ██████.net     │   59141 │
│ example.com    │   57316 │
└────────────────┴─────────┘

uniqThetaIntersect

引入版本：v22.9.0 对两个 uniqThetaSketch 对象进行交集计算 (集合运算 ∩) ，结果是一个新的 uniqThetaSketch。语法

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

参数

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

返回值 新的 uniqThetaSketch，其中包含交集结果。UInt64 示例 使用示例

Query

SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

Response

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

uniqThetaNot

引入版本：v22.9.0 对两个 uniqThetaSketch 对象执行 a_not_b 计算 (集合运算 ×) ，返回一个新的 uniqThetaSketch。语法

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

参数

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

返回值 返回一个新的 uniqThetaSketch，表示 a_not_b 的结果。UInt64 示例 用法示例

Query

SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);

Response

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

uniqThetaUnion

在 v22.9.0 中引入对两个 uniqThetaSketch 对象进行并集计算 (集合运算 ∪) ，结果为一个新的 uniqThetaSketch。语法

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

参数

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

返回值 返回一个新的 uniqThetaSketch，其中包含并集运算结果。UInt64 示例 用法示例

Query

SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

Response

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

运行时间

引入版本：v1.1.0 返回服务器的运行时间，单位为秒。如果在分布式表中执行，此函数会生成一个普通列，其值对应每个分片。否则，它会生成一个常量值。语法

uptime()

参数

无。

返回值 返回服务器的运行时间 (以秒为单位) 。UInt32 示例 使用示例

Query

SELECT uptime() AS Uptime

Response

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

variantElement

引入版本：v25.2.0 从 Variant 列中提取指定类型的列。语法

variantElement(variant, type_name[, default_value])

参数

variant — Variant 列。Variant
type_name — 要提取的 Variant 类型名称。String
default_value — 如果 variant 中不存在指定的 Variant 类型，则使用该默认值。可以是任意类型。可选。Any

返回值 返回从 Variant 列中提取出的指定 Variant 类型的列。Any 示例 使用示例

Query

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;

Response

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

variantType

自 v24.2.0 起引入返回 Variant 列中每一行的 Variant 类型名称。如果该行为 NULL，则返回 ‘None’。语法

variantType(variant)

参数

variant — Variant 列。Variant

返回值 返回一个 Enum 列，表示每一行的 Variant 类型名称。Enum 示例 用法示例

Query

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;

Response

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

version

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

version()

参数

无。

返回值 返回当前的 ClickHouse 版本。String 示例 用法示例

Query

SELECT version()

Response

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

visibleWidth

引入版本：v1.1.0 计算以文本格式 (制表符分隔) 将值输出到控制台时的大致宽度。系统使用该函数来实现 Pretty formats。在 Pretty formats 中，NULL 表示为与 NULL 对应的字符串。语法

visibleWidth(x)

参数

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

返回值 返回该值以文本格式显示时的近似宽度。UInt64 示例 计算 NULL 的可见宽度

Query

SELECT visibleWidth(NULL)

Response

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

zookeeperSessionUptime

引入版本：v21.11.0 返回当前 ZooKeeper 会话的运行时间 (以秒为单位) 。语法

zookeeperSessionUptime()

参数

无。

返回值 返回当前 ZooKeeper 会话的运行时间 (以秒为单位) 。UInt32 示例 使用示例

Query

SELECT zookeeperSessionUptime();

Response

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

最后修改于 2026年7月2日

随机数用于生成随机数的函数文档

​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

​highlightQuery

​hostName

​icebergBucket

​icebergTruncate

​identity

​ignore

​indexHint

​initialQueryID

​initialQueryStartTime

​initializeAggregation

​isConstant

​isDecimalOverflow

​joinGet

​joinGetOrNull

​lowCardinalityIndices

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

highlightQuery

hostName

icebergBucket

icebergTruncate

identity

ignore

indexHint

initialQueryID

initialQueryStartTime

initializeAggregation

isConstant

isDecimalOverflow

joinGet

joinGetOrNull

lowCardinalityIndices