其他函数
hostName
返回执行此函数的主机名。如果该函数在远程服务器上执行（分布式处理），则返回远程服务器名称。如果该函数在分布式表的上下文中执行，它将生成一个普通列，其值与每个分片相关。否则，它会生成一个常量值。
语法
hostName()
返回值
- 主机名。 字符串。
getMacro
从服务器配置的 macros 部分返回一个命名值。
语法
getMacro(name);
参数
name— 要从<macros>部分检索的宏名称。 字符串。
返回值
- 指定宏的值。 字符串。
示例
服务器配置文件中 <macros> 部分的示例
<macros>
<test>Value</test>
</macros>
查询
SELECT getMacro('test');
结果
┌─getMacro('test')─┐
│ Value │
└──────────────────┘
可以按如下方式检索相同的值
SELECT * FROM system.macros
WHERE macro = 'test';
┌─macro─┬─substitution─┐
│ test │ Value │
└───────┴──────────────┘
fqdn
返回 ClickHouse 服务器的完全限定域名。
语法
fqdn();
别名：fullHostName, FQDN。
返回值
- 带有完全限定域名的字符串。 字符串。
示例
SELECT FQDN();
结果
┌─FQDN()──────────────────────────┐
│ clickhouse.ru-central1.internal │
└─────────────────────────────────┘
basename
提取字符串尾部最后一个斜杠或反斜杠之后的部分。此函数通常用于从路径中提取文件名。
basename(expr)
参数
expr— String 类型的值。反斜杠必须转义。
返回值
一个包含以下内容的字符串
- 输入字符串尾部最后一个斜杠或反斜杠之后的部分。如果输入字符串以斜杠或反斜杠结尾（例如
/或c:\），则该函数返回一个空字符串。 - 如果没有斜杠或反斜杠，则返回原始字符串。
示例
查询
SELECT 'some/long/path/to/file' AS a, basename(a)
结果
┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file │
└────────────────────────┴────────────────────────────────────────┘
查询
SELECT 'some\\long\\path\\to\\file' AS a, basename(a)
结果
┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file │
└────────────────────────┴────────────────────────────────────────┘
查询
SELECT 'some-file-name' AS a, basename(a)
结果
┌─a──────────────┬─basename('some-file-name')─┐
│ some-file-name │ some-file-name │
└────────────────┴────────────────────────────┘
visibleWidth
计算以文本格式（制表符分隔）将值输出到控制台时的大概宽度。此函数由系统用于实现 美观格式。
NULL 在 Pretty 格式中表示为与 NULL 对应的字符串。
语法
visibleWidth(x)
示例
查询
SELECT visibleWidth(NULL)
结果
┌─visibleWidth(NULL)─┐
│ 4 │
└────────────────────┘
toTypeName
返回传递参数的类型名称。
如果传递 NULL，该函数返回类型 Nullable(Nothing)，它对应于 ClickHouse 的内部 NULL 表示。
语法
toTypeName(value)
参数
value— 任意类型的值。
返回值
- 输入值的数据类型名称。 字符串。
示例
查询
SELECT toTypeName(123);
结果
┌─toTypeName(123)─┐
│ UInt8 │
└─────────────────┘
blockSize
在 ClickHouse 中，查询在 块（chunks）中处理。此函数返回调用该函数的块的大小（行数）。
语法
blockSize()
示例
查询
DROP TABLE IF EXISTS test;
CREATE TABLE test (n UInt8) ENGINE = Memory;
INSERT INTO test
SELECT * FROM system.numbers LIMIT 5;
SELECT blockSize()
FROM test;
结果
┌─blockSize()─┐
1. │ 5 │
2. │ 5 │
3. │ 5 │
4. │ 5 │
5. │ 5 │
└─────────────┘
byteSize
返回内存中其参数的未压缩字节大小的估计值。
语法
byteSize(argument [, ...])
参数
argument— 值。
返回值
- 内存中参数的字节大小估计值。 UInt64。
示例
对于 String 参数，该函数返回字符串长度 + 9（终止零 + 长度）。
查询
SELECT byteSize('string');
结果
┌─byteSize('string')─┐
│ 15 │
└────────────────────┘
查询
CREATE TABLE test
(
`key` Int32,
`u8` UInt8,
`u16` UInt16,
`u32` UInt32,
`u64` UInt64,
`i8` Int8,
`i16` Int16,
`i32` Int32,
`i64` Int64,
`f32` Float32,
`f64` Float64
)
ENGINE = MergeTree
ORDER BY key;
INSERT INTO test VALUES(1, 8, 16, 32, 64, -8, -16, -32, -64, 32.32, 64.64);
SELECT key, byteSize(u8) AS `byteSize(UInt8)`, byteSize(u16) AS `byteSize(UInt16)`, byteSize(u32) AS `byteSize(UInt32)`, byteSize(u64) AS `byteSize(UInt64)`, byteSize(i8) AS `byteSize(Int8)`, byteSize(i16) AS `byteSize(Int16)`, byteSize(i32) AS `byteSize(Int32)`, byteSize(i64) AS `byteSize(Int64)`, byteSize(f32) AS `byteSize(Float32)`, byteSize(f64) AS `byteSize(Float64)` FROM test ORDER BY key ASC FORMAT Vertical;
结果
Row 1:
──────
key: 1
byteSize(UInt8): 1
byteSize(UInt16): 2
byteSize(UInt32): 4
byteSize(UInt64): 8
byteSize(Int8): 1
byteSize(Int16): 2
byteSize(Int32): 4
byteSize(Int64): 8
byteSize(Float32): 4
byteSize(Float64): 8
如果函数有多个参数，则该函数会累积它们的字节大小。
查询
SELECT byteSize(NULL, 1, 0.3, '');
结果
┌─byteSize(NULL, 1, 0.3, '')─┐
│ 19 │
└────────────────────────────┘
materialize
将常量转换为包含单个值的完整列。完整列和常量在内存中以不同的方式表示。函数通常为普通参数和常量参数执行不同的代码，尽管结果通常应该是相同的。此函数可用于调试此行为。
语法
materialize(x)
参数
x— 常量。 常量。
返回值
- 包含单个值
x的列。
示例
在下面的示例中，countMatches 函数需要一个常量作为第二个参数。可以通过使用 materialize 函数将常量转换为完整列来调试此行为，验证该函数是否会为非常量参数抛出错误。
查询
SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));
结果
2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String
ignore
接受任意参数并无条件地返回 0。参数仍在内部评估，使其可用于例如基准测试。
语法
ignore([arg1[, arg2[, ...]])
参数
- 接受任意多个任意类型的参数，包括
NULL。
返回值
- 返回
0。
示例
查询
SELECT ignore(0, 'ClickHouse', NULL);
结果
┌─ignore(0, 'ClickHouse', NULL)─┐
│ 0 │
└───────────────────────────────┘
sleep
用于在查询执行中引入延迟或暂停。它主要用于测试和调试目的。
语法
sleep(seconds)
参数
返回值
此函数不返回任何值。
示例
SELECT sleep(2);
此函数不返回任何值。但是，如果您使用 clickhouse client 运行该函数，您将看到类似于以下内容
SELECT sleep(2)
Query id: 8aa9943e-a686-45e1-8317-6e8e3a5596ac
┌─sleep(2)─┐
│ 0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.
此查询将暂停 2 秒钟，然后完成。在此期间，不会返回任何结果，并且查询将显示为挂起或无响应。
实现细节
sleep() 函数通常不用于生产环境，因为它可能会对查询性能和系统响应能力产生负面影响。但是，它在以下情况下可能很有用
- 测试：在测试或基准测试 ClickHouse 时，您可能希望模拟延迟或引入暂停，以观察系统在特定条件下的行为。
- 调试：如果您需要在特定时间点检查系统状态或查询执行情况，可以使用
sleep()引入暂停，以便您检查或收集相关信息。 - 模拟：在某些情况下，您可能希望模拟现实世界中发生延迟或暂停的场景，例如网络延迟或外部系统依赖性。
重要的是要谨慎使用 sleep() 函数，并且仅在必要时使用，因为它可能会影响 ClickHouse 系统的整体性能和响应能力。
sleepEachRow
暂停查询执行指定的秒数，结果集中的每一行暂停一次。
语法
sleepEachRow(seconds)
参数
返回值
此函数返回与接收到的输入值相同的值，而不对其进行修改。
示例
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;
┌─number─┬─sleepEachRow(0.5)─┐
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 0 │
│ 3 │ 0 │
│ 4 │ 0 │
└────────┴───────────────────┘
但输出将被延迟，每行之间暂停 0.5 秒。
sleepEachRow() 函数主要用于测试和调试目的，类似于 sleep() 函数。它允许您模拟延迟或在每行处理中引入暂停，这在以下情况下可能很有用
- 测试：在特定条件下测试或基准测试 ClickHouse 的性能时，可以使用
sleepEachRow()来模拟延迟或为处理的每一行引入暂停。 - 调试：如果您需要检查系统状态或每行处理的查询执行情况，可以使用
sleepEachRow()引入暂停，以便您检查或收集相关信息。 - 模拟：在某些情况下，您可能希望模拟现实世界中每行处理都发生延迟或暂停的场景，例如在处理外部系统或网络延迟时。
与 sleep() 函数 类似，重要的是要谨慎使用 sleepEachRow()，并且仅在必要时使用，因为它可能会严重影响 ClickHouse 系统的整体性能和响应能力，尤其是在处理大型结果集时。
currentDatabase
返回当前数据库的名称。在 CREATE TABLE 查询的表引擎参数中，当您需要指定数据库时很有用。
语法
currentDatabase()
返回值
- 返回当前数据库名称。 字符串。
示例
查询
SELECT currentDatabase()
结果
┌─currentDatabase()─┐
│ default │
└───────────────────┘
currentUser
返回当前用户的名称。在分布式查询的情况下，返回启动查询的用户的名称。
语法
currentUser()
别名：user(), USER(), current_user()。别名不区分大小写。
返回值
示例
SELECT currentUser();
结果
┌─currentUser()─┐
│ default │
└───────────────┘
currentSchemas
返回一个单元素数组，其中包含当前数据库模式的名称。
语法
currentSchemas(bool)
别名：current_schemas。
参数
bool：布尔值。 Bool。
布尔参数被忽略。它的存在只是为了与 PostgreSQL 中此函数的 实现 兼容。
返回值
- 返回一个单元素数组，其中包含当前数据库的名称
示例
SELECT currentSchemas(true);
结果
['default']
isConstant
返回参数是否为常量表达式。
常量表达式是在查询分析期间（即执行之前）已知其结果的表达式。例如，字面量 上的表达式是常量表达式。
此函数主要用于开发、调试和演示。
语法
isConstant(x)
参数
x— 要检查的表达式。
返回值
示例
查询
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 │
└────────────────────┘
hasColumnInTable
给定数据库名称、表名称和列名称作为常量字符串，如果给定列存在，则返回 1，否则返回 0。
语法
hasColumnInTable(\[‘hostname’\[, ‘username’\[, ‘password’\]\],\] ‘database’, ‘table’, ‘column’)
参数
database：数据库名称。 字符串字面量table：表名称。 字符串字面量column：列名称。 字符串字面量hostname：要在其上执行检查的远程服务器名称。 字符串字面量username：远程服务器的用户名。 字符串字面量password：远程服务器的密码。 字符串字面量
返回值
- 如果给定列存在，则返回
1。 - 否则返回
0。
实现细节
对于嵌套数据结构中的元素，该函数检查列的存在性。对于嵌套数据结构本身，该函数返回 0。
示例
查询
SELECT hasColumnInTable('system','metrics','metric')
1
SELECT hasColumnInTable('system','metrics','non-existing_column')
0
hasThreadFuzzer
返回线程模糊测试器是否有效。它可以在测试中使用，以防止运行时间过长。
语法
hasThreadFuzzer();
bar
构建条形图。
bar(x, min, max, width) 绘制一个条带，其宽度与 (x - min) 成比例，当 x = max 时等于 width 个字符。
参数
x— 要显示的大小。min, max— 整数常量。该值必须适合Int64。width— 常量，正整数，可以是小数。
条带以八分之一符号的精度绘制。
示例
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 │ █████████████▎ │
└────┴────────┴────────────────────┘
transform
根据某些元素到其他元素的显式定义的映射转换值。此函数有两种变体
transform(x, array_from, array_to, default)
x – 要转换的内容。
array_from – 要转换的值的常量数组。
array_to – 将“from”中的值转换为的值的常量数组。
default – 如果“x”不等于“from”中的任何值，则使用的值。
array_from 和 array_to 必须具有相同数量的元素。
签名
对于等于 array_from 中元素之一的 x，该函数返回 array_to 中的相应元素，即位于相同数组索引处的元素。否则，它返回 default。如果 array_from 中存在多个匹配元素，则它返回与第一个匹配元素对应的元素。
transform(T, Array(T), Array(U), U) -> U
T 和 U 可以是数值、字符串或 Date 或 DateTime 类型。相同的字母（T 或 U）表示类型必须相互兼容，但不一定相等。例如，第一个参数的类型可以是 Int64，而第二个参数的类型可以是 Array(UInt16)。
示例
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(x, array_from, array_to)
与其他变体类似，但没有“default”参数。如果找不到匹配项，则返回 x。
示例
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 │
└────────────────┴─────────┘
formatReadableDecimalSize
给定大小（字节数），此函数返回可读的、四舍五入的大小，并带有后缀（KB、MB 等）作为字符串。
此函数的相反操作是 parseReadableSize、parseReadableSizeOrZero 和 parseReadableSizeOrNull。
语法
formatReadableDecimalSize(x)
示例
查询
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 │
└────────────────┴────────────┘
formatReadableSize
给定大小（字节数），此函数返回可读的、四舍五入的大小，并带有后缀（KiB、MiB 等）作为字符串。
此函数的相反操作是 parseReadableSize、parseReadableSizeOrZero 和 parseReadableSizeOrNull。
语法
formatReadableSize(x)
别名：FORMAT_BYTES。
此函数接受任何数值类型作为输入，但在内部将其强制转换为 Float64。对于较大的值，结果可能不是最优的
示例
查询
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 │
└────────────────┴────────────┘
formatReadableQuantity
给定一个数字，此函数返回一个四舍五入的数字，并带有后缀（千、百万、十亿等）作为字符串。
语法
formatReadableQuantity(x)
此函数接受任何数值类型作为输入，但在内部将其强制转换为 Float64。对于较大的值，结果可能不是最优的
示例
查询
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 │
└────────────────┴───────────────────┘
formatReadableTimeDelta
给定以秒为单位的时间间隔（增量），此函数返回一个时间增量，其中包含年/月/日/小时/分钟/秒/毫秒/微秒/纳秒作为字符串。
语法
formatReadableTimeDelta(column[, maximum_unit, minimum_unit])
此函数接受任何数值类型作为输入，但在内部将其强制转换为 Float64。对于较大的值，结果可能不是最优的
参数
column— 带有数值时间增量的列。maximum_unit— 可选。要显示的最大单位。- 可接受的值：
nanoseconds、microseconds、milliseconds、seconds、minutes、hours、days、months、years。 - 默认值：
years。
- 可接受的值：
minimum_unit— 可选。要显示的最小单位。所有较小的单位都将被截断。- 可接受的值：
nanoseconds、microseconds、milliseconds、seconds、minutes、hours、days、months、years。 - 如果显式指定的值大于
maximum_unit，则会抛出异常。 - 默认值：如果
maximum_unit是seconds或更大，则为seconds，否则为nanoseconds。
- 可接受的值：
示例
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 │
└────────────┴─────────────────────────────────────────────────────────────────┘
SELECT
arrayJoin([100, 12345, 432546534.00000006]) AS elapsed,
formatReadableTimeDelta(elapsed, 'minutes', 'nanoseconds') AS time_delta
┌────────────elapsed─┬─time_delta─────────────────────────────────────┐
│ 100 │ 1 minute and 40 seconds │
│ 12345 │ 205 minutes and 45 seconds │
│ 432546534.00000006 │ 7209108 minutes, 54 seconds and 60 nanoseconds │
└────────────────────┴────────────────────────────────────────────────┘
parseReadableSize
给定一个包含字节大小和 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
给定一个包含字节大小和 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
给定一个包含字节大小和 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
解析后跟类似于时间单位的内容的数字序列。
语法
parseTimeDelta(timestr)
参数
timestr— 后跟类似于时间单位的内容的数字序列。
返回值
- 一个浮点数，表示秒数。
示例
SELECT parseTimeDelta('11s+22min')
┌─parseTimeDelta('11s+22min')─┐
│ 1331 │
└─────────────────────────────┘
SELECT parseTimeDelta('1yr2mo')
┌─parseTimeDelta('1yr2mo')─┐
│ 36806400 │
└──────────────────────────┘
least
返回一个或多个输入参数中最小的参数。 NULL 参数将被忽略。
语法
least(a, b)
版本 24.12 引入了一个向后不兼容的更改，即 NULL 值被忽略，而以前如果其中一个参数为 NULL，则返回 NULL。要保留以前的行为，请将设置 least_greatest_legacy_null_behavior（默认值：false）设置为 true。
greatest
返回一个或多个输入参数中最大的参数。 NULL 参数将被忽略。
语法
greatest(a, b)
版本 24.12 引入了一个向后不兼容的更改，即 NULL 值被忽略，而以前如果其中一个参数为 NULL，则返回 NULL。要保留以前的行为，请将设置 least_greatest_legacy_null_behavior（默认值：false）设置为 true。
uptime
返回服务器的正常运行时间（以秒为单位）。如果在分布式表的上下文中执行，此函数将生成一个普通列，其值与每个分片相关。否则，它会生成一个常量值。
语法
uptime()
返回值
- 秒的时间值。 UInt32。
示例
查询
SELECT uptime() as Uptime;
结果
┌─Uptime─┐
│ 55867 │
└────────┘
version
以字符串形式返回 ClickHouse 的当前版本，格式为
- 主版本
- 次版本
- 补丁版本
- 自上次稳定版本以来的提交次数。
major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release
如果在分布式表的上下文中执行，此函数将生成一个普通列，其值与每个分片相关。否则，它会生成一个常量值。
语法
version()
参数
无。
返回值
- ClickHouse 的当前版本。 字符串。
实现细节
无。
示例
查询
SELECT version()
结果:
┌─version()─┐
│ 24.2.1.1 │
└───────────┘
buildId
返回编译器为正在运行的 ClickHouse 服务器二进制文件生成的构建 ID。如果在分布式表的上下文中执行，此函数将生成一个普通列，其值与每个分片相关。否则，它会生成一个常量值。
语法
buildId()
blockNumber
返回包含行的 block 的单调递增序列号。返回的块号以尽力而为的方式更新，即它可能不是完全准确的。
语法
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 │
└───────────────┘
rowNumberInBlock
对于 rowNumberInBlock 处理的每个 block，返回当前行的编号。返回的编号从每个块的 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 │
└────────────────────┘
rowNumberInAllBlocks
为 rowNumberInAllBlocks 处理的每一行返回唯一的行号。返回的数字从 0 开始。
语法
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 │
└────────────────────────┘
neighbor
提供访问给定列的当前行之前或之后指定偏移量处的行的窗口函数。
语法
neighbor(column, offset[, default_value])
函数的结果取决于受影响的数据块和块中数据的顺序。
仅返回当前处理的数据块内的邻居。由于这种容易出错的行为，该函数已被弃用（DEPRECATED），请使用合适的窗口函数代替。
在计算 neighbor() 期间，行的顺序可能与返回给用户的行的顺序不同。为了防止这种情况，您可以创建一个带有 ORDER BY 的子查询，并从子查询外部调用该函数。
参数
column— 列名或标量表达式。offset— 在column中当前行之前或之后的行数。 Int64。default_value— 可选。如果偏移量超出块边界，则返回的值。受影响的数据块的类型。
返回值
- 如果
offset未超出块边界，则为距当前行offset距离的column的值。 - 如果
offset超出块边界，则为column的默认值或default_value（如果已给定）。
返回类型将是受影响的数据块的类型或默认值类型。
示例
查询
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 │
└────────┴──────────────────────────┘
此函数可用于计算同比指标值
查询
WITH toDate('2018-01-01') AS start_date
SELECT
toStartOfMonth(start_date + (number * 32)) AS month,
toInt32(month) % 100 AS money,
neighbor(money, -12) AS prev_year,
round(prev_year / money, 2) AS year_over_year
FROM numbers(16)
结果
┌──────month─┬─money─┬─prev_year─┬─year_over_year─┐
│ 2018-01-01 │ 32 │ 0 │ 0 │
│ 2018-02-01 │ 63 │ 0 │ 0 │
│ 2018-03-01 │ 91 │ 0 │ 0 │
│ 2018-04-01 │ 22 │ 0 │ 0 │
│ 2018-05-01 │ 52 │ 0 │ 0 │
│ 2018-06-01 │ 83 │ 0 │ 0 │
│ 2018-07-01 │ 13 │ 0 │ 0 │
│ 2018-08-01 │ 44 │ 0 │ 0 │
│ 2018-09-01 │ 75 │ 0 │ 0 │
│ 2018-10-01 │ 5 │ 0 │ 0 │
│ 2018-11-01 │ 36 │ 0 │ 0 │
│ 2018-12-01 │ 66 │ 0 │ 0 │
│ 2019-01-01 │ 97 │ 32 │ 0.33 │
│ 2019-02-01 │ 28 │ 63 │ 2.25 │
│ 2019-03-01 │ 56 │ 91 │ 1.62 │
│ 2019-04-01 │ 87 │ 22 │ 0.25 │
└────────────┴───────┴───────────┴────────────────┘
runningDifference
计算数据块中两个连续行值之间的差异。第一行返回 0，后续行返回与前一行的差异。
仅返回当前处理的数据块内的差异。由于这种容易出错的行为，该函数已被弃用（DEPRECATED），请使用合适的窗口函数代替。
函数的结果取决于受影响的数据块和块中数据的顺序。
在计算 runningDifference() 期间，行的顺序可能与返回给用户的行的顺序不同。为了防止这种情况，您可以创建一个带有 ORDER BY 的子查询，并从子查询外部调用该函数。
语法
runningDifference(x)
示例
查询
SELECT
EventID,
EventTime,
runningDifference(EventTime) AS delta
FROM
(
SELECT
EventID,
EventTime
FROM events
WHERE EventDate = '2016-11-24'
ORDER BY EventTime ASC
LIMIT 5
)
结果
┌─EventID─┬───────────EventTime─┬─delta─┐
│ 1106 │ 2016-11-24 00:00:04 │ 0 │
│ 1107 │ 2016-11-24 00:00:05 │ 1 │
│ 1108 │ 2016-11-24 00:00:05 │ 0 │
│ 1109 │ 2016-11-24 00:00:09 │ 4 │
│ 1110 │ 2016-11-24 00:00:10 │ 1 │
└─────────┴─────────────────────┴───────┘
请注意，块大小会影响结果。runningDifference 的内部状态对于每个新块都会重置。
查询
SELECT
number,
runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1
结果
┌─number─┬─diff─┐
│ 0 │ 0 │
└────────┴──────┘
┌─number─┬─diff─┐
│ 65536 │ 0 │
└────────┴──────┘
查询
set max_block_size=100000 -- default value is 65536!
SELECT
number,
runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1
结果
┌─number─┬─diff─┐
│ 0 │ 0 │
└────────┴──────┘
runningDifferenceStartingWithFirstValue
此函数已被弃用（DEPRECATED）（请参阅 runningDifference 的注释）。
与 runningDifference 相同，但第一行返回第一行的值。
runningConcurrency
计算并发事件的数量。每个事件都有一个开始时间和结束时间。开始时间包含在事件中，而结束时间不包含在事件中。具有开始时间和结束时间的列必须具有相同的数据类型。该函数计算每个事件开始时间的活动（并发）事件的总数。
事件必须按开始时间升序排序。如果违反此要求，该函数将引发异常。每个数据块都单独处理。如果来自不同数据块的事件重叠，则无法正确处理它们。
语法
runningConcurrency(start, end)
参数
start— 包含事件开始时间的列。 Date, DateTime, 或 DateTime64。end— 包含事件结束时间的列。 Date, DateTime, 或 DateTime64。
返回值
- 每个事件开始时间的并发事件数。 UInt32
示例
考虑下表
┌──────start─┬────────end─┐
│ 2021-03-03 │ 2021-03-11 │
│ 2021-03-06 │ 2021-03-12 │
│ 2021-03-07 │ 2021-03-08 │
│ 2021-03-11 │ 2021-03-12 │
└────────────┴────────────┘
查询
SELECT start, runningConcurrency(start, end) FROM example_table;
结果
┌──────start─┬─runningConcurrency(start, end)─┐
│ 2021-03-03 │ 1 │
│ 2021-03-06 │ 2 │
│ 2021-03-07 │ 3 │
│ 2021-03-11 │ 2 │
└────────────┴────────────────────────────────┘
MACNumToString
将 UInt64 数字解释为大端格式的 MAC 地址。以 AA:BB:CC:DD:EE 格式返回相应的 MAC 地址:FF（十六进制形式的冒号分隔数字）作为字符串。
语法
MACNumToString(num)
MACStringToNum
MACNumToString 的反函数。如果 MAC 地址格式无效，则返回 0。
语法
MACStringToNum(s)
MACStringToOUI
给定 AA:BB:CC:DD:EE 格式的 MAC 地址:FF（十六进制形式的冒号分隔数字），返回前三个八位字节作为 UInt64 数字。如果 MAC 地址格式无效，则返回 0。
语法
MACStringToOUI(s)
getSizeOfEnumType
返回 Enum 中的字段数。如果类型不是 Enum，则会抛出异常。
语法
getSizeOfEnumType(value)
参数
value—Enum类型的值。
返回值
- 具有
Enum输入值的字段数。
示例
SELECT getSizeOfEnumType( CAST('a' AS Enum8('a' = 1, 'b' = 2) ) ) AS x
┌─x─┐
│ 2 │
└───┘
blockSerializedSize
返回磁盘上的大小，不考虑压缩。
blockSerializedSize(value[, value[, ...]])
参数
value— 任何值。
返回值
- 不压缩的情况下，值块将写入磁盘的字节数。
示例
查询
SELECT blockSerializedSize(maxState(1)) as x
结果
┌─x─┐
│ 2 │
└───┘
toColumnTypeName
返回表示值的内部数据类型名称。
语法
toColumnTypeName(value)
参数
value— 任何类型的值。
返回值
- 用于表示
value的内部数据类型名称。
示例
toTypeName 和 toColumnTypeName 之间的区别
SELECT toTypeName(CAST('2018-01-01 01:02:03' AS DateTime))
结果
┌─toTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime │
└─────────────────────────────────────────────────────┘
查询
SELECT toColumnTypeName(CAST('2018-01-01 01:02:03' AS DateTime))
结果
┌─toColumnTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32) │
└───────────────────────────────────────────────────────────┘
示例显示 DateTime 数据类型在内部存储为 Const(UInt32)。
dumpColumnStructure
输出 RAM 中数据结构的详细描述
dumpColumnStructure(value)
参数
value— 任何类型的值。
返回值
- 用于表示
value的列结构的描述。
示例
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)) │
└──────────────────────────────────────────────────────────────┘
defaultValueOfArgumentType
返回给定数据类型的默认值。
不包括用户设置的自定义列的默认值。
语法
defaultValueOfArgumentType(expression)
参数
expression— 任意类型的值或产生任意类型的值的表达式。
返回值
- 数字为
0。 - 字符串为空字符串。
- 对于 Nullable 为
ᴺᵁᴸᴸ。
示例
查询
SELECT defaultValueOfArgumentType( CAST(1 AS Int8) )
结果
┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│ 0 │
└─────────────────────────────────────────────┘
查询
SELECT defaultValueOfArgumentType( CAST(1 AS Nullable(Int8) ) )
结果
┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│ ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘
defaultValueOfTypeName
返回给定类型名称的默认值。
不包括用户设置的自定义列的默认值。
defaultValueOfTypeName(type)
参数
type— 表示类型名称的字符串。
返回值
- 数字为
0。 - 字符串为空字符串。
- 对于 Nullable 为
ᴺᵁᴸᴸ。
示例
查询
SELECT defaultValueOfTypeName('Int8')
结果
┌─defaultValueOfTypeName('Int8')─┐
│ 0 │
└────────────────────────────────┘
查询
SELECT defaultValueOfTypeName('Nullable(Int8)')
结果
┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘
indexHint
此函数旨在用于调试和内省。它忽略其参数并始终返回 1。参数不进行评估。
但在索引分析期间，此函数的参数被假定为未包装在 indexHint 中。这允许通过相应的条件在索引范围内选择数据，但无需通过此条件进一步过滤。ClickHouse 中的索引是稀疏的，使用 indexHint 将产生比直接指定相同条件更多的数据。
语法
SELECT * FROM table WHERE indexHint(<expression>)
返回值
1。 Uint8。
示例
这是表 ontime 中的测试数据示例。
表
SELECT count() FROM ontime
┌─count()─┐
│ 4276457 │
└─────────┘
该表在字段 (FlightDate, (Year, FlightDate)) 上具有索引。
创建一个不使用索引的查询
SELECT FlightDate AS k, count() FROM ontime GROUP BY k ORDER BY k
ClickHouse 处理了整个表（Processed 4.28 million rows）。
结果
┌──────────k─┬─count()─┐
│ 2017-01-01 │ 13970 │
│ 2017-01-02 │ 15882 │
........................
│ 2017-09-28 │ 16411 │
│ 2017-09-29 │ 16384 │
│ 2017-09-30 │ 12520 │
└────────────┴─────────┘
要应用索引，请选择特定日期
SELECT FlightDate AS k, count() FROM ontime WHERE k = '2017-09-15' GROUP BY k ORDER BY k
ClickHouse 现在使用索引来处理明显更少的行数（Processed 32.74 thousand rows）。
结果
┌──────────k─┬─count()─┐
│ 2017-09-15 │ 16428 │
└────────────┴─────────┘
现在将表达式 k = '2017-09-15' 包装在函数 indexHint 中
查询
SELECT
FlightDate AS k,
count()
FROM ontime
WHERE indexHint(k = '2017-09-15')
GROUP BY k
ORDER BY k ASC
ClickHouse 以与之前相同的方式使用索引（Processed 32.74 thousand rows）。表达式 k = '2017-09-15' 在生成结果时未使用。在示例中，indexHint 函数允许查看相邻日期。
结果
┌──────────k─┬─count()─┐
│ 2017-09-14 │ 7071 │
│ 2017-09-15 │ 16428 │
│ 2017-09-16 │ 1077 │
│ 2017-09-30 │ 8167 │
└────────────┴─────────┘
replicate
创建一个包含单个值的数组。
此函数用于 arrayJoin 的内部实现。
语法
replicate(x, arr)
参数
x— 用于填充结果数组的值。arr— 一个数组。 Array。
返回值
与 arr 长度相同的数组，填充了值 x。 Array。
示例
查询
SELECT replicate(1, ['a', 'b', 'c']);
结果
┌─replicate(1, ['a', 'b', 'c'])─┐
│ [1,1,1] │
└───────────────────────────────┘
revision
返回当前 ClickHouse 服务器修订号。
语法
revision()
返回值
- 当前 ClickHouse 服务器修订号。 UInt32。
示例
查询
SELECT revision();
结果
┌─revision()─┐
│ 54485 │
└────────────┘
filesystemAvailable
返回托管数据库持久性的文件系统中可用的可用空间量。返回的值始终小于总可用空间 (filesystemUnreserved)，因为某些空间为操作系统保留。
语法
filesystemAvailable()
返回值
- 剩余可用空间量（字节）。 UInt64。
示例
查询
SELECT formatReadableSize(filesystemAvailable()) AS "Available space";
结果
┌─Available space─┐
│ 30.75 GiB │
└─────────────────┘
filesystemUnreserved
返回托管数据库持久性的文件系统上的总可用空间量。（以前为 filesystemFree）。另请参阅 filesystemAvailable。
语法
filesystemUnreserved()
返回值
- 可用空间量（字节）。 UInt64。
示例
查询
SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";
结果
┌─Free space─┐
│ 32.39 GiB │
└────────────┘
filesystemCapacity
返回文件系统的容量（字节）。需要配置数据目录的 path。
语法
filesystemCapacity()
返回值
- 文件系统的容量（字节）。 UInt64。
示例
查询
SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";
结果
┌─Capacity──┐
│ 39.32 GiB │
└───────────┘
initializeAggregation
基于单个值计算聚合函数的结果。此函数可用于初始化带有组合器 -State 的聚合函数。您可以创建聚合函数的状态，并将它们插入到 AggregateFunction 类型的列中，或将初始化的聚合用作默认值。
语法
initializeAggregation (aggregate_function, arg1, arg2, ..., argN)
参数
aggregate_function— 要初始化的聚合函数的名称。 String。arg— 聚合函数的参数。
返回值
- 传递给函数的每一行的聚合结果。
返回类型与 initializeAggregation 作为第一个参数的函数的返回类型相同。
示例
查询
SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
结果
┌─uniqMerge(state)─┐
│ 3 │
└──────────────────┘
查询
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) │
└────────────────────────────┴───────────────────────────────┘
带有 AggregatingMergeTree 表引擎和 AggregateFunction 列的示例
CREATE TABLE metrics
(
key UInt64,
value AggregateFunction(sum, UInt64) DEFAULT initializeAggregation('sumState', toUInt64(0))
)
ENGINE = AggregatingMergeTree
ORDER BY key
INSERT INTO metrics VALUES (0, initializeAggregation('sumState', toUInt64(42)))
另请参阅
finalizeAggregation
给定聚合函数的状态，此函数返回聚合的结果（或在使用 -State 组合器时返回最终状态）。
语法
finalizeAggregation(state)
参数
state— 聚合的状态。 AggregateFunction。
返回值
- 已聚合的值/多个值。
返回类型等于任何已聚合的类型的返回类型。
示例
查询
SELECT finalizeAggregation(( SELECT countState(number) FROM numbers(10)));
结果
┌─finalizeAggregation(_subquery16)─┐
│ 10 │
└──────────────────────────────────┘
查询
SELECT finalizeAggregation(( SELECT sumState(number) FROM numbers(10)));
结果
┌─finalizeAggregation(_subquery20)─┐
│ 45 │
└──────────────────────────────────┘
请注意，NULL 值将被忽略。
查询
SELECT finalizeAggregation(arrayReduce('anyState', [NULL, 2, 3]));
结果
┌─finalizeAggregation(arrayReduce('anyState', [NULL, 2, 3]))─┐
│ 2 │
└────────────────────────────────────────────────────────────┘
组合示例
查询
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(10);
结果
┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│ 0 │ 0 │ 0 │
│ 1 │ 1 │ 1 │
│ 2 │ 2 │ 3 │
│ 3 │ 3 │ 6 │
│ 4 │ 4 │ 10 │
│ 5 │ 5 │ 15 │
│ 6 │ 6 │ 21 │
│ 7 │ 7 │ 28 │
│ 8 │ 8 │ 36 │
│ 9 │ 9 │ 45 │
└────────┴─────────────┴────────────────┘
另请参阅
runningAccumulate
为数据块的每一行累积聚合函数的状态。
对于每个新的数据块，状态都会重置。由于这种容易出错的行为，该函数已被弃用（DEPRECATED），请使用合适的窗口函数代替。
语法
runningAccumulate(agg_state[, grouping]);
参数
agg_state— 聚合函数的状态。 AggregateFunction。grouping— 分组键。可选。如果grouping值发生更改，则函数的状态将重置。它可以是 支持的数据类型 中的任何类型，并且这些类型定义了相等运算符。
返回值
- 每个结果行都包含聚合函数的结果，该结果针对从 0 到当前位置的所有输入行进行累积。对于每个新的数据块或当
grouping值更改时，runningAccumulate会重置状态。
类型取决于使用的聚合函数。
示例
考虑如何使用 runningAccumulate 来查找数字的累积和，无论是否分组。
查询
SELECT k, runningAccumulate(sum_k) AS res FROM (SELECT number as k, sumState(k) AS sum_k FROM numbers(10) GROUP BY k ORDER BY k);
结果
┌─k─┬─res─┐
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 3 │
│ 3 │ 6 │
│ 4 │ 10 │
│ 5 │ 15 │
│ 6 │ 21 │
│ 7 │ 28 │
│ 8 │ 36 │
│ 9 │ 45 │
└───┴─────┘
子查询为从 0 到 9 的每个数字生成 sumState。sumState 返回 sum 函数的状态，该状态包含单个数字的总和。
整个查询执行以下操作
- 对于第一行，
runningAccumulate采用sumState(0)并返回0。 - 对于第二行，该函数合并
sumState(0)和sumState(1)，生成sumState(0 + 1)，并返回1作为结果。 - 对于第三行，该函数合并
sumState(0 + 1)和sumState(2)，生成sumState(0 + 1 + 2)，并返回3作为结果。 - 重复这些操作直到块结束。
以下示例显示了 groupping 参数的用法
查询
SELECT
grouping,
item,
runningAccumulate(state, grouping) AS res
FROM
(
SELECT
toInt8(number / 4) AS grouping,
number AS item,
sumState(number) AS state
FROM numbers(15)
GROUP BY item
ORDER BY item ASC
);
结果
┌─grouping─┬─item─┬─res─┐
│ 0 │ 0 │ 0 │
│ 0 │ 1 │ 1 │
│ 0 │ 2 │ 3 │
│ 0 │ 3 │ 6 │
│ 1 │ 4 │ 4 │
│ 1 │ 5 │ 9 │
│ 1 │ 6 │ 15 │
│ 1 │ 7 │ 22 │
│ 2 │ 8 │ 8 │
│ 2 │ 9 │ 17 │
│ 2 │ 10 │ 27 │
│ 2 │ 11 │ 38 │
│ 3 │ 12 │ 12 │
│ 3 │ 13 │ 25 │
│ 3 │ 14 │ 39 │
└──────────┴──────┴─────┘
如您所见，runningAccumulate 分别合并每组行的状态。
joinGet
该函数使您可以像从 字典 中一样从表中提取数据。使用指定的连接键从 Join 表中获取数据。
仅支持使用 ENGINE = Join(ANY, LEFT, <join_keys>) 语句创建的表。
语法
joinGet(join_storage_table_name, `value_column`, join_keys)
参数
join_storage_table_name— 一个 标识符，指示在何处执行搜索。value_column— 表中包含所需数据的列的名称。join_keys— 键列表。
将在默认数据库中搜索标识符（请参阅配置文件中的设置 default_database）。要覆盖默认数据库，请使用 USE db_name 或通过分隔符 db_name.db_table 指定数据库和表，如示例中所示。
返回值
- 返回与键列表对应的值列表。
如果源表中不存在某个键，则将根据表创建期间的 join_use_nulls 设置返回 0 或 null。有关 join_use_nulls 的更多信息，请参见 Join 操作。
示例
输入表
CREATE DATABASE db_test;
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 * FROM db_test.id_val;
┌─id─┬─val─┐
│ 4 │ 13 │
│ 2 │ 12 │
│ 1 │ 11 │
└────┴─────┘
查询
SELECT number, joinGet(db_test.id_val, 'val', toUInt32(number)) from numbers(4);
结果
┌─number─┬─joinGet('db_test.id_val', 'val', toUInt32(number))─┐
1. │ 0 │ 0 │
2. │ 1 │ 11 │
3. │ 2 │ 12 │
4. │ 3 │ 0 │
└────────┴────────────────────────────────────────────────────┘
可以在表创建期间使用设置 join_use_nulls 来更改源表中不存在键时返回的内容的行为。
CREATE DATABASE db_test;
CREATE TABLE db_test.id_val_nulls(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id) SETTINGS join_use_nulls=1;
INSERT INTO db_test.id_val_nulls VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val_nulls;
┌─id─┬─val─┐
│ 4 │ 13 │
│ 2 │ 12 │
│ 1 │ 11 │
└────┴─────┘
查询
SELECT number, joinGet(db_test.id_val_nulls, 'val', toUInt32(number)) from numbers(4);
结果
┌─number─┬─joinGet('db_test.id_val_nulls', 'val', toUInt32(number))─┐
1. │ 0 │ ᴺᵁᴸᴸ │
2. │ 1 │ 11 │
3. │ 2 │ 12 │
4. │ 3 │ ᴺᵁᴸᴸ │
└────────┴──────────────────────────────────────────────────────────┘
joinGetOrNull
与 joinGet 类似，但在键缺失时返回 NULL 而不是返回默认值。
语法
joinGetOrNull(join_storage_table_name, `value_column`, join_keys)
参数
join_storage_table_name— 一个 标识符，指示在何处执行搜索。value_column— 表中包含所需数据的列的名称。join_keys— 键列表。
将在默认数据库中搜索标识符（请参阅配置文件中的设置 default_database）。要覆盖默认数据库，请使用 USE db_name 或通过分隔符 db_name.db_table 指定数据库和表，如示例中所示。
返回值
- 返回与键列表对应的值列表。
如果源表中不存在某个键，则为该键返回 NULL。
示例
输入表
CREATE DATABASE db_test;
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 * FROM db_test.id_val;
┌─id─┬─val─┐
│ 4 │ 13 │
│ 2 │ 12 │
│ 1 │ 11 │
└────┴─────┘
查询
SELECT number, joinGetOrNull(db_test.id_val, 'val', toUInt32(number)) from numbers(4);
结果
┌─number─┬─joinGetOrNull('db_test.id_val', 'val', toUInt32(number))─┐
1. │ 0 │ ᴺᵁᴸᴸ │
2. │ 1 │ 11 │
3. │ 2 │ 12 │
4. │ 3 │ ᴺᵁᴸᴸ │
└────────┴──────────────────────────────────────────────────────────┘
catboostEvaluate
ClickHouse Cloud 中不提供此功能。
评估外部 catboost 模型。 CatBoost 是 Yandex 开发的用于机器学习的开源梯度提升库。接受 catboost 模型的路径和模型参数（特征）。返回 Float64。
语法
catboostEvaluate(path_to_model, feature_1, feature_2, ..., feature_n)
示例
SELECT feat1, ..., feat_n, catboostEvaluate('/path/to/model.bin', feat_1, ..., feat_n) AS prediction
FROM data_table
先决条件
- 构建 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 模型的信息，请参阅 训练和应用模型。
throwIf
如果参数 x 为真，则抛出异常。
语法
throwIf(x[, message[, error_code]])
参数
x- 要检查的条件。message- 提供自定义错误消息的常量字符串。可选。error_code- 提供自定义错误代码的常量整数。可选。
要使用 error_code 参数，必须启用配置参数 allow_custom_error_code_in_throwif。
示例
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.
identity
返回其参数。旨在用于调试和测试。允许取消使用索引，并获得完整扫描的查询性能。当分析查询以确定是否可能使用索引时，分析器会忽略 identity 函数中的所有内容。还会禁用常量折叠。
语法
identity(x)
示例
查询
SELECT identity(42);
结果
┌─identity(42)─┐
│ 42 │
└──────────────┘
getSetting
返回 自定义设置 的当前值。
语法
getSetting('custom_setting');
参数
custom_setting— 设置名称。 String。
返回值
- 设置的当前值。
示例
SET custom_a = 123;
SELECT getSetting('custom_a');
结果
123
另请参阅
getSettingOrDefault
返回 自定义设置 的当前值，如果未在当前配置文件中设置自定义设置，则返回第二个参数中指定的默认值。
语法
getSettingOrDefault('custom_setting', default_value);
参数
custom_setting— 设置名称。 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
另请参阅
isDecimalOverflow
检查 Decimal 值是否超出其精度或超出指定的精度。
语法
isDecimalOverflow(d, [p])
参数
返回值
1— Decimal 值的小数位数超过其精度允许的位数，0— Decimal 值满足指定的精度。
示例
查询
SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
isDecimalOverflow(toDecimal32(1000000000, 0)),
isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
isDecimalOverflow(toDecimal32(-1000000000, 0));
结果
1 1 1 1
countDigits
返回表示值所需的小数位数。
语法
countDigits(x)
参数
返回值
- 位数。 UInt8。
对于 Decimal 值，请考虑其比例：计算底层整数类型的结果，即 (value * scale)。例如：countDigits(42) = 2，countDigits(42.000) = 5，countDigits(0.04200) = 4。即，您可以检查 Decimal64 的十进制溢出，其中 countDecimal(x) > 18。它是 isDecimalOverflow 的慢速变体。
示例
查询
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));
结果
10 10 19 19 39 39
errorCodeToName
- 错误代码的文本名称。 LowCardinality(String)。
语法
errorCodeToName(1)
结果
UNSUPPORTED_METHOD
tcpPort
返回此服务器侦听的 native interface TCP 端口号。如果在分布式表的上下文中执行，则此函数生成一个普通列，其中包含与每个分片相关的值。否则，它会生成一个常量值。
语法
tcpPort()
参数
- 无。
返回值
- TCP 端口号。 UInt16。
示例
查询
SELECT tcpPort();
结果
┌─tcpPort()─┐
│ 9000 │
└───────────┘
另请参阅
currentProfiles
返回当前用户的当前 设置配置文件 列表。
命令 SET PROFILE 可用于更改当前设置配置文件。如果未使用命令 SET PROFILE，则该函数返回当前用户定义中指定的配置文件（请参阅 CREATE USER）。
语法
currentProfiles()
返回值
enabledProfiles
返回分配给当前用户的设置配置文件，包括显式分配和隐式分配。显式分配的配置文件与 currentProfiles 函数返回的配置文件相同。隐式分配的配置文件包括其他已分配配置文件的父配置文件、通过授予的角色分配的配置文件、通过其自身设置分配的配置文件以及主默认配置文件（请参阅主服务器配置文件中的 default_profile 部分）。
语法
enabledProfiles()
返回值
defaultProfiles
返回当前用户定义中指定的所有配置文件（请参阅 CREATE USER 语句）。
语法
defaultProfiles()
返回值
currentRoles
返回分配给当前用户的角色。可以使用 SET ROLE 语句更改角色。如果未使用 SET ROLE 语句，则函数 currentRoles 返回与 defaultRoles 相同的内容。
语法
currentRoles()
返回值
enabledRoles
返回当前角色的名称以及授予某些当前角色的角色。
语法
enabledRoles()
返回值
defaultRoles
返回当前用户登录时默认启用的角色。最初，这些是授予当前用户的所有角色（请参阅 GRANT），但可以使用 SET DEFAULT ROLE 语句更改。
语法
defaultRoles()
返回值
getServerPort
返回服务器端口号。当服务器未使用该端口时，会抛出异常。
语法
getServerPort(port_name)
参数
-
port_name— 服务器端口的名称。 String。可能的值- 'tcp_port'
- 'tcp_port_secure'
- 'http_port'
- 'https_port'
- 'interserver_http_port'
- 'interserver_https_port'
- 'mysql_port'
- 'postgresql_port'
- 'grpc_port'
- 'prometheus.port'
返回值
- 服务器端口号。 UInt16。
示例
查询
SELECT getServerPort('tcp_port');
结果
┌─getServerPort('tcp_port')─┐
│ 9000 │
└───────────────────────────┘
queryID
返回当前查询的 ID。可以通过 query_id 从 system.query_log 表中提取查询的其他参数。
与 initialQueryID 函数相比，queryID 可以在不同的分片上返回不同的结果（请参阅示例）。
语法
queryID()
返回值
- 当前查询的 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()─┐
│ 3 │
└─────────┘
initialQueryID
返回初始当前查询的 ID。可以通过 initial_query_id 从 system.query_log 表中提取查询的其他参数。
与 queryID 函数相比，initialQueryID 在不同的分片上返回相同的结果（请参阅示例）。
语法
initialQueryID()
返回值
- 初始当前查询的 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()─┐
│ 1 │
└─────────┘
partitionID
计算 分区 ID。
此函数速度较慢，不应为大量行调用。
语法
partitionID(x[, y, ...]);
参数
x— 要为其返回分区 ID 的列。y, ...— 要为其返回分区 ID 的其余 N 列（可选）。
返回值
- 行将属于的分区 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 │
└───┴───┴────────────────┴───────────────┘
┌─i─┬─j─┬─partitionID(i)─┬─_partition_id─┐
│ 2 │ 4 │ 2 │ 2 │
│ 2 │ 5 │ 2 │ 2 │
│ 2 │ 6 │ 2 │ 2 │
└───┴───┴────────────────┴───────────────┘
shardNum
返回在分布式查询中处理部分数据的分片的索引。索引从 1 开始。如果查询不是分布式的，则返回常量值 0。
语法
shardNum()
返回值
- 分片索引或常量
0。 UInt32。
示例
在以下示例中，使用了具有两个分片的配置。查询在每个分片上的 system.one 表上执行。
查询
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 │ 2 │ 2 │
│ 0 │ 1 │ 2 │
└───────┴────────────┴──────────────┘
另请参阅
shardCount
返回分布式查询的分片总数。如果查询不是分布式的，则返回常量值 0。
语法
shardCount()
返回值
- 分片总数或
0。 UInt32。
另请参阅
- shardNum() 函数示例也包含
shardCount()函数调用。
getOSKernelVersion
返回包含当前操作系统内核版本的字符串。
语法
getOSKernelVersion()
参数
- 无。
返回值
- 当前操作系统内核版本。 String。
示例
查询
SELECT getOSKernelVersion();
结果
┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘
zookeeperSessionUptime
返回当前 ZooKeeper 会话的正常运行时间，以秒为单位。
语法
zookeeperSessionUptime()
参数
- 无。
返回值
- 当前 ZooKeeper 会话的正常运行时间，以秒为单位。 UInt32。
示例
查询
SELECT zookeeperSessionUptime();
结果
┌─zookeeperSessionUptime()─┐
│ 286 │
└──────────────────────────┘
generateRandomStructure
生成随机表结构，格式为 column1_name column1_type, column2_name column2_type, ...。
语法
generateRandomStructure([number_of_columns, seed])
参数
number_of_columns— 结果表结构中所需的列数。如果设置为 0 或Null，则列数将为 1 到 128 的随机数。默认值：Null。seed- 用于生成稳定结果的随机种子。如果未指定种子或设置为Null，则会随机生成。
所有参数必须为常量。
返回值
- 随机生成的表结构。 String。
示例
查询
SELECT generateRandomStructure()
结果
┌─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)
结果
┌─generateRandomStructure(1)─┐
│ c1 Map(UInt256, UInt16) │
└────────────────────────────┘
查询
SELECT generateRandomStructure(NULL, 33)
结果
┌─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))) │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
注意：复杂类型（Array、Tuple、Map、Nested）的最大嵌套深度限制为 16。
此函数可以与 generateRandom 一起使用，以生成完全随机的表。
structureToCapnProtoSchema
将 ClickHouse 表结构转换为 CapnProto 模式。
语法
structureToCapnProtoSchema(structure)
参数
structure— 表结构，格式为column1_name column1_type, column2_name column2_type, ...。root_struct_name— CapnProto 模式中根结构的名称。默认值 -Message。
返回值
- CapnProto 模式。 String。
示例
查询
SELECT structureToCapnProtoSchema('column1 String, column2 UInt32, column3 Array(String)') FORMAT RawBLOB
结果
@0xf96402dd754d0eb7;
struct Message
{
column1 @0 : Data;
column2 @1 : UInt32;
column3 @2 : List(Data);
}
查询
SELECT structureToCapnProtoSchema('column1 Nullable(String), column2 Tuple(element1 UInt32, element2 Array(String)), column3 Map(String, String)') FORMAT RawBLOB
结果
@0xd1c8320fecad2b7f;
struct Message
{
struct Column1
{
union
{
value @0 : Data;
null @1 : Void;
}
}
column1 @0 : Column1;
struct Column2
{
element1 @0 : UInt32;
element2 @1 : List(Data);
}
column2 @1 : Column2;
struct Column3
{
struct Entry
{
key @0 : Data;
value @1 : Data;
}
entries @0 : List(Entry);
}
column3 @2 : Column3;
}
查询
SELECT structureToCapnProtoSchema('column1 String, column2 UInt32', 'Root') FORMAT RawBLOB
结果
@0x96ab2d4ab133c6e1;
struct Root
{
column1 @0 : Data;
column2 @1 : UInt32;
}
structureToProtobufSchema
将 ClickHouse 表结构转换为 Protobuf 模式。
语法
structureToProtobufSchema(structure)
参数
structure— 表结构，格式为column1_name column1_type, column2_name column2_type, ...。root_message_name— Protobuf 模式中根消息的名称。默认值 -Message。
返回值
- Protobuf 模式。 String。
示例
查询
SELECT structureToProtobufSchema('column1 String, column2 UInt32, column3 Array(String)') FORMAT RawBLOB
结果
syntax = "proto3";
message Message
{
bytes column1 = 1;
uint32 column2 = 2;
repeated bytes column3 = 3;
}
查询
SELECT structureToProtobufSchema('column1 Nullable(String), column2 Tuple(element1 UInt32, element2 Array(String)), column3 Map(String, String)') FORMAT RawBLOB
结果
syntax = "proto3";
message Message
{
bytes column1 = 1;
message Column2
{
uint32 element1 = 1;
repeated bytes element2 = 2;
}
Column2 column2 = 2;
map<string, bytes> column3 = 3;
}
查询
SELECT structureToProtobufSchema('column1 String, column2 UInt32', 'Root') FORMAT RawBLOB
结果
syntax = "proto3";
message Root
{
bytes column1 = 1;
uint32 column2 = 2;
}
formatQuery
返回给定 SQL 查询的格式化版本，可能是多行的。
如果查询格式不正确，则抛出异常。要返回 NULL，可以使用函数 formatQueryOrNull()。
语法
formatQuery(query)
formatQueryOrNull(query)
参数
query- 要格式化的 SQL 查询。 String
返回值
- 格式化后的查询。 String。
示例
SELECT formatQuery('select a, b FRom tab WHERE a > 3 and b < 3');
结果
┌─formatQuery('select a, b FRom tab WHERE a > 3 and b < 3')─┐
│ SELECT
a,
b
FROM tab
WHERE (a > 3) AND (b < 3) │
└───────────────────────────────────────────────────────────────┘
formatQuerySingleLine
类似于 formatQuery()，但返回的格式化字符串不包含换行符。
如果查询格式不正确，则抛出异常。要返回 NULL，可以使用函数 formatQuerySingleLineOrNull()。
语法
formatQuerySingleLine(query)
formatQuerySingleLineOrNull(query)
参数
query- 要格式化的 SQL 查询。 String
返回值
- 格式化后的查询。 String。
示例
SELECT formatQuerySingleLine('select a, b FRom tab WHERE a > 3 and b < 3');
结果
┌─formatQuerySingleLine('select a, b FRom tab WHERE a > 3 and b < 3')─┐
│ SELECT a, b FROM tab WHERE (a > 3) AND (b < 3) │
└─────────────────────────────────────────────────────────────────────────┘
variantElement
从 Variant 列中提取具有指定类型的列。
语法
variantElement(variant, type_name, [, default_value])
参数
variant— Variant 列。 Variant。type_name— 要提取的 Variant 类型名称。 String。default_value- 如果 Variant 没有指定类型的变体，则将使用的默认值。可以是任何类型。可选。
返回值
- 具有指定类型的
Variant列的子列。
示例
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
返回 Variant 列中每行的变体类型名称。如果行包含 NULL，则返回 'None'。
语法
variantType(variant)
参数
variant— Variant 列。 Variant。
返回值
- Enum8 列，包含每行的变体类型名称。
示例
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) │
└────────────────┘
SELECT toTypeName(variantType(v)) FROM test LIMIT 1;
┌─toTypeName(variantType(v))──────────────────────────────────────────┐
│ Enum8('None' = -1, 'Array(UInt64)' = 0, 'String' = 1, 'UInt64' = 2) │
└─────────────────────────────────────────────────────────────────────┘
minSampleSizeConversion
计算 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。
返回值
一个名为 Tuple 的元组，包含 3 个元素
"minimum_sample_size"— 所需的样本量。 Float64。"detect_range_lower"— 使用返回的所需样本量无法检测到的值范围的下限（即，所有小于或等于"detect_range_lower"的值都可以使用提供的alpha和power检测到）。计算公式为baseline - mde。 Float64。"detect_range_upper"— 使用返回的所需样本量无法检测到的值范围的上限（即，所有大于或等于"detect_range_upper"的值都可以使用提供的alpha和power检测到）。计算公式为baseline + mde。 Float64。
示例
以下查询计算基线转化率为 25%、MDE 为 3%、显著性水平为 5%、所需统计功效为 80% 的 A/B 测试所需的样本量
SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size;
结果
┌─sample_size───────────────────┐
│ (3396.077603219163,0.22,0.28) │
└───────────────────────────────┘
minSampleSizeContinuous
计算 A/B 测试中比较两个样本的连续指标均值所需的最小样本量。
语法
minSampleSizeContinous(baseline, sigma, mde, power, alpha)
别名：minSampleSizeContinous
使用 这篇文章 中描述的公式。假设处理组和对照组的大小相等。返回一个组所需的样本量（即整个实验所需的样本量是返回值的两倍）。还假设测试指标在处理组和对照组中具有相等的方差。
参数
baseline— 指标的基线值。 Integer 或 Float。sigma— 指标的基线标准差。 Integer 或 Float。mde— 最小可检测效应 (MDE)，以基线值的百分比表示（例如，对于基线值 112.25，MDE 0.03 表示预期变化为 112.25 ± 112.25*0.03）。 Integer 或 Float。power— 测试所需的统计功效（1 - II 类错误的概率）。 Integer 或 Float。alpha— 测试所需的显著性水平（I 类错误的概率）。 Integer 或 Float。
返回值
一个名为 Tuple 的元组，包含 3 个元素
"minimum_sample_size"— 所需的样本量。 Float64。"detect_range_lower"— 使用返回的所需样本量无法检测到的值范围的下限（即，所有小于或等于"detect_range_lower"的值都可以使用提供的alpha和power检测到）。计算公式为baseline * (1 - mde)。 Float64。"detect_range_upper"— 使用返回的所需样本量无法检测到的值范围的上限（即，所有大于或等于"detect_range_upper"的值都可以使用提供的alpha和power检测到）。计算公式为baseline * (1 + mde)。 Float64。
示例
以下查询计算基线值为 112.25、标准差为 21.1、MDE 为 3%、显著性水平为 5%、所需统计功效为 80% 的指标的 A/B 测试所需的样本量
SELECT minSampleSizeContinous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size;
结果
┌─sample_size───────────────────────────┐
│ (616.2931945826209,108.8825,115.6175) │
└───────────────────────────────────────┘
connectionId
检索提交当前查询的客户端的连接 ID，并将其作为 UInt64 整数返回。
语法
connectionId()
别名：connection_id。
参数
无。
返回值
当前的连接 ID。 UInt64。
实现细节
此函数在调试场景或 MySQL 处理程序内部使用时最有用。它是为了与 MySQL 的 CONNECTION_ID 函数 兼容而创建的。它通常不用于生产查询中。
示例
查询
SELECT connectionId();
0
getClientHTTPHeader
获取 HTTP 标头的值。
如果不存在此类标头，或者当前请求不是通过 HTTP 接口执行的，则该函数返回一个空字符串。某些 HTTP 标头（例如，Authentication 和 X-ClickHouse-*）受到限制。
该函数需要启用设置 allow_get_client_http_header。出于安全原因，默认情况下未启用此设置，因为某些标头（例如 Cookie）可能包含敏感信息。
对于此函数，HTTP 标头区分大小写。
如果在分布式查询的上下文中使用该函数，则仅在发起节点上返回非空结果。
showCertificate
如果已配置，则显示有关当前服务器的安全套接字层 (SSL) 证书的信息。有关如何配置 ClickHouse 以使用 OpenSSL 证书来验证连接的更多信息，请参阅 配置 SSL-TLS。
语法
showCertificate()
返回值
示例
查询
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'}
lowCardinalityIndices
返回 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)─┐
1. │ ab │ 1 │
2. │ cd │ 2 │
3. │ ab │ 1 │
4. │ ab │ 1 │
5. │ df │ 3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
6. │ ef │ 1 │
7. │ cd │ 2 │
8. │ ab │ 3 │
9. │ cd │ 2 │
10. │ ef │ 1 │
└────┴──────────────────────────┘
lowCardinalityKeys
返回 LowCardinality 列的字典值。如果块小于或大于字典大小，则结果将被截断或使用默认值扩展。由于 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, lowCardinalityKeys(s) FROM test;
结果
┌─s──┬─lowCardinalityKeys(s)─┐
1. │ ef │ │
2. │ cd │ ef │
3. │ ab │ cd │
4. │ cd │ ab │
5. │ ef │ │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
6. │ ab │ │
7. │ cd │ ab │
8. │ ab │ cd │
9. │ ab │ df │
10. │ df │ │
└────┴───────────────────────┘
displayName
从 config 返回 display_name 的值，如果未设置，则返回服务器完全限定域名 (FQDN)。
语法
displayName()
返回值
- 从 config 返回的
display_name值，如果未设置，则返回服务器 FQDN。 String。
示例
display_name 可以在 config.xml 中设置。例如，配置了 display_name 为 'production' 的服务器
<!-- It is the name that will be shown in the clickhouse-client.
By default, anything with "production" will be highlighted in red in query prompt.
-->
<display_name>production</display_name>
查询
SELECT displayName();
结果
┌─displayName()─┐
│ production │
└───────────────┘
transactionID
返回 事务 的 ID。
此函数是实验性功能集的一部分。通过将此设置添加到您的配置来启用实验性事务支持
<clickhouse>
<allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>
有关更多信息，请参阅页面 事务 (ACID) 支持。
语法
transactionID()
返回值
-
返回一个元组，其中包含
start_csn、local_tid和host_id。 Tuple。 -
start_csn：全局序列号，此事务开始时看到的最新提交时间戳。 UInt64。 -
local_tid：本地序列号，对于此主机在特定 start_csn 中启动的每个事务都是唯一的。 UInt64。 -
host_id：启动此事务的主机的 UUID。 UUID。
示例
查询
BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;
结果
┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘
transactionLatestSnapshot
返回可用于读取的 事务 的最新快照（提交序列号）。
此函数是实验性功能集的一部分。通过将此设置添加到您的配置来启用实验性事务支持
<clickhouse>
<allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>
有关更多信息，请参阅页面 事务 (ACID) 支持。
语法
transactionLatestSnapshot()
返回值
- 返回事务的最新快照 (CSN)。 UInt64
示例
查询
BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;
结果
┌─transactionLatestSnapshot()─┐
│ 32 │
└─────────────────────────────┘
transactionOldestSnapshot
返回某些正在运行的 事务 可见的旧快照（提交序列号）。
此函数是实验性功能集的一部分。通过将此设置添加到您的配置来启用实验性事务支持
<clickhouse>
<allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>
有关更多信息，请参阅页面 事务 (ACID) 支持。
语法
transactionOldestSnapshot()
返回值
- 返回事务的旧快照 (CSN)。 UInt64
示例
查询
BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;
结果
┌─transactionOldestSnapshot()─┐
│ 32 │
└─────────────────────────────┘
getSubcolumn
接受表表达式或标识符以及包含子列名称的常量字符串，并返回从表达式中提取的请求子列。
语法
getSubcolumn(col_name, subcol_name)
参数
返回值
- 返回提取的子列。
示例
查询
CREATE TABLE t_arr (arr Array(Tuple(subcolumn1 UInt32, subcolumn2 String))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO t_arr VALUES ([(1, 'Hello'), (2, 'World')]), ([(3, 'This'), (4, 'is'), (5, 'subcolumn')]);
SELECT getSubcolumn(arr, 'subcolumn1'), getSubcolumn(arr, 'subcolumn2') FROM t_arr;
结果
┌─getSubcolumn(arr, 'subcolumn1')─┬─getSubcolumn(arr, 'subcolumn2')─┐
1. │ [1,2] │ ['Hello','World'] │
2. │ [3,4,5] │ ['This','is','subcolumn'] │
└─────────────────────────────────┴─────────────────────────────────┘
getTypeSerializationStreams
枚举数据类型的流路径。
此函数旨在供开发人员使用。
语法
getTypeSerializationStreams(col)
参数
col— 列或数据类型的字符串表示形式，将从中检测数据类型。
返回值
示例
查询
SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2));
结果
┌─getTypeSerializationStreams(('a', 1, 'b', 2))─────────────────────────────────────────────────────────────────────────┐
1. │ ['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}'] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
查询
SELECT getTypeSerializationStreams('Map(String, Int64)');
结果
┌─getTypeSerializationStreams('Map(String, Int64)')────────────────────────────────────────────────────────────────┐
1. │ ['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}'] │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
globalVariable
接受常量字符串参数，并返回具有该名称的全局变量的值。此函数旨在与 MySQL 兼容，对于 ClickHouse 的正常运行来说不是必需的或有用的。仅定义了少数虚拟全局变量。
语法
globalVariable(name)
参数
name— 全局变量名称。 String。
返回值
- 返回变量
name的值。
示例
查询
SELECT globalVariable('max_allowed_packet');
结果
┌─globalVariable('max_allowed_packet')─┐
│ 67108864 │
└──────────────────────────────────────┘
getMaxTableNameLengthForDatabase
返回指定数据库中最大表名称长度。
语法
getMaxTableNameLengthForDatabase(database_name)
参数
database_name— 指定数据库的名称。 String。
返回值
- 返回最大表名称的长度。
示例
查询
SELECT getMaxTableNameLengthForDatabase('default');
结果
┌─getMaxTableNameLengthForDatabase('default')─┐
│ 206 │
└─────────────────────────────────────────────┘