其他函数

注意

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

FQDN

引入于: v20.1

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

语法

fqdn()

别名: fullHostName

参数

无。

返回值

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

示例

使用示例

SELECT fqdn()

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

MACNumToString

引入于：v1.1

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

语法

MACNumToString(num)

参数

num — UInt64 数字。 UInt64

返回值

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

示例

使用示例

SELECT MACNumToString(149809441867716) AS mac_address;

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

MACStringToNum

引入于：v1.1

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

语法

MACStringToNum(s)

参数

s — MAC 地址字符串。 String

返回值

返回 UInt64 数字。 UInt64

示例

使用示例

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

1108152157446

MACStringToOUI

引入于：v1.1

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

语法

MACStringToOUI(s)

参数

s — MAC 地址字符串。 String

返回值

前三个八位字节作为 UInt64 数字。 UInt64

示例

使用示例

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

__applyFilter

引入于: v25.10

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

语法

__applyFilter(filter_name, key)

参数

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

返回值

如果应过滤该键，则为 False Bool

示例

This function is not supposed to be used in user queries. It might be added to query plan during optimization.

__patchPartitionID

引入于：v25.5

内部函数。接收一个部分的名称和补丁部分列名的哈希值。返回补丁部分的划分名称。参数必须是正确的部件名称，否则行为未定义。

语法

参数

无。

返回值

示例

authenticatedUser

引入于：v25.11

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

语法

authenticatedUser()

别名: authUser

参数

无。

返回值

经过身份验证的用户名。 String

示例

使用示例

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

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

bar

引入于：v1.1

构建条形图。当 x = max 时，绘制一个宽度与 (x - min) 成比例且等于 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 中，查询以块（块）处理。此函数返回调用该函数时块的大小（行数）。

语法

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 模型。

语法

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 旨在具有感知均匀性，同时保持计算成本低廉。

转换包括以下阶段

从 OKLab 到线性 sRGB 的转换。
从线性 sRGB 到伽马编码 sRGB 的转换。

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

有关 OKLab 颜色空间及其与 sRGB 的关系，请参阅 https://mdn.org.cn/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。
OKLab 到线性 sRGB
线性 sRGB 到 sRGB

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

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

语法

colorOKLCHToSRGB(tuple [, gamma])

参数

tuple — 一个包含三个数值 L、C、H 的元组，其中 L 的范围是 [0...1]，C >= 0，并且 H 的范围是 [0...360]。 Tuple(Float64, Float64, Float64)
gamma — 可选。用于通过对每个通道 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 (绿-红轴) 和 b (蓝-黄轴)。OKLab 的设计旨在感知上统一，同时保持计算成本低廉。

转换包括两个阶段

sRGB 到线性 sRGB
线性 sRGB 到 OKLab

语法

colorSRGBToOKLAB(tuple[, gamma])

参数

tuple — 包含三个值 R、G、B 的元组，范围为 [0...255]。 Tuple(UInt8, UInt8, UInt8)
gamma — 可选。用于通过将 (x / 255)^gamma 应用于每个通道 x 来线性化 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 值不为正数，则行为未定义。

注意

OKLCH 是 OKLab 色彩空间的圆柱版本。它的三个坐标是 L（亮度，范围为 [0...1]）、C（色度，>= 0）和 H（以度为单位的色相，范围为 [0...360]）。OKLab/OKLCH 的设计旨在感知上统一，同时保持计算成本低廉。

转换包括三个阶段

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

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

语法

colorSRGBToOKLCH(tuple[, gamma])

参数

tuple — 包含三个值 R、G、B 的元组，范围为 [0...255]。 Tuple(UInt8, UInt8, UInt8)
gamma — 可选。用于通过将 (x / 255)^gamma 应用于每个通道 x 来线性化 sRGB 的指数。默认值为 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

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

注意

此函数考虑了十进制值的刻度，即它计算底层整数类型的结果，即 (value * scale)。

例如

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

提示

可以使用 countDigits(x) > 18 检查 Decimal64 的十进制溢出，但它比 isDecimalOverflow 慢。

语法

countDigits(x)

参数

x — 一个整数或十进制值。 (U)Int* 或 Decimal

返回值

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

示例

使用示例

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

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

currentDatabase

引入于：v1.1

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

另请参阅 SET 语句。

语法

currentDatabase()

别名：current_database、SCHEMA、DATABASE

参数

无。

返回值

返回当前数据库名称。 String

示例

使用示例

SELECT currentDatabase()

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

currentProfiles

引入于: v21.9

返回当前用户的设置配置文件数组。

语法

currentProfiles()

参数

无。

返回值

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

示例

使用示例

SELECT currentProfiles();

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

currentQueryID

引入于：v

返回当前查询 ID。

语法

currentQueryID()

别名：current_query_id

参数

无。

返回值

示例

SELECT currentQueryID();

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

currentRoles

引入于: v21.9

返回分配给当前用户的角色数组。

语法

currentRoles()

参数

无。

返回值

返回分配给当前用户的角色数组。 Array(String)

示例

使用示例

SELECT currentRoles();

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

currentSchemas

引入于：v23.7

与函数 currentDatabase 相同，但

接受一个布尔参数，该参数将被忽略
将数据库名称作为单个值的数组返回。

函数 currentSchemas 仅存在为了与 PostgreSQL 兼容。请使用 currentDatabase 代替。

另请参阅 SET 语句。

语法

currentSchemas(bool)

别名：current_schemas

参数

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

返回值

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

示例

使用示例

SELECT currentSchemas(true)

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

currentUser

引入于: v20.1

返回当前用户名。在分布式查询的情况下，返回发起查询的用户的名称。

语法

currentUser()

别名：current_user、user

参数

无。

返回值

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

示例

使用示例

SELECT currentUser()

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

defaultProfiles

引入于: v21.9

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

语法

defaultProfiles()

参数

无。

返回值

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

示例

使用示例

SELECT defaultProfiles();

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

defaultRoles

引入于: v21.9

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

语法

defaultRoles()

参数

无。

返回值

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

示例

使用示例

SELECT defaultRoles();

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

defaultValueOfArgumentType

引入于：v1.1

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

语法

defaultValueOfArgumentType(expression)

参数

expression — 任意类型的值或产生任意类型值的表达式。 Any

返回值

返回数字的 0，字符串的空字符串或可为空类型的 NULL。 UInt8 或 String 或 NULL

示例

使用示例

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

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

可为空示例

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

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

defaultValueOfTypeName

引入于：v1.1

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

语法

defaultValueOfTypeName(type)

参数

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

返回值

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

示例

使用示例

SELECT defaultValueOfTypeName('Int8');

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

可为空示例

SELECT defaultValueOfTypeName('Nullable(Int8)');

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

displayName

引入于：v22.11

返回 config 中的 display_name 的值，或者如果没有设置，则返回服务器的完全限定域名 (FQDN)。

语法

displayName()

参数

无。

返回值

返回 config 中的 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()

参数

无。

返回值

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

示例

使用示例

SELECT enabledProfiles();

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

enabledRoles

引入于: v21.9

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

语法

enabledRoles()

参数

无。

返回值

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

示例

使用示例

SELECT enabledRoles();

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

errorCodeToName

引入于：v20.12

返回数字 ClickHouse 错误代码的文本名称。从数字错误代码到错误名称的映射可在此处找到。

语法

errorCodeToName(error_code)

参数

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

返回值

返回 error_code 的文本名称。 String

示例

使用示例

SELECT errorCodeToName(252);

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

file

引入于：v21.3

将文件读取为字符串并将其数据加载到指定的列中。不会解释文件内容。

另请参阅 file 表函数。

语法

file(path[, default])

参数

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

返回值

返回文件内容作为字符串。 String

示例

将文件插入到表中

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

filesystemAvailable

引入于: v20.1

返回托管数据库持久性的文件系统中的可用空间量。返回的值始终小于总可用空间（filesystemUnreserved），因为操作系统会保留一些空间。

语法

filesystemAvailable([disk_name])

参数

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

返回值

返回剩余可用空间量（以字节为单位）。 UInt64

示例

使用示例

SELECT formatReadableSize(filesystemAvailable()) AS "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（包含这些类型中的任何一种类型的变体）。

返回值

翻转坐标的几何体。返回类型与输入类型匹配。 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)]

polygon

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

引入于：v

返回给定 SQL 查询的格式化版本，可能包含多行。如果发生解析错误，则抛出异常。 [示例:multiline]

语法

formatQuery(query)

参数

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

返回值

格式化的查询 String

示例

multiline

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

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

formatQueryOrNull

引入于：v

返回给定 SQL 查询的格式化版本，可能包含多行。如果发生解析错误，则返回 NULL。 [示例:multiline]

语法

formatQueryOrNull(query)

参数

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

返回值

格式化的查询 String

示例

multiline

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

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

formatQuerySingleLine

引入于：v

类似于 formatQuery()，但返回的格式化字符串不包含换行符。如果发生解析错误，则抛出异常。 [示例:multiline]

语法

formatQuerySingleLine(query)

参数

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

返回值

格式化的查询 String

示例

multiline

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

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

formatQuerySingleLineOrNull

引入于：v

类似于 formatQuery()，但返回的格式化字符串不包含换行符。如果发生解析错误，则返回 NULL。 [示例:multiline]

语法

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

formatReadableDecimalSize

引入于：v22.11

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

此函数的相反操作是 parseReadableSize。

语法

formatReadableDecimalSize(x)

参数

x — 字节大小。 UInt64

返回值

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

示例

格式化文件大小

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

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

formatReadableQuantity

引入于：v20.10

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

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

语法

formatReadableQuantity(x)

参数

x — 要格式化的数字。 UInt64

返回值

返回带有后缀的四舍五入的数字作为字符串。 String

示例

格式化带有后缀的数字

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

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 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

给定一个时间间隔（秒），此函数返回一个带有年/月/日/小时/分钟/秒/毫秒/微秒/纳秒的时间间隔作为字符串。

此函数接受任何数值类型作为输入，但在内部将其转换为 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                                  │
└────────────┴─────────────────────────────────────────────────────────────────┘

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 — 随机种子，用于生成稳定的结果。如果未指定种子或设置为 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 节点下的路径中，该路径可以在服务器配置中的 path 中配置。

语法

generateSerialID(series_identifier[, start_value])

参数

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

返回值

从先前的计数器值开始返回连续数字。 UInt64

示例

首次调用

SELECT generateSerialID('id1')

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

第二次调用

SELECT generateSerialID('id1')

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

列调用

SELECT *, generateSerialID('id1') FROM test_table

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

带有起始值

SELECT generateSerialID('id2', 100)

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

带有起始值的第二次调用

SELECT generateSerialID('id2', 100)

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

getClientHTTPHeader

引入于：v24.5

获取 HTTP 标头的值。如果没有这样的标头，或者当前请求不是通过 HTTP 接口执行的，则该函数返回一个空字符串。某些 HTTP 标头（例如 Authentication 和 X-ClickHouse-*）受到限制。

注意

需要设置 allow_get_client_http_header

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

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

语法

getClientHTTPHeader(name)

参数

name — HTTP 标头的名称。 String

返回值

返回标头的值。 String

示例

使用示例

SELECT getClientHTTPHeader('Content-Type');

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

getMacro

引入于: v20.1

从服务器配置文件中返回宏的值。宏在配置文件的 <macros> 部分中定义，可用于通过方便的名称区分服务器，即使它们具有复杂的hostname。如果该函数在分布式表的上下文中执行，它将生成一个包含与每个分片相关值的普通列。

语法

getMacro(name)

参数

name — 要检索的宏的名称。 const String

返回值

返回指定宏的值。 String

示例

基本用法

SELECT getMacro('test');

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

getMaxTableNameLengthForDatabase

引入于：v

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

语法

getMaxTableNameLengthForDatabase(database_name)

参数

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

返回值

返回最大表名的长度，一个整数

示例

典型

SELECT getMaxTableNameLengthForDatabase('default');

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

getMergeTreeSetting

引入于: v25.6

返回 MergeTree 设置的当前值。

语法

getMergeTreeSetting(setting_name)

参数

setting_name — 设置名称。 String

返回值

返回合并树设置的当前值。

示例

使用示例

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

引入于：v

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

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

语法

参数

无。

返回值

示例

getSubcolumn

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

getTypeSerializationStreams

引入于：v22.6

枚举数据类型的流路径。此函数旨在用于开发用途。

语法

getTypeSerializationStreams(col)

参数

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

返回值

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

示例

tuple

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

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

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

返回线程模糊器是否启用。此函数仅对测试和调试有用。

语法

hasThreadFuzzer()

参数

无。

返回值

返回线程模糊器是否有效。 UInt8

示例

检查线程模糊器状态

SELECT hasThreadFuzzer()

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

hostName

引入于：v20.5

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

语法

hostName()

别名：hostname

参数

无。

返回值

返回主机名。 String

示例

使用示例

SELECT hostName()

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

icebergBucket

引入于：v25.5

实现 iceberg bucket transform 的逻辑

语法

icebergBucket(N, value)

参数

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

返回值

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

示例

SELECT icebergBucket(5, 1.0 :: Float32)

icebergTruncate

引入于：v25.3

实现 iceberg truncate transform 的逻辑：https://iceberg.org.cn/spec/#truncate-transform-details。

语法

icebergTruncate(N, value)

参数

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

返回值

与参数相同的类型

示例

SELECT icebergTruncate(3, 'iceberg')

ice

identity

引入于：v1.1

此函数返回您传递给它的参数，这对于调试和测试很有用。它允许您绕过索引使用以查看完整的扫描性能。查询分析器忽略 identity 函数内部的任何内容，在查找要使用的索引时，并且还会禁用常量折叠。

语法

identity(x)

参数

x — 输入值。 Any

返回值

返回输入值不变。 Any

示例

使用示例

SELECT identity(42)

ignore

引入于：v1.1

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

语法

ignore(x)

参数

x — 一个输入值，未被使用，仅传递以避免语法错误。 Any

返回值

始终返回 0。 UInt8

示例

使用示例

SELECT ignore(0, 'ClickHouse', NULL)

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

indexHint

引入于：v1.1

此函数旨在用于调试和内省。它忽略其参数并始终返回 1。参数不会被评估。

在索引分析期间，假定此函数的参数未包装在 indexHint 中。这允许您通过相应的条件选择索引范围内的的数据，但无需通过此条件进一步过滤。ClickHouse 中的索引是稀疏的，使用 indexHint 会产生比直接指定相同条件更多的数据。

说明

当您运行

SELECT * FROM test WHERE key = 123;

ClickHouse 会执行两件事

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

即使它从磁盘读取 8192 行，它也只返回实际匹配的 1 行。

使用 indexHint 时，当您运行

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

ClickHouse 只执行一件事

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

它返回所有 8192 行，包括 key = 456、key = 789 等的行（所有存储在同一颗粒中的内容）。indexHint() 并非用于性能。它是用于调试和理解 ClickHouse 的索引工作原理的

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

注意：使用 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
precision — 可选。Decimal 类型的精度。如果省略，则使用第一个参数的初始精度。

返回值

如果十进制值超过其精度的位数，则返回 1；如果十进制值满足指定的精度，则返回 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 表中获取数据。

注意

仅支持使用 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 │
└─────────────────────────────────────┘

将数组用作连接键

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 表中获取数据。与 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 - II 类错误的概率）。 (U)Int* 或 Float*
alpha — 测试所需的显著性水平（I 类错误的概率）。 (U)Int* 或 Float*

返回值

返回一个包含 3 个元素的命名元组：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 个元素的命名元组：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 │
└────────┴──────────────────────────┘

nested

引入于：v

此函数由 ClickHouse 引擎内部使用，不应直接使用。

从多个数组返回元组数组。

第一个参数必须是字符串常量数组，用于确定结果元组的名称。其他参数必须是相同大小的数组。

语法

参数

无。

返回值

示例

嵌套

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

normalizeQuery

引入于: v20.8

将字面量、字面量序列和复杂别名（包含空格、超过两位数字或至少 36 字节长的 UUID 等）替换为占位符 ?。

语法

normalizeQuery(x)

参数

x — 字符序列。 String

返回值

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

示例

使用示例

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

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

normalizeQueryKeepNames

引入于: v21.2

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

语法

normalizeQueryKeepNames(x)

参数

x — 字符序列。 String

返回值

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

示例

使用示例

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

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

normalizedQueryHash

引入于: v20.8

为相似查询返回相同的 64 位哈希值，不包含字面量的值。有助于分析查询日志。

语法

normalizedQueryHash(x)

参数

x — 字符序列。 String

返回值

返回 64 位哈希值。 UInt64

示例

使用示例

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

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

normalizedQueryHashKeepNames

引入于: v21.2

与 normalizedQueryHash 类似，它为相似查询返回相同的 64 位哈希值，不包含字面量的值，但它不会在哈希之前将复杂别名（包含空格、超过两位数字或至少 36 字节长的 UUID 等）替换为占位符。有助于分析查询日志。

语法

normalizedQueryHashKeepNames(x)

参数

x — 字符序列。 String

返回值

返回 64 位哈希值。 UInt64

示例

使用示例

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

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

parseReadableSize

引入于：v24.6

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

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

语法

parseReadableSize(x)

参数

x — 带有 ISO/IEC 80000-13 或十进制字节单位的可读大小。 String

返回值

返回字节数，向上舍入到最接近的整数。 UInt64

示例

使用示例

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

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

parseReadableSizeOrNull

引入于：v24.6

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

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

语法

parseReadableSizeOrNull(x)

参数

x — 带有 ISO/IEC 80000-13 或十进制字节单位的可读大小。 String

返回值

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

示例

使用示例

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

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

parseReadableSizeOrZero

引入于：v24.6

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

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

语法

parseReadableSizeOrZero(x)

参数

x — 带有 ISO/IEC 80000-13 或十进制字节单位的可读大小。 String

返回值

返回字节数，向上舍入到最接近的整数，或者如果无法解析输入则返回 0。 UInt64

示例

使用示例

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

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

parseTimeDelta

引入于：v22.7

解析一个由时间单位后跟数字序列组成的字符串。

时间 delta 字符串使用以下时间单位规范

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

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

年份和月份的长度是近似值：一年是 365 天，一个月是 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

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

要求

事件必须按开始时间升序排序。如果违反此要求，该函数将引发异常。每个数据块都是单独处理的。如果来自不同数据块的事件重叠，则无法正确处理它们。

已弃用

建议使用窗口函数代替。

语法

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，对于后续行返回与前一行的差异。

已弃用

仅返回当前处理的数据块内的差异。由于这种容易出错的行为，该函数已被弃用。建议使用窗口函数代替。

您可以使用设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

该函数的结果取决于受影响的数据块和块中的数据顺序。计算 runningDifference() 期间的行顺序可能与返回给用户的行顺序不同。为了防止这种情况，您可以创建一个带有 ORDER BY 的子查询，并从子查询外部调用该函数。请注意，块大小会影响结果。 runningDifference 状态的内部状态会为每个新的块重置。

语法

runningDifference(x)

参数

x — 要计算运行差异的列。 Any

返回值

返回连续值之间的差异，第一行为 0。

示例

使用示例

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

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2025-11-24 00:00:04 │     0 │
│    1107 │ 2025-11-24 00:00:05 │     1 │
│    1108 │ 2025-11-24 00:00:05 │     0 │
│    1109 │ 2025-11-24 00:00:09 │     4 │
│    1110 │ 2025-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

块大小影响示例

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

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

runningDifferenceStartingWithFirstValue

引入于：v1.1

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

已弃用

仅返回当前处理的数据块内的差异。由于这种容易出错的行为，该函数已被弃用。建议使用窗口函数代替。

您可以使用设置 allow_deprecated_error_prone_window_functions 来允许使用此函数。

语法

runningDifferenceStartingWithFirstValue(x)

参数

x — 要计算运行差异的列。 Any

返回值

返回连续值之间的差异，第一行为第一行的值。 Any

示例

使用示例

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

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

serverUUID

引入于: v20.1

返回服务器首次启动时生成的随机且唯一的 UUID (v4)。 UUID 会持久化，即第二次、第三次等服务器启动返回相同的 UUID。

语法

serverUUID()

参数

无。

返回值

返回服务器的随机 UUID。 UUID

示例

使用示例

SELECT serverUUID();

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

shardCount

引入于: v21.9

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

语法

shardCount()

参数

无。

返回值

返回总分片数或 0。 UInt32

示例

使用示例

-- 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 证书来验证连接的信息，请参阅配置 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

引入于：v

函数，将 ClickHouse 表结构转换为 CapnProto 格式架构

语法

参数

无。

返回值

示例

random

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

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

structureToProtobufSchema

引入于：v23.8

将 ClickHouse 表结构转换为 Protobuf 格式架构。

此函数接收 ClickHouse 表结构定义，并将其转换为 proto3 语法中的协议缓冲区 (Protobuf) 架构定义。这对于生成与您的 ClickHouse 表结构匹配的 Protobuf 架构以进行数据交换很有用。

语法

structureToProtobufSchema(structure, message_name)

参数

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

返回值

返回与输入 ClickHouse 结构对应的 proto3 语法 Protobuf 模式定义。 String

示例

将 ClickHouse 结构转换为 Protobuf 模式

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

syntax = "proto3";

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

tcpPort

引入于：v20.12

返回服务器监听的本机接口 TCP 端口号。如果在分布式表的上下文中执行，此函数会生成一个包含与每个分片相关值的普通列。否则，它会生成一个常量值。

语法

tcpPort()

参数

无。

返回值

返回 TCP 端口号。 UInt16

示例

使用示例

SELECT tcpPort()

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

throwIf

引入于：v1.1

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

语法

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

参数

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

返回值

如果条件为 false，则返回 0；如果条件为 true，则抛出异常。 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

实验性功能。了解更多。

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

实验性功能。了解更多。

ClickHouse Cloud 中不支持

返回可用于读取的事务的最新快照（提交序列号）。

注意

此函数是实验功能集的一部分。通过将此设置添加到您的配置中来启用实验性事务支持

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

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

语法

transactionLatestSnapshot()

参数

无。

返回值

返回事务的最新快照 (CSN)。 UInt64

示例

使用示例

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

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

transactionOldestSnapshot

引入于：v22.6

实验性功能。了解更多。

ClickHouse Cloud 中不支持

返回某些正在运行的事务可见的最新快照（提交序列号）。

注意

此函数是实验功能集的一部分。通过将此设置添加到您的配置中来启用实验性事务支持

<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 中对应的元素，否则返回默认值（如果提供）或 x（如果未提供默认值）。 Any

示例

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

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

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

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

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

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

uniqThetaIntersect

引入于: v22.9

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

语法

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

参数

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

返回值

包含交集结果的新 uniqThetaSketch。 UInt64

示例

使用示例

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

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

uniqThetaNot

引入于: v22.9

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

语法

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

参数

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

返回值

返回包含 a_not_b 结果的新 uniqThetaSketch。 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 — 要提取的变体类型名称。 String
default_value — 如果变体没有指定类型的变体，则使用的默认值。可以是任何类型。可选。 Any

返回值

返回从 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 列。 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 格式。

语法

visibleWidth(x)

参数

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

返回值

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

示例

计算 NULL 的可见宽度

SELECT visibleWidth(NULL)

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

zookeeperSessionUptime

引入于：v21.11

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

语法

zookeeperSessionUptime()

参数

无。

返回值

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

示例

使用示例

SELECT zookeeperSessionUptime();

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

FQDN​

MACNumToString​

MACStringToNum​

MACStringToOUI​

__applyFilter​

__patchPartitionID​

authenticatedUser​

bar​

blockNumber​

blockSerializedSize​

blockSize​

buildId​

byteSize​

catboostEvaluate​

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​

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​

FQDN

MACNumToString

MACStringToNum

MACStringToOUI

__applyFilter

__patchPartitionID

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

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