其他函数
hostName
返回执行此函数的主机名称。如果该函数在远程服务器上执行（分布式处理），则返回远程服务器名称。 如果该函数在分布式表的上下文中执行，则生成一个正常的列，其中的值与每个分片相关。否则，它会生成一个常量值。
语法
返回值
- 主机名。字符串。
getMacro
从服务器配置的 macros 部分返回一个命名值。
语法
参数
name— 要从<macros>部分检索的宏名称。字符串。
返回值
- 指定宏的值。字符串。
示例
服务器配置文件中 <macros> 部分的示例：
查询：
结果：
同样的值可以通过以下方式检索：
fqdn
返回 ClickHouse 服务器的完全合格域名。
语法
别名：fullHostName, FQDN。
返回值
- 包含完全合格域名的字符串。字符串。
示例
结果：
basename
提取字符串最后一个斜杠或反斜杠后的尾部。此函数通常用于从路径中提取文件名。
参数
expr— 字符串 类型的值。反斜杠必须被转义。
返回值
一个字符串，包含：
- 输入字符串最后一个斜杠或反斜杠后的尾部。如果输入字符串以斜杠或反斜杠结尾（例如
/或c:\），则该函数返回一个空字符串。 - 如果没有斜杠或反斜杠，则返回原始字符串。
示例
查询：
结果：
查询：
结果：
查询：
结果：
visibleWidth
计算将值以文本格式（制表符分隔）输出时的近似宽度。 此函数由系统用于实现 Pretty formats。
NULL 表示为与 Pretty 格式中的 NULL 相对应的字符串。
语法
示例
查询：
结果：
toTypeName
返回传入参数的类型名称。
如果传入 NULL，该函数返回类型 Nullable(Nothing)，这对应于 ClickHouse 的内部 NULL 表示。
语法
参数
value— 任意类型的值。
返回值
- 输入值的数据类型名称。字符串。
示例
查询：
结果：
blockSize
在 ClickHouse 中，查询以 blocks（块）方式处理。 此函数返回对该函数调用的块的大小（行数）。
语法
示例
查询：
结果：
byteSize
返回其参数在内存中未压缩的字节大小的估算。
语法
参数
argument— 值。
返回值
- 参数在内存中字节大小的估算。UInt64。
示例
对于 字符串 参数，该函数返回字符串长度 + 9（终止零 + 长度）。
查询：
结果：
查询：
结果：
如果函数有多个参数，那么函数将它们的字节大小累加。
查询：
结果：
materialize
将常量转换为包含单个值的完整列。 完整列和常量在内存中的表示形式不同。 函数通常对正常和常量参数执行不同的代码，但结果通常应该是相同的。 此函数可用于调试此行为。
语法
参数
x— 常量。常量。
返回值
- 包含单个值
x的列。
示例
在下面的示例中，countMatches 函数期望一个常量的第二个参数。
此行为可以通过使用 materialize 函数将常量转换为一个完整列来调试，从而验证该函数对非常量参数抛出错误。
查询：
结果：
ignore
接受任意参数并无条件返回 0。
参数仍会在内部评估，这使其在基准测试等情况下非常有用。
语法
参数
- 接受任意数量的任意类型的参数，包括
NULL。
返回值
- 返回
0。
示例
查询：
结果：
sleep
用于在查询的执行中引入延迟或暂停。主要用于测试和调试目的。
语法
参数
返回值
此函数不返回任何值。
示例
此函数不返回任何值。不过，如果使用 clickhouse client 运行该函数，您将看到类似的内容：
此查询将在完成之前暂停 2 秒。在此期间，不会返回任何结果，查询看起来会挂起或无响应。
实现细节
sleep() 函数通常不在生产环境中使用，因为它可能对查询性能和系统响应能力产生负面影响。不过，在以下情况下可以有用：
- 测试：在测试或基准测试 ClickHouse 时，您可能希望模拟延迟或引入暂停，以观察系统在特定条件下的行为。
- 调试：如果您需要检查系统的状态或在特定时间点查询的执行情况，可以使用
sleep()引入暂停，从而允许您检查或收集相关信息。 - 模拟：在某些情况下，您可能希望模拟现实世界场景，其中发生延迟或暂停，例如网络延迟或外部系统依赖性。
重要的是要明智地使用 sleep() 函数，仅在必要时使用，因为这可能会对 ClickHouse 系统的整体性能和响应能力产生潜在影响。
sleepEachRow
暂停查询的执行，每行结果集暂停指定的秒数。
语法
参数
返回值
此函数返回与接收到的输入值相同的值，不会对其进行修改。
示例
但输出会延迟，每行之间有 0.5 秒的暂停。
sleepEachRow() 函数主要用于测试和调试目的，类似于 sleep() 函数。它允许您在处理每一行中模拟延迟或引入暂停，这在以下情况中可能会很有用：
- 测试：在测试或基准测试 ClickHouse 在特定条件下的性能时，您可以使用
sleepEachRow()模拟延迟或为处理的每行引入暂停。 - 调试：如果您需要检查系统状态或每行处理的查询执行情况，可以使用
sleepEachRow()引入暂停，从而允许您检查或收集相关信息。 - 模拟：在某些情况下，您可能希望模拟现实场景，在处理每行时发生延迟或暂停，例如在处理外部系统或网络延迟时。
与 sleep() 函数 一样，重要的是要明智地使用 sleepEachRow()，并仅在必要时使用，因为它可能会显著影响 ClickHouse 系统的整体性能和响应能力，尤其是在处理大结果集时。
currentDatabase
返回当前数据库的名称。
在需要指定数据库的 CREATE TABLE 查询的表引擎参数中非常有用。
语法
返回值
- 返回当前数据库名称。字符串。
示例
查询：
结果：
currentUser
返回当前用户的名称。如果是分布式查询，则返回发起查询的用户名称。
语法
别名：user(), USER(), current_user()。别名不区分大小写。
返回值
示例
结果：
currentSchemas
返回一个包含当前数据库架构名称的单元素数组。
语法
别名：current_schemas。
参数
bool：布尔值。布尔。
布尔参数会被忽略。它的存在仅仅是为了与 PostgreSQL 中该函数的实现保持兼容性。
返回值
- 返回一个包含当前数据库名称的单元素数组。
示例
结果：
isConstant
返回参数是否是常量表达式。
常量表达式是查询分析期间结果已知的表达式，即在执行之前。例如，针对 literals 的表达式是常量表达式。
此函数主要用于开发、调试和演示。
语法
参数
x— 要检查的表达式。
返回值
示例
查询：
结果：
查询：
结果：
查询：
结果：
hasColumnInTable
给定数据库名称、表名称和常量字符串列名称，如果给定列存在，则返回 1，否则返回 0。
语法
参数
database: 数据库名称。字符串字面量table: 表名称。字符串字面量column: 列名称。字符串字面量hostname: 用于进行检查的远程服务器名称。字符串字面量username: 远程服务器的用户名。字符串字面量password: 远程服务器的密码。字符串字面量
返回值
- 如果给定列存在，返回
1。 - 否则返回
0。
实现细节
对于嵌套数据结构中的元素，函数检查列的存在性。对于嵌套数据结构本身，函数返回 0。
示例
查询：
hasThreadFuzzer
返回线程模糊器是否有效。可以在测试中使用，以防止运行时间过长。
语法
bar
构建柱状图。
bar(x, min, max, width) 绘制一个宽度与 (x - min) 成比例，并在 x = max 时等于 width 字符的带状图。
参数
x— 要显示的大小。min, max— 整数常量。值必须适合Int64。width— 常量，正整数，可以是小数。
带状图的绘制精确到符号的八分之一。
示例：
transform
根据某些元素到其他元素的显式映射转换值。 此函数有两种变体：
transform(x, array_from, array_to, default)
x – 要转换的值。
array_from – 要转换的常量值数组。
array_to – 要将 from 中的值转换到的常量值数组。
default – 如果 x 不等于 from 中的任何值，则使用该值。
array_from 和 array_to 必须具有相同数量的元素。
签名：
对于 x 等于 array_from 中的一个元素，函数返回 array_to 中对应的元素，即在相同数组索引处的元素。否则，它返回 default。如果 array_from 中存在多个匹配元素，则返回第一个的对应元素。
transform(T, Array(T), Array(U), U) -> U
T 和 U 可以是数字、字符串或日期或日期时间类型。
相同的字母（T 或 U）表示类型必须是互相兼容的，不一定相等。
例如，第一个参数可以是类型为 Int64，而第二个参数可以是类型为 Array(UInt16)。
示例：
transform(x, array_from, array_to)
与另一个变体相似，但没有 'default' 参数。如果找不到匹配，返回 x。
示例：
formatReadableDecimalSize
给定一个大小（字节数），此函数返回一个可读的、四舍五入的大小，并带有后缀（KB、MB 等）的字符串。
此函数的反操作是 parseReadableSize、parseReadableSizeOrZero 和 parseReadableSizeOrNull。
语法
示例
查询：
结果：
formatReadableSize
给定一个大小（字节数），此函数返回一个可读的、四舍五入的大小，并带有后缀（KiB、MiB 等）的字符串。
此函数的反操作是 parseReadableSize、parseReadableSizeOrZero 和 parseReadableSizeOrNull。
语法
别名：FORMAT_BYTES。
此函数接受任何数字类型作为输入，但在内部会将其转换为 Float64。对于大值，结果可能不理想。
示例
查询：
结果：
formatReadableQuantity
给定一个数字，此函数返回一个带后缀（千、百万、十亿等）四舍五入的数字字符串。
语法
此函数接受任何数字类型作为输入，但在内部会将其转换为 Float64。对于大值，结果可能不理想。
示例
查询：
结果：
formatReadableTimeDelta
给定一个时间间隔（增量）以秒为单位，此函数返回一个时间增量字符串，包含年/月/天/小时/分钟/秒/毫秒/微秒/纳秒。
语法
此函数接受任何数字类型作为输入，但在内部会将其转换为 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。
- 可接受的值：
示例
parseReadableSize
给定一个包含字节大小的字符串和 B、KiB、KB、MiB、MB 等单位（即 ISO/IEC 80000-13 或十进制字节单位），该函数返回对应的字节数。
如果函数无法解析输入值，则抛出异常。
此函数的反操作是 formatReadableSize 和 formatReadableDecimalSize。
语法
参数
x: 带有 ISO/IEC 80000-13 或十进制字节单位的可读大小 (字符串)。
返回值
- 字节数，四舍五入到最接近的整数 (UInt64)。
示例
parseReadableSizeOrNull
给定一个包含字节大小的字符串和 B、KiB、KB、MiB、MB 等单位（即 ISO/IEC 80000-13 或十进制字节单位），该函数返回对应的字节数。
如果函数无法解析输入值，则返回 NULL。
此函数的反操作是 formatReadableSize 和 formatReadableDecimalSize。
语法
参数
x: 带有 ISO/IEC 80000-13 或十进制字节单位的可读大小 (字符串)。
返回值
- 字节数，四舍五入到最接近的整数，或者如果无法解析输入，则为 NULL（Nullable(UInt64)）。
示例
parseReadableSizeOrZero
给定一个包含字节大小的字符串和 B、KiB、KB、MiB、MB 等单位（即 ISO/IEC 80000-13 或十进制字节单位），该函数返回对应的字节数。 如果函数无法解析输入值，则返回 0。
此函数的反操作是 formatReadableSize 和 formatReadableDecimalSize。
语法
参数
x: 带有 ISO/IEC 80000-13 或十进制字节单位的可读大小 (字符串)。
返回值
- 字节数，四舍五入到最接近的整数，或者如果无法解析输入，则返回 0 (UInt64)。
示例
parseTimeDelta
解析一系列数字后跟类似时间单位的内容。
语法
参数
timestr— 一系列数字后跟类似时间单位的内容。
返回值
- 一个浮点数，表示秒数。
示例
查询：
least
返回一个或多个输入参数中的最小参数。NULL 参数会被忽略。
语法
版本 24.12 引入了一个向后不兼容的更改，即 NULL 值被忽略，而之前如果参数中有一个 NULL，则返回 NULL。要保持以前的行为，请将设置 least_greatest_legacy_null_behavior （默认：false）设置为 true。
greatest
返回一个或多个输入参数中的最大参数。NULL 参数会被忽略。
语法
版本 24.12 引入了一个向后不兼容的更改，即 NULL 值被忽略，而之前如果参数中有一个 NULL，则返回 NULL。要保持以前的行为，请将设置 least_greatest_legacy_null_behavior （默认：false）设置为 true。
uptime
返回服务器的运行时间（以秒为单位）。 如果在分布式表的上下文中执行，则此函数生成一个与每个分片相关的正常列的值。否则，它会产生一个常量值。
语法
返回值
- 以秒为单位的时间值。UInt32。
示例
查询：
结果：
version
以字符串形式返回 ClickHouse 的当前版本，其格式为：
- 主版本
- 次版本
- 修补版本
- 自上一个稳定版本以来的提交数量。
如果在分布式表的上下文中执行，则此函数生成一个与每个分片相关的正常列的值。否则，它会产生一个常量值。
语法
参数
无。
返回值
- ClickHouse 的当前版本。字符串。
实现细节
无。
示例
查询：
结果：
buildId
返回由编译器为运行的 ClickHouse 服务器二进制文件生成的构建 ID。 如果在分布式表的上下文中执行，则此函数生成一个与每个分片相关的正常列的值。否则，它会产生一个常量值。
语法
blockNumber
返回包含该行的 block 的单调递增序列号。 返回的块号基于最佳努力更新，即它可能不完全准确。
语法
返回值
- 存在该行中的数据块的序列号。UInt64。
示例
查询：
结果：
rowNumberInBlock
返回 rowNumberInBlock 处理的每个 block 的当前行号。
返回的数字从每个块的 0 开始。
语法
返回值
- 从 0 开始的数据块中行的序号。UInt64。
示例
查询：
结果：
rowNumberInAllBlocks
返回由 rowNumberInAllBlocks 处理的每行唯一行号。返回的数字从 0 开始。
语法
返回值
- 从 0 开始的数据块中行的序号。UInt64。
示例
查询：
结果：
normalizeQuery
用占位符 ? 替换文字、文字序列和复杂别名（包含空格、超过两个数字或至少 36 字节长的内容，例如 UUID）。
语法
参数
x— 字符序列。字符串。
返回值
- 带占位符的字符序列。字符串。
示例
查询：
结果：
normalizeQueryKeepNames
用占位符 ? 替换文字和文字序列，但不替换复杂别名（包含空格、超过两个数字或至少 36 字节长的内容，例如 UUID）。这有助于更好地分析复杂查询日志。
语法
参数
x— 字符序列。字符串。
返回值
- 带占位符的字符序列。字符串。
示例
查询：
结果：
normalizedQueryHash
返回相似查询的文字值无值的相同 64 位哈希值。可以帮助分析查询日志。
语法
参数
x— 字符序列。字符串。
返回值
- 哈希值。UInt64。
示例
查询：
结果：
normalizedQueryHashKeepNames
与 normalizedQueryHash 相似，它返回相似查询的文字值无值的相同 64 位哈希值，但在哈希之前不将复杂别名（包含空格、超过两个数字或至少 36 字节长的内容，例如 UUID）替换为占位符。这有助于分析查询日志。
语法
参数
x— 字符序列。字符串。
返回值
- 哈希值。UInt64。
示例
结果：
neighbor
窗口函数，提供对指定偏移量前后行的访问。
语法
函数的结果取决于受影响数据块和数据在块中的顺序。
仅返回当前处理数据块内的相邻值。 由于这种易出错的行为，该函数已被弃用，请使用适当的窗口函数。
在计算 neighbor() 时，行的顺序可能会与用户返回的行的顺序不同。
为防止这种情况，可以创建一个带有 ORDER BY 的子查询，并从子查询外部调用该函数。
参数
column— 列名称或标量表达式。offset— 在column中查找当前行之前或之后的行数。Int64。default_value— 可选。如果偏移量超出块边界，则返回该值。受影响的数据块的类型。
返回值
- 当前行偏移量为
offset的column值，如果offset不在块边界之外。 column的默认值或default_value（如果提供），如果offset超出块边界。
返回类型将是受影响的数据块的类型或默认值类型。
示例
查询：
结果：
查询：
结果：
此函数可用于计算年比年指标值：
查询：
结果：
runningDifference
计算数据块中两个连续行值之间的差异。 对于第一行返回 0，对于后续行，返回与前一行的差异。
仅返回当前处理数据块内的差异。 由于这种易出错的行为，该函数已被弃用，请使用适当的窗口函数。
函数的结果取决于受影响数据块和数据在块中的顺序。
在计算 runningDifference() 时，行的顺序可能会与用户返回的行的顺序不同。
为防止这种情况，可以创建一个带有 ORDER BY 的子查询，并从子查询外部调用该函数。
语法
示例
查询：
结果：
请注意，块大小会影响结果。runningDifference 的内部状态在每个新块处重置。
查询：
结果：
查询：
结果：
runningDifferenceStartingWithFirstValue
该函数已被弃用（请参见 runningDifference 的说明）。
与 runningDifference 相同，但将第一行的值作为第一行的值返回。
runningConcurrency
计算并发事件的数量。 每个事件都有开始时间和结束时间。开始时间包含在事件中，而结束时间不包含。带有开始时间和结束时间的列必须具有相同的数据类型。 该函数计算每个事件开始时间的活动（并发）事件总数。
事件必须按升序排列的开始时间。如果违反此要求，函数将引发异常。每个数据块单独处理。如果来自不同数据块的事件重叠，则不能正确处理它们。
语法
参数
start— 事件的开始时间列。日期、日期时间或 DateTime64。end— 事件的结束时间列。日期、日期时间或 DateTime64。
返回值
- 每个事件开始时间的并发事件数量。UInt32
示例
考虑表：
查询：
结果：
MACNumToString
将 UInt64 数字解释为大端格式的 MAC 地址。以字符串形式返回相应的 MAC 地址，格式为 AA:BB:CC:DD:EE:FF（十六进制形式的冒号分隔数字）。
语法
MACStringToNum
MACNumToString 的逆函数。如果 MAC 地址格式无效，则返回 0。
语法
MACStringToOUI
给定格式为 AA:BB:CC:DD:EE:FF（十六进制形式的冒号分隔数字）的 MAC 地址，返回前三个八位字节作为 UInt64 数字。如果 MAC 地址格式无效，则返回 0。
语法
getSizeOfEnumType
返回 Enum 中字段的数量。
如果类型不是 Enum，则会抛出异常。
语法
参数：
value— 类型为Enum的值。
返回值
- 具有
Enum输入值的字段数量。
示例
blockSerializedSize
返回未考虑压缩的磁盘大小。
参数
value— 任意值。
返回值
- 在没有压缩的情况下，将为值块写入磁盘的字节数。
示例
查询：
结果：
toColumnTypeName
返回代表该值的数据类型的内部名称。
语法
参数：
value— 任意类型的值。
返回值
- 用于表示
value的内部数据类型名称。
示例
toTypeName 与 toColumnTypeName 之间的区别：
结果：
查询：
结果：
示例表明，DateTime 数据类型在内部存储为 Const(UInt32)。
dumpColumnStructure
输出 RAM 中数据结构的详细描述
参数：
value— 任意类型的值。
返回值
- 描述用于表示
value的列结构。
示例
defaultValueOfArgumentType
返回给定数据类型的默认值。
不包括用户设置的自定义列的默认值。
语法
参数：
expression— 任意类型的值或结果为任意类型的表达式。
返回值
- 数字的默认值为
0。 - 字符串的默认值为空字符串。
ᴺᵁᴸᴸ表示 Nullable。
示例
查询：
结果：
查询：
结果：
defaultValueOfTypeName
返回给定类型名称的默认值。
不包括用户设置的自定义列的默认值。
参数：
type— 表示类型名称的字符串。
返回值
- 数字的默认值为
0。 - 字符串的默认值为空字符串。
ᴺᵁᴸᴸ表示 Nullable。
示例
查询：
结果：
查询：
结果：
indexHint
此函数用于调试和自省。它忽略其参数并始终返回 1。参数不被评估。
但在索引分析期间，该函数的参数假定没有被 indexHint 包装。这允许通过相应的条件选择索引范围内的数据，但不需对该条件进一步过滤。在 ClickHouse 中，索引是稀疏的，使用 indexHint 将产生比直接指定相同条件更多的数据。
语法
返回值
1。 Uint8。
示例
以下是来自表 ontime 的测试数据示例。
表：
表在字段 (FlightDate, (Year, FlightDate)) 上有索引。
创建一个不使用索引的查询：
ClickHouse 处理了整个表 (处理了 428 万行)。
结果：
为了应用索引，选择特定日期：
ClickHouse 现在使用索引处理数量显著较少的行 (处理了 32740 行)。
结果：
现在将表达式 k = '2017-09-15' 包装在 indexHint 函数中：
查询：
ClickHouse 以与之前相同的方式使用索引 (处理了 32740 行)。
生成结果时未使用表达式 k = '2017-09-15'。
在示例中，indexHint 函数允许查看相邻日期。
结果：
replicate
创建一个包含单个值的数组。
此函数用于 arrayJoin 的内部实现。
语法
参数
x— 用于填充结果数组的值。arr— 数组。 Array。
返回值
一个与 arr 大小相同的数组，填充值 x。 Array。
示例
查询：
结果：
revision
返回当前 ClickHouse 服务器版本。
语法
返回值
- 当前 ClickHouse 服务器版本。 UInt32。
示例
查询：
结果：
filesystemAvailable
返回托管数据库持久性的文件系统中的可用空间量。返回的值总是小于总的可用空间量 (filesystemUnreserved)，因为某些空间是为操作系统保留的。
语法
返回值
- 以字节为单位的剩余可用空间量。 UInt64。
示例
查询：
结果：
filesystemUnreserved
返回托管数据库持久性的文件系统上的总可用空间量。 (之前称为 filesystemFree )。 另见 filesystemAvailable。
语法
返回值
- 以字节为单位的可用空间总量。 UInt64。
示例
查询：
结果：
filesystemCapacity
返回文件系统的容量（以字节为单位）。需要配置 path 指向数据目录。
语法
返回值
- 文件系统的容量（以字节为单位）。 UInt64。
示例
查询：
结果：
initializeAggregation
根据单个值计算聚合函数的结果。此函数可用于初始化带组合器的聚合函数 -State。您可以创建聚合函数的状态并将其插入到类型为 AggregateFunction 的列中，或使用初始化的聚合作为默认值。
语法
参数
aggregate_function— 要初始化的聚合函数的名称。 String。arg— 聚合函数的参数。
返回值
- 传递给函数的每一行的聚合结果。
返回类型与 initializeAggregation 作为第一个参数所接受的函数的返回类型相同。
示例
查询：
结果：
查询：
结果：
在使用 AggregatingMergeTree 表引擎和 AggregateFunction 列的示例：
另见
finalizeAggregation
给定聚合函数的状态，此函数返回聚合的结果（或在使用 -State 组合器时的最终状态）。
语法
参数
state— 聚合状态。 AggregateFunction。
返回值
- 被聚合的值/值。
返回类型与任何被聚合的类型的类型相同。
示例
查询：
结果：
查询：
结果：
请注意，NULL 值被忽略。
查询：
结果：
组合示例：
查询：
结果：
另见
runningAccumulate
在每个数据块的行上累积聚合函数的状态。
每个新数据块都会重置状态。 由于这种错误易发的行为，此函数已被弃用，请使用适当的窗口函数。
语法
参数
agg_state— 聚合函数的状态。 AggregateFunction。grouping— 分组键。可选。如果更改grouping值，则会重置函数的状态。它可以是任何支持数据类型的类型 index.md 的类型，对于这些类型定义了相等运算符。
返回值
- 每个结果行包含用于所有输入行的聚合函数结果，累积到当前的行位置为止。
runningAccumulate在每个新数据块或grouping值更改时重置状态。
类型依赖于使用的聚合函数。
示例
考虑如何使用 runningAccumulate 计算不分组和分组的数字的累积和。
查询：
结果：
子查询为从 0 到 9 的每个数字生成 sumState。 sumState 返回包含单个数字和（../../sql-reference/aggregate-functions/reference/sum.md）函数的状态。
整个查询执行以下操作：
- 对于第一行，
runningAccumulate取sumState(0)并返回0。 - 对于第二行，函数合并
sumState(0)和sumState(1)，结果为sumState(0 + 1)，并返回1作为结果。 - 对于第三行，函数合并
sumState(0 + 1)和sumState(2)，结果为sumState(0 + 1 + 2)，并返回3作为结果。 - 这些操作重复进行，直到块结束。
下一个示例显示 groupping 参数的用法：
查询：
结果：
如您所见，runningAccumulate 会分别合并每组行的状态。
joinGet
该函数允许您从表中提取数据，方式与从 dictionary 相同。 使用指定的连接键从 Join 表中获取数据。
仅支持使用 ENGINE = Join(ANY, LEFT, <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 操作。
示例
输入表：
查询：
结果：
在表创建时可以使用设置 join_use_nulls 来更改键不存在时返回的行为。
查询：
结果：
joinGetOrNull
类似于 joinGet 但在缺少键时返回 NULL，而不是返回默认值。
语法
参数
join_storage_table_name— 指定搜索位置的 标识符。value_column— 包含所需数据的表的列名。join_keys— 键的列表。
该标识符在默认数据库中进行搜索（请参阅配置文件中的设置 default_database）。要覆盖默认数据库，请使用 USE db_name 或通过分隔符 db_name.db_table 指定数据库和表，如示例所示。
返回值
- 返回与键列表对应的值列表。
如果某个键在源表中不存在，则将为该键返回 NULL。
示例
输入表：
查询：
结果：
catboostEvaluate
此函数在 ClickHouse Cloud 中不可用。
评估外部 catboost 模型。 CatBoost 是由 Yandex 开发的开源梯度提升库，用于机器学习。 接受 catboost 模型的路径和模型参数（特征）。返回 Float64。
语法
示例
前提条件
- 构建 catboost 评估库
在评估 catboost 模型之前，必须提供 libcatboostmodel.<so|dylib> 库。有关如何进行编译，请参阅 CatBoost 文档。
接下来，在 ClickHouse 配置中指定路径到 libcatboostmodel.<so|dylib>：
出于安全和隔离原因，模型评估不会在服务器进程中运行，而是在 clickhouse-library-bridge 进程中运行。
在第一次执行 catboostEvaluate() 时，服务器会启动库桥接进程（如果尚未运行）。这两个进程通过 HTTP 接口进行通信。默认情况下，端口 9012 被使用。如果端口 9012 已被分配给其他服务，可以按以下方式指定其他端口 - 这在端口 9012 已分配给其他服务的情况下非常有用。
- 使用 libcatboost 训练 catboost 模型
请参阅 Training and applying models 以了解如何根据训练数据集训练 catboost 模型。
throwIf
如果参数 x 为真，则抛出异常。
语法
参数
x- 要检查的条件。message- 提供自定义错误消息的常量字符串。可选。error_code- 提供自定义错误代码的常量整数。可选。
要使用 error_code 参数，必须启用配置参数 allow_custom_error_code_in_throwif。
示例
结果：
identity
返回其参数。用于调试和测试。允许取消使用索引，并获取全表扫描的查询性能。当查询在闭合索引时进行可能的分析时，分析器会忽略 identity 函数中的所有内容。也禁用了常量折叠。
语法
示例
查询：
结果：
getSetting
返回当前 自定义设置 的值。
语法
参数
custom_setting— 设置名称。 String。
返回值
- 设置的当前值。
示例
查询：
结果：
另见
getSettingOrDefault
返回当前 自定义设置 的值，或者如果当前配置未设置自定义设置，则返回第二个参数中指定的默认值。
语法
参数
custom_setting— 设置名称。 String。default_value— 如果未设置 custom_setting，则返回的值。值可以是任何数据类型或 Null。
返回值
- 设置的当前值或设置未设置时的 default_value。
示例
查询：
结果：
另见
isDecimalOverflow
检查 Decimal 值是否超出其精度或超出指定精度。
语法
参数
返回值
1— Decimal 值的位数超出了其精度允许的范围，0— Decimal 值满足指定的精度。
示例
查询：
结果：
countDigits
返回表示值所需的小数位数。
语法
参数
返回值
- 位数。 UInt8。
对于 Decimal 值，考虑它们的规模：计算结果是在基础整数类型上 (value * scale)。 例如： countDigits(42) = 2， countDigits(42.000) = 5， countDigits(0.04200) = 4。也就是说，您可以通过 countDecimal(x) > 18 检查 Decimal64 类型的超出精度。
示例
查询：
结果：
errorCodeToName
- 错误代码的文本名称。 LowCardinality(String)。
语法
结果：
tcpPort
返回此服务器监听的 native interface TCP 端口号。 如果在分布式表的上下文中执行，则此函数生成一个包含与每个分片相关的值的普通列。否则，它产生一个常量值。
语法
参数
- 无。
返回值
- TCP 端口号。 UInt16。
示例
查询：
结果：
另见
currentProfiles
返回当前用户的当前 设置配置文件 列表。
命令 SET PROFILE 可用于更改当前配置文件。如果没有使用命令 SET PROFILE，则函数将返回在当前用户定义中指定的配置文件（请参阅 CREATE USER）。
语法
返回值
enabledProfiles
返回显式和隐式分配给当前用户的设置配置文件。显式分配的配置文件与 currentProfiles 函数返回的相同。隐式分配的配置文件包括其他分配配置文件的父配置文件、通过授予角色分配的配置文件、通过自身设置分配的配置文件以及主默认配置文件（请参阅主服务器配置文件中的 default_profile 部分）。
语法
返回值
defaultProfiles
返回在当前用户定义中指定的所有配置文件（请参阅 CREATE USER 语句）。
语法
返回值
currentRoles
返回分配给当前用户的角色。角色可以通过 SET ROLE 语句进行更改。如果没有使用 SET ROLE 语句，则函数 currentRoles 返回与 defaultRoles 相同的结果。
语法
返回值
enabledRoles
返回当前角色和授予当前角色的角色的名称。
语法
返回值
defaultRoles
返回当前用户登录时默认启用的角色。这些角色最初是授予当前用户的所有角色（请参阅 GRANT），但可以通过 SET DEFAULT ROLE 语句进行更改。
语法
返回值
getServerPort
返回服务器端口号。当端口未被服务器使用时，抛出异常。
语法
参数
-
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。
示例
查询：
结果：
queryID
返回当前查询的 ID。其他查询参数可以通过 query_id 从 system.query_log 表中提取。
与 initialQueryID 函数相比，queryID 在不同的分片上可能返回不同的结果（请参见示例）。
语法
返回值
- 当前查询的 ID。 String
示例
查询：
结果：
initialQueryID
返回初始当前查询的 ID。其他查询参数可以通过 initial_query_id 从 system.query_log 表中提取。
与 queryID 函数相比，initialQueryID 在不同的分片上返回相同的结果（请参见示例）。
语法
返回值
- 初始当前查询的 ID。 String
示例
查询：
结果：
initialQueryStartTime
返回初始当前查询的开始时间。
initialQueryStartTime 在不同分片上返回相同的结果（请参见示例）。
语法
返回值
- 初始当前查询的开始时间。 DateTime
示例
查询：
结果：
partitionID
计算 partition ID。
此函数较慢，不应对大量行调用。
语法
参数
x— 返回其分区 ID 的列。y, ...— 返回其分区 ID 的剩余 N 列（可选）。
返回值
- 行所属的分区 ID。 String。
示例
查询：
结果：
shardNum
返回在分布式查询中处理部分数据的分片索引。索引从 1 开始。
如果查询未分布，则返回常量值 0。
语法
返回值
- 分片索引或常量
0。 UInt32。
示例
在以下示例中，使用两个分片的配置。查询在每个分片的 system.one 表上执行。
查询：
结果：
另见
shardCount
返回分布式查询的总分片数。
如果查询未分布，则返回常量值 0。
语法
返回值
- 总分片数或
0。 UInt32。
另见
- shardNum() 函数示例也包含了
shardCount()函数调用。
getOSKernelVersion
返回当前操作系统内核版本的字符串。
语法
参数
- 无。
返回值
- 当前操作系统内核版本。 String。
示例
查询：
结果：
zookeeperSessionUptime
返回当前 ZooKeeper 会话的正常运行时间（以秒为单位）。
语法
参数
- 无。
返回值
- 当前 ZooKeeper 会话的正常运行时间（以秒为单位）。 UInt32。
示例
查询：
结果：
generateRandomStructure
生成随机的表结构，格式为 column1_name column1_type, column2_name column2_type, ...。
语法
参数
number_of_columns— 结果表结构中所需的列数。如果设置为 0 或Null，则列数将在 1 到 128 之间随机选择。默认值：Null。seed- 用于生成稳定结果的随机种子。如果未指定种子或设置为Null，则会随机生成。
所有参数必须是常量。
返回值
- 随机生成的表结构。 String。
示例
查询：
结果：
查询：
结果：
查询：
结果：
注意：复杂类型（Array、Tuple、Map、Nested）的最大嵌套深度限制为 16。
此函数可以与 generateRandom 一起使用以生成完全随机的表格。
structureToCapnProtoSchema
将 ClickHouse 表结构转换为 CapnProto 架构。
语法
参数
structure— 表结构，格式为column1_name column1_type, column2_name column2_type, ...。root_struct_name— CapnProto 架构中根结构的名称。默认值 -Message;
返回值
- CapnProto 架构。 String。
示例
查询：
结果：
查询：
结果：
查询：
结果：
structureToProtobufSchema
将 ClickHouse 表结构转换为 Protobuf 架构。
语法
参数
structure— 表结构，格式为column1_name column1_type, column2_name column2_type, ...。root_message_name— Protobuf 架构中根消息的名称。默认值 -Message;
返回值
- Protobuf 架构。 String。
示例
查询：
结果：
查询：
结果：
查询：
结果：
formatQuery
返回给定 SQL 查询的格式化版本，可能是多行。
如果查询格式不正确，则会抛出异常。要返回 NULL，可以使用函数 formatQueryOrNull()。
语法
参数
query- 要格式化的 SQL 查询。 String
返回值
- 格式化的查询。 String。
示例
查询：
结果：
formatQuerySingleLine
像 formatQuery() 但返回的格式化字符串不包含换行符。
如果查询格式不正确，则抛出异常。要返回 NULL，可以使用函数 formatQuerySingleLineOrNull()。
语法
参数
query- 要格式化的 SQL 查询。 String
返回值
- 格式化后的查询。 String。
示例
结果：
variantElement
从 Variant 列中提取指定类型的列。
语法
参数
variant— Variant 列。 Variant。type_name— 要提取的变体类型的名称。 String。default_value- 如果变体中没有指定类型的变体，则使用的默认值。可以是任何类型。可选。
返回值
- 指定类型的
Variant列的子列。
示例
variantType
返回 Variant 列的每行的变体类型名称。如果行包含 NULL，则返回 'None'。
语法
参数
variant— Variant 列。 Variant。
返回值
- 带有每行变体类型名称的 Enum8 列。
示例
minSampleSizeConversion
计算 A/B 测试中比较两个样本的转化所需的最小样本量。
语法
使用 这篇文章 中描述的公式。假设处理组和对照组的大小相等。返回一个组所需的样本量（即整个实验所需的样本量是返回值的两倍）。
参数
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 测试所需的样本量：
结果：
minSampleSizeContinuous
计算 A/B 测试中比较两个样本的连续指标均值所需的最小样本量。
语法
别名：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 测试所需的样本量：
结果：
connectionId
检索提交当前查询的客户端的连接 ID，并以 UInt64 整数形式返回。
语法
别名： connection_id。
参数
无。
返回值
当前连接 ID。 UInt64。
实现细节
该函数在调试场景或 MySQL 处理程序内部目的中最为有用。它是为了与 MySQL 的 CONNECTION_ID 函数 兼容而创建的。它通常不用于生产查询。
示例
查询：
getClientHTTPHeader
获取 HTTP 头的值。
如果没有此类头，或者当前请求不是通过 HTTP 接口执行的，则该函数返回空字符串。
某些 HTTP 头（例如 Authentication 和 X-ClickHouse-*）是受限的。
该函数要求启用设置 allow_get_client_http_header。
出于安全原因，默认情况下不启用该设置，因为某些头，例如 Cookie，可能包含敏感信息。
HTTP 头对该函数是区分大小写的。
如果在分布式查询的上下文中使用该函数，它仅在发起节点上返回非空结果。
showCertificate
显示关于当前服务器的安全套接字层（SSL）证书的信息，如果已配置。有关如何配置 ClickHouse 使用 OpenSSL 证书验证连接的更多信息，请参见 配置 SSL-TLS。
语法
返回值
示例
查询：
结果：
lowCardinalityIndices
返回 LowCardinality 列中值在字典中的位置。位置从 1 开始。由于 LowCardinality 列按部分具有不同的字典，因此该函数可能会在不同的部分为同一值返回不同的位置。
语法
参数
col— 低基数列。 LowCardinality。
返回值
- 当前部分字典中值的位置。 UInt64。
示例
查询：
结果：
lowCardinalityKeys
返回 LowCardinality 列的字典值。如果块的大小小于或大于字典大小，则结果将被截断或使用默认值扩展。由于 LowCardinality 列按部分具有不同的字典，因此该函数可能会在不同的部分返回不同的字典值。
语法
参数
col— 低基数列。 LowCardinality。
返回值
- 字典键。 UInt64。
示例
查询：
结果：
displayName
返回 config 中的 display_name 值，如果未设置，则返回服务器的完全合格域名 (FQDN)。
语法
返回值
- 从 config 中的
display_name的值，如果未设置，则返回服务器的 FQDN。 String。
示例
可以在 config.xml 中设置 display_name。例如，用 display_name 配置为 'production' 的服务器：
查询：
结果：
transactionID
返回 transaction 的 ID。
语法
返回值
-
返回一个元组，包含
start_csn、local_tid和host_id。 Tuple。 -
start_csn：全局顺序号，该事务开始时看到的最新提交时间戳。 UInt64。 -
local_tid：在特定 start_csn 之内，该主机启动的每个事务唯一的本地顺序号。 UInt64。 -
host_id：启动此事务的主机的 UUID。 UUID。
示例
查询：
结果：
transactionLatestSnapshot
返回可供读取的 transaction 的最新快照（提交序列号）。
语法
返回值
- 返回一个事务的最新快照（CSN）。 UInt64
示例
查询：
结果：
transactionOldestSnapshot
返回可见的某些运行中的 transaction 的最旧快照（提交序列号）。
语法
返回值
- 返回一个事务的最旧快照（CSN）。 UInt64
示例
查询：
结果：
getSubcolumn
获取一个表表达式或标识符和一个常量字符串（包含子列的名称），并返回从表达式中提取的请求子列。
语法
参数
col_name— 表表达式或标识符。 Expression, Identifier。subcol_name— 子列的名称。 String。
返回值
- 返回提取的子列。
示例
查询：
结果：
getTypeSerializationStreams
枚举数据类型的流路径。
该函数供开发人员使用。
语法
参数
col— 列或数据类型的字符串表示形式，数据类型将从中检测。
返回值
示例
查询：
结果：
查询：
结果：
globalVariable
接受一个常量字符串参数，返回具有该名称的全局变量的值。此函数旨在与 MySQL 兼容，并不需要或对 ClickHouse 的正常运行有用。仅定义了少数虚拟全局变量。
语法
参数
name— 全局变量名称。 String。
返回值
- 返回变量
name的值。
示例
查询：
结果：
getMaxTableNameLengthForDatabase
返回指定数据库中表名的最大长度。
语法
参数
database_name— 指定数据库的名称。 String。
返回值
- 返回最大表名的长度。
示例
查询：
结果：
getServerSetting
返回当前一个服务器设置的值。
语法
参数
server_setting— 设置名称。 String。
返回值
- 服务器设置的当前值。
示例
结果：
getMergeTreeSetting
返回当前一个合并树设置的值。
语法
参数
merge_tree_setting— 设置名称。 String。
返回值
- 合并树设置的当前值。
示例
结果：
