其他函数
hostName
返回执行此函数的主机的名称。如果函数在远程服务器上执行(分布式处理),则返回远程服务器名称。如果函数在分布式表的上下文中执行,它会生成一个包含与每个分片相关的值的普通列。否则它会生成一个常量值。
语法
hostName()
返回值
- 主机名。 字符串。
getMacro
从服务器配置的 宏 部分返回命名值。
语法
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
— 类型为 字符串 的值。必须转义反斜杠。
返回值
包含以下内容的字符串
- 输入字符串在其最后一个斜杠或反斜杠之后的尾部。如果输入字符串以斜杠或反斜杠结尾(例如
/
或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 中,查询以 块(块)的形式进行处理。此函数返回调用该函数的块的大小(行数)。
语法
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。
示例
对于 字符串 参数,该函数返回字符串长度 + 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
:布尔值。 布尔类型。
布尔参数被忽略。它仅出于与 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
。
示例
查询
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)
示例
查询
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])
参数
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。
语法
formatReadableSize(x)
参数
x
:包含 ISO/IEC 80000-13 或十进制字节单位的可读大小(字符串)。
返回值
- 字节数,四舍五入到最接近的整数(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 或十进制字节单位的可读大小(字符串)。
返回值
- 字节数,四舍五入到最接近的整数,或者如果无法解析输入则返回 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 或十进制字节单位的可读大小(字符串)。
返回值
- 字节数,四舍五入到最接近的整数,或者如果无法解析输入则返回 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
返回 a 和 b 中较小的值。
语法
least(a, b)
greatest
返回 a 和 b 中较大的值。
语法
greatest(a, b)
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
返回包含该行的 数据块 的单调递增序列号。返回的数据块编号以尽力而为的方式更新,即可能不完全准确。
语法
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
处理的数据块,返回当前行的行号。每个数据块返回的行号从 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])
函数的结果取决于受影响的数据块和块中数据的顺序。
仅返回当前处理的数据块内的邻居。由于这种容易出错的行为,该函数已**弃用**,请改用合适的窗口函数。
计算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,对于后续行返回与前一行的差值。
仅返回当前处理的数据块内的差值。由于这种容易出错的行为,该函数已**弃用**,请改用合适的窗口函数。
函数的结果取决于受影响的数据块和块中数据的顺序。
计算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
此函数已**弃用**(参见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 地址。以字符串格式返回相应的 MAC 地址,格式为 AA:BB:CC:DD:EE:FF(以冒号分隔的十六进制数字)。
语法
MACNumToString(num)
MACStringToNum
MACNumToString 的反函数。如果 MAC 地址格式无效,则返回 0。
语法
MACStringToNum(s)
MACStringToOUI
给定格式为 AA:BB:CC:DD:EE:FF(以冒号分隔的十六进制数字)的 MAC 地址,返回前三个八位字节作为 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
中。这允许通过相应的条件选择索引范围内的数
语法
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
返回托管数据库持久性的文件系统中的可用空间量。返回的值始终小于总可用空间(filesystemFree),因为某些空间保留给操作系统。
语法
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
返回文件系统容量(以字节为单位)。需要配置数据目录的路径。
语法
filesystemCapacity()
返回值
- 文件系统容量(以字节为单位)。 UInt64。
示例
查询
SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";
结果
┌─Capacity──┐
│ 39.32 GiB │
└───────────┘
initializeAggregation
根据单个值计算聚合函数的结果。此函数可用于使用组合器-State初始化聚合函数。您可以创建聚合函数的状态并将它们插入到类型为AggregateFunction的列中,或使用初始化的聚合作为默认值。
语法
initializeAggregation (aggregate_function, arg1, arg2, ..., argN)
参数
aggregate_function
— 要初始化的聚合函数的名称。 字符串。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
给定聚合函数的状态,此函数返回聚合的结果(或在使用 -状态 组合器时返回最终状态)。
语法
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
累积数据块的每一行的聚合函数的状态。
对于每个新的数据块,状态都会重置。由于这种易于出错的行为,该函数已 **弃用**,请改用合适的窗口函数。
语法
runningAccumulate(agg_state[, grouping]);
参数
agg_state
— 聚合函数的状态。 AggregateFunction。grouping
— 分组键。可选。如果grouping
值发生更改,则函数的状态将重置。它可以是 支持的数据类型 中的任何一种,这些数据类型已定义了相等运算符。
返回值
- 每个结果行都包含聚合函数的结果,该结果累积了从 0 到当前位置的所有输入行。
runningAccumulate
对于每个新的数据块或grouping
值更改时重置状态。
类型取决于使用的聚合函数。
示例
考虑如何使用 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
此函数允许您像从 字典 中提取数据一样从表中提取数据。使用指定的连接键从 连接 表中获取数据。
仅支持使用 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
的更多信息,请参阅 连接操作。
示例
输入表
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
— 设置名称。 字符串。
返回值
- 设置的当前值。
示例
SET custom_a = 123;
SELECT getSetting('custom_a');
结果
123
另请参阅
getSettingOrDefault
返回 自定义设置 的当前值,如果当前配置文件中未设置自定义设置,则返回第二个参数中指定的默认值。
语法
getSettingOrDefault('custom_setting', default_value);
参数
custom_setting
— 设置名称。 字符串。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
。也就是说,您可以使用 countDecimal(x) > 18
检查 Decimal64
的十进制溢出。这是 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
返回此服务器侦听的 本机接口 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))) │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
注意:复杂类型(数组、元组、映射、嵌套)的最大嵌套深度限制为 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
— 要提取的变体类型的名称。 String。default_value
- 如果变体没有指定类型的变体,则将使用的默认值。可以是任何类型。可选。
返回值
- 具有指定类型的
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。
返回值
具有 3 个元素的命名 Tuple
"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。
返回值
具有 3 个元素的命名 Tuple
"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。
示例
以下查询计算对指标进行 A/B 测试所需的样本量,该指标的基线值为 112.25,标准差为 21.1,MDE 为 3%,显著性水平为 5%,所需的统计功效为 80%。
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
返回 配置 中的 display_name
值,如果未设置则返回服务器完全限定域名 (FQDN)。
语法
displayName()
返回值
- 配置中的
display_name
值,如果未设置则返回服务器 FQDN。 String。
示例
可以在 config.xml
中设置 display_name
。例如,一个服务器的 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 保持兼容性。
语法
globalVariable(name)
参数
name
— 全局变量名称。 String。
返回值
- 返回变量
name
的值。
示例
查询
SELECT globalVariable('max_allowed_packet');
结果
┌─globalVariable('max_allowed_packet')─┐
│ 67108864 │
└──────────────────────────────────────┘