其他函数
hostName
返回执行此函数的主机名。如果函数在远程服务器上执行（分布式处理），则返回远程服务器的名称。 如果函数在分布式表的上下文中执行，则生成一个普通列，其中包含与每个分片相关的值。否则，它将产生一个常量值。
语法
返回值
- 主机名。String。
getMacro
从服务器配置的 macros 部分返回命名值。
语法
参数
name— 要从<macros>部分检索的宏名称。String。
返回值
- 指定宏的值。String。
示例
服务器配置文件中的 <macros> 部分示例：
查询：
结果：
可以如下检索相同的值：
fqdn
返回 ClickHouse 服务器的完全限定域名。
语法
别名：fullHostName, FQDN。
返回值
- 包含完全限定域名的字符串。String。
示例
结果：
basename
提取字符串中最后一个斜杠或反斜杠后的部分。此函数通常用于从路径中提取文件名。
参数
expr— String 类型的值。反斜杠需转义。
返回值
包含以下内容的字符串：
- 输入字符串最后一个斜杠或反斜杠后的部分。如果输入字符串以斜杠或反斜杠结尾（例如
/或c:\），该函数将返回空字符串。 - 如果没有斜杠或反斜杠，则返回原始字符串。
示例
查询：
结果：
查询：
结果：
查询：
结果：
visibleWidth
计算以文本格式（制表符分隔）输出值时的大致宽度。 此函数由系统用于实现 Pretty formats。
NULL 在 Pretty 格式中表示为对应于 NULL 的字符串。
语法
示例
查询：
结果：
toTypeName
返回传递参数的类型名称。
如果传递 NULL，函数将返回类型 Nullable(Nothing)，对应 ClickHouse 内部的 NULL 表示。
语法
参数
value— 任意类型的值。
返回值
- 输入值的数据类型名称。String。
示例
查询：
结果：
blockSize
在 ClickHouse 中，查询在 块（数据块）中处理。 该函数返回调用函数的块的大小（行数）。
语法
示例
查询：
结果：
byteSize
返回其参数在内存中的未压缩字节大小的估计。
语法
参数
argument— 值。
返回值
- 参数在内存中字节大小的估计。UInt64。
示例
对于 String 参数，该函数返回字符串长度 + 9（结束零 + 长度）。
查询：
结果：
查询：
结果：
如果函数有多个参数，函数将累积它们的字节大小。
查询：
结果：
materialize
将常量转换为包含单个值的完整列。 在内存中，完整列和常量的表示方式不同。 函数通常会为正常和常量参数执行不同的代码，尽管结果通常应该相同。 此函数可用于调试此行为。
语法
参数
x— 常量。Constant。
返回值
- 包含单个值
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 查询的表引擎参数中很有用，您需要指定数据库。
语法
返回值
- 返回当前数据库名称。String。
示例
查询：
结果：
currentUser
返回当前用户的名称。在分布式查询的情况下，返回发起查询的用户的名称。
语法
别名：user(), USER(), current_user()。别名不区分大小写。
返回值
示例
结果：
currentSchemas
返回当前数据库模式名称的单元素数组。
语法
别名：current_schemas。
参数
bool: 布尔值。Bool。
布尔参数被忽略。它仅存在于兼容性考虑，与 PostgreSQL 中该函数的 实现 保持一致。
返回值
- 返回当前数据库名称的单元素数组。
示例
结果：
isConstant
返回参数是否为常量表达式。
常量表达式是查询分析过程中结果已知的表达式，即执行之前已知。例如，字面量的表达式是常量表达式。
此函数主要用于开发、调试和演示。
语法
参数
x— 要检查的表达式。
返回值
示例
查询：
结果：
查询：
结果：
查询：
结果：
hasColumnInTable
给定数据库名、表名和列名作为常量字符串，如果给定的列存在则返回 1，否则返回 0。
语法
参数
database: 数据库的名称。String literaltable: 表的名称。String literalcolumn: 列的名称。String literalhostname: 进行检查的远程服务器名称。String literalusername: 远程服务器的用户名。String literalpassword: 远程服务器的密码。String literal
返回值
- 如果给定的列存在，则返回
1。 - 否则返回
0。
实现细节
对于嵌套数据结构中的元素，函数检查列的存在性。对于嵌套数据结构本身，函数返回 0。
示例
查询：
hasThreadFuzzer
返回 Thread Fuzzer 是否有效。可用于测试以防止运行时间过长。
语法
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 或十进制字节单位的可读大小 (String)。
返回值
- 字节数，四舍五入到最近整数 (UInt64)。
示例
parseReadableSizeOrNull
给定一个包含字节大小的字符串和单位 B，KiB，KB，MiB，MB 等（即 ISO/IEC 80000-13 或十进制字节单位），此函数返回对应的字节数。
如果函数无法解析输入值，则返回 NULL。
此函数的反向操作是 formatReadableSize 和 formatReadableDecimalSize。
语法
参数
x: 含有 ISO/IEC 80000-13 或十进制字节单位的可读大小 (String)。
返回值
- 字节数，四舍五入到最近整数，或无法解析输入时返回
NULL（Nullable(UInt64)）。
示例
parseReadableSizeOrZero
给定一个包含字节大小的字符串和单位 B，KiB，KB，MiB，MB 等（即 ISO/IEC 80000-13 或十进制字节单位），此函数返回对应的字节数。如果函数无法解析输入值，则返回 0。
此函数的反向操作是 formatReadableSize 和 formatReadableDecimalSize。
语法
参数
x: 含有 ISO/IEC 80000-13 或十进制字节单位的可读大小 (String)。
返回值
- 字节数，四舍五入到最近整数，或无法解析输入时返回 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 的版本。 String。
实现细节
无。
示例
查询：
结果：
buildId
返回由编译器生成的运行 ClickHouse 服务器二进制文件的构建 ID。 如果在分布式表的上下文中执行，此函数会生成一个正常的列，其值与每个分片相关。否则它会生成一个常量值。
语法
blockNumber
返回包含该行的 块 的单调递增的序列号。 返回的块编号以最佳努力原则更新，即可能不完全准确。
语法
返回值
- 行所在数据块的序列号。 UInt64。
示例
查询：
结果：
rowNumberInBlock
对于每个被 rowNumberInBlock 处理的 块，返回当前行的编号。
返回的编号在每个块中从 0 开始。
语法
返回值
- 从 0 开始的数据块中的行序号。 UInt64。
示例
查询：
结果：
rowNumberInAllBlocks
返回 rowNumberInAllBlocks 处理的每一行的唯一行号。返回的编号从 0 开始。
语法
返回值
- 从 0 开始的数据块中的行序号。 UInt64。
示例
查询：
结果：
normalizeQuery
将字面量、字面量序列和复杂别名（包含空格、超过两个数字或至少 36 字节长，例如 UUID）替换为占位符 ?。
语法
参数
x— 字符序列。 String。
返回值
- 替换了占位符的字符序列。 String。
示例
查询：
结果：
normalizeQueryKeepNames
替换字面量、字面量序列为占位符 ?，但不替换复杂别名（包含空格、超过两个数字或至少 36 字节长，如 UUID）。这有助于更好地分析复杂查询日志。
语法
参数
x— 字符序列。 String。
返回值
- 替换了占位符的字符序列。 String。
示例
查询：
结果：
normalizedQueryHash
返回没有字面量值的相似查询的相同 64 位哈希值。对分析查询日志会有所帮助。
语法
参数
x— 字符序列。 String。
返回值
- 哈希值。 UInt64。
示例
查询：
结果：
normalizedQueryHashKeepNames
与 normalizedQueryHash 一样，它返回没有字面量值的相似查询的相同 64 位哈希值，但它不在哈希之前将复杂别名（包含空格、超过两个数字或至少 36 字节长，如 UUID）替换为占位符。对分析查询日志会有所帮助。
语法
参数
x— 字符序列。 String。
返回值
- 哈希值。 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— 事件的开始时间的列。 Date、 DateTime 或 DateTime64。end— 事件的结束时间的列。 Date、 DateTime 或 DateTime64。
返回值
- 在每个事件开始时间时的并发事件数。 UInt32
示例
考虑以下表：
查询：
结果：
MACNumToString
将 UInt64 数字解释为大端格式的 MAC 地址。以格式 AA:BB:CC:DD:EE:FF（以十六进制形式表示的冒号分隔数字）返回相应的 MAC 地址，作为字符串。
语法
MACStringToNum
函数 MACNumToString 的反向函数。如果 MAC 地址格式无效，则返回 0。
语法
MACStringToOUI
给定格式为 AA:BB:CC:DD:EE:FF（以十六进制形式表示的冒号分隔数字）的 MAC 地址，返回前三个八位字节作为 UInt64 数字。如果 MAC 地址格式无效，则返回 0。
语法
getSizeOfEnumType
返回 枚举 中的字段数量。
如果类型不是 枚举，则抛出异常。
语法
参数：
value— 类型Enum的值。
返回值
- 带有
Enum输入值的字段数量。
示例
blockSerializedSize
返回未考虑压缩时的磁盘大小。
参数
value— 任何值。
返回值
- 将写入磁盘的值块的字节数（未压缩）。
示例
查询：
结果：
toColumnTypeName
返回代表该值的数据类型的内部名称。
语法
参数：
value— 任何类型的值。
返回值
- 用于表示
value的内部数据类型名称。
示例
toTypeName 和 toColumnTypeName 的区别：
结果：
查询：
结果：
该示例显示，DateTime 数据类型内部存储为 Const(UInt32)。
dumpColumnStructure
输出内存中数据结构的详细描述。
参数：
value— 任何类型的值。
返回值
- 描述用于表示
value的列结构。
示例
defaultValueOfArgumentType
返回给定数据类型的默认值。
不包括用户设置的自定义列的默认值。
语法
参数：
expression— 任意类型值或生成任意类型值的表达式。
返回值
- 数字返回
0。 - 字符串返回空字符串。
- Nullable 返回
ᴺᵁᴸᴸ。
示例
查询：
结果：
查询：
结果：
defaultValueOfTypeName
返回给定类型名称的默认值。
不包括用户设置的自定义列的默认值。
参数：
type— 表示类型名称的字符串。
返回值
- 数字返回
0。 - 字符串返回空字符串。
- Nullable 返回
ᴺᵁᴸᴸ。
示例
查询：
结果：
查询：
结果：
indexHint
此函数用于调试和内省。它忽略其参数并始终返回 1。参数不会被评估。
但是在索引分析期间，该函数的参数被假定为不包裹在 indexHint 中。这允许通过相应的条件选择索引范围中的数据，但不对该条件进一步过滤。ClickHouse 中的索引是稀疏的，使用 indexHint 将比直接指定相同条件返回更多数据。
语法
返回值
1。 Uint8。
示例
以下是来自表 ontime 的测试数据示例。
表：
该表在字段 (FlightDate, (Year, FlightDate)) 上具有索引。
创建一个不使用索引的查询：
ClickHouse 处理整个表（Processed 4.28 million rows）。
结果：
要应用索引，选择特定日期：
ClickHouse 现在使用索引处理的行数量大大减少（Processed 32.74 thousand rows）。
结果：
现在将表达式 k = '2017-09-15' 包裹在函数 indexHint 中：
查询：
ClickHouse 以与之前相同的方式使用了索引（Processed 32.74 thousand rows）。
在生成结果时未使用表达式 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 列的示例：
参见
参数
state— 聚合的状态。 AggregateFunction。
返回值
- 聚合值。
返回的类型与任何被聚合的类型相同。
示例
查询：
结果：
查询：
结果：
注意，NULL 值会被忽略。
查询：
结果：
组合示例：
查询：
结果：
另请参阅
runningAccumulate
为数据块的每一行累积聚合函数的状态。
每个新数据块都会重置状态。 由于这种容易出错的行为，此函数已弃用，请改用适当的窗口函数。
语法
参数
agg_state— 聚合函数的状态。 AggregateFunction。grouping— 分组键。选填。如果grouping值更改，则函数的状态会被重置。它可以是任何定义了相等运算符的支持的数据类型。
返回值
- 每个结果行包含聚合函数的结果，累积了所有输入行从0到当前的位置。
runningAccumulate在每个新的数据块中或当grouping值发生变化时重置状态。
类型依赖于使用的聚合函数。
示例
考虑如何使用runningAccumulate在没有分组和有分组的情况下找到数字的累积和。
查询：
结果：
子查询生成从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参数的用法：
查询：
结果：
如您所见，runningAccumulate单独为每组行合并状态。
joinGet
该函数允许您从表中提取数据，方式与从字典中一样。使用指定的连接键从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已分配给其他服务，这将非常有用。
- 使用libcatboost训练catboost模型
有关如何从训练数据集训练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的十进制溢出。这是isDecimalOverflow的慢变体。
示例
查询：
结果：
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
计算分区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。type_name— 要提取的变体类型名称。 String。default_value- 如果变体中没有指定类型的变体时使用的默认值。可以是任何类型。可选。
返回值
- 具有指定类型的
Variant列的子列。
示例
variantType
返回 Variant 列中每行的变体类型名称。如果行包含 NULL，则返回 'None'。
语法
参数
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"— 使用所需样本大小无法检测到的值范围的下限（即，在提供的alpha和power下，所有小于或等于"detect_range_lower"的值都是可检测的）。计算为baseline - mde。 Float64。"detect_range_upper"— 使用所需样本大小无法检测到的值范围的上限（即，在提供的alpha和power下，所有大于或等于"detect_range_upper"的值都是可检测的）。计算为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"— 使用所需样本大小无法检测到的值范围的下限（即，在提供的alpha和power下，所有小于或等于"detect_range_lower"的值都是可检测的）。计算为baseline * (1 - mde)。 Float64。"detect_range_upper"— 使用所需样本大小无法检测到的值范围的上限（即，在提供的alpha和power下，所有大于或等于"detect_range_upper"的值都是可检测的）。计算为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。
示例
display_name 可以在 config.xml 中设置。以配置为 'production' 的服务器为例：
查询:
结果:
transactionID
返回事务的 ID transaction。
语法
返回值
-
返回一个包含
start_csn、local_tid和host_id的元组。 Tuple。 -
start_csn: 全局顺序号，事务开始时看到的最新提交时间戳。 UInt64。 -
local_tid: 本地主键编号，在特定start_csn中对该主机启动的每个事务都是唯一的。 UInt64。 -
host_id: 启动此事务的主机 UUID。 UUID。
示例
查询:
结果:
transactionLatestSnapshot
返回可用于读取的事务的最新快照（提交序列号）。
语法
返回值
- 返回事务的最新快照（CSN）。 UInt64
示例
查询:
结果:
transactionOldestSnapshot
返回对某个正在运行的事务可见的最旧快照（提交序列号）。
语法
返回值
- 返回事务的最旧快照（CSN）。 UInt64
示例
查询:
结果:
getSubcolumn
接受表表达式或标识符以及包含子列名称的常量字符串，并返回从表达式中提取的所请求的子列。
语法
参数
col_name— 表表达式或标识符。 Expression， Identifier。subcol_name— 子列名称。 String。
返回值
- 返回提取的子列。
示例
查询:
结果:
getTypeSerializationStreams
枚举数据类型的流路径。
此函数仅供开发者使用。
语法
参数
col— 列或数据类型的字符串表示，可以检测到数据类型。
返回值
示例
查询:
结果:
查询:
结果:
globalVariable
接受一个常量字符串参数，返回具有该名称的全局变量的值。此函数旨在与 MySQL 兼容，并且对于 ClickHouse 的正常操作不需要或不实用。仅定义了一些虚拟全局变量。
语法
参数
name— 全局变量名称。 String。
返回值
- 返回变量
name的值。
示例
查询:
结果:
getMaxTableNameLengthForDatabase
返回指定数据库中表名的最大长度。
语法
参数
database_name— 指定数据库的名称。 String。
返回值
- 返回最大表名的长度。
示例
查询:
结果: