编码函数

bech32Decode

引入版本：v25.6

对由 bech32 或 bech32m 算法生成的 Bech32 地址字符串进行解码。

注意

与编码函数不同，Bech32Decode 会自动处理带填充的 FixedString。

语法

bech32Decode(address)

参数

address — 要解码的 Bech32 字符串。String 或 FixedString

返回值

返回一个元组 (hrp, data)，其中包含用于编码该字符串的值。data 为二进制格式。Tuple(String, String)

示例

解码地址

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('bc1w508d6qejxtdg4y5r3zarvary0c5xw7kj7gz7z') AS tup)

bc   751E76E8199196D454941C45D1B3A323F1433BD6

测试网地址

SELECT tup.1 AS hrp, hex(tup.2) AS data FROM (SELECT bech32Decode('tb1w508d6qejxtdg4y5r3zarvary0c5xw7kzp034v') AS tup)

tb   751E76E8199196D454941C45D1B3A323F1433BD6

bech32Encode

自 v25.6 起引入

使用 Bech32 或 Bech32m 算法对二进制数据字符串及其人类可读部分（HRP）进行编码。

注意

在使用 FixedString 数据类型时，如果某个值没有完全填满其定义的长度，将会用空字符（null 字符）进行填充。对于 hrp 参数，bech32Encode 函数会自动处理这种情况，但对于 data 参数，值不能包含这些填充字符。因此，不建议对数据值使用 FixedString 数据类型，除非能够确保它们的长度完全相同，并相应地将 FixedString 列的长度设置为该值。

语法

bech32Encode(hrp, data[, witver])

参数

hrp — 一个由 1 - 83 个小写字符组成的字符串，用于指定代码的“human-readable part（人类可读部分）”。通常为 'bc' 或 'tb'。String 或 FixedString
data — 要编码的二进制数据字符串。String 或 FixedString
witver — 可选。见证版本（默认 = 1）。一个 UInt*，用于指定要运行的算法版本。0 对应 Bech32，1 或更大对应 Bech32m。UInt*

返回值

返回一个 Bech32 地址字符串，由 human-readable part、一个始终为 '1' 的分隔符字符，以及数据部分组成。该字符串的长度不会超过 90 个字符。如果算法无法从输入中生成有效地址，则返回空字符串。String

示例

默认 Bech32m

-- 当未提供见证版本时，默认为 1，即更新后的 Bech32m 算法。
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'))

bc1w508d6qejxtdg4y5r3zarvary0c5xw7k8zcwmq

Bech32 算法

-- 见证版本为 0 将生成不同的地址字符串。
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 0)

bc1w508d6qejxtdg4y5r3zarvary0c5xw7kj7gz7z

自定义 HRP

-- 虽然在 SegWit 地址格式中，只有 'bc'（主网）和 'tb'（测试网）是允许的 hrp 值，
-- 但 Bech32 允许使用任何满足上述要求的 hrp。
SELECT bech32Encode('abcdefg', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 10)

abcdefg1w508d6qejxtdg4y5r3zarvary0c5xw7k9rp8r4

bin

引入于：v21.8

根据不同类型，按照以下逻辑返回一个包含参数二进制表示形式的字符串：

Type	Description
`(U)Int*`	以从最高有效位到最低有效位（大端序或“人类可读”顺序）输出二进制位。输出时从最高有效的非零字节开始（省略前导零字节），但如果该字节的最高位为零，仍然为该字节输出完整的 8 位二进制数字。
`Date` and `DateTime`	格式化为对应的整数（`Date` 为自纪元（epoch）起的天数，`DateTime` 为 Unix 时间戳的值）。
`String` and `FixedString`	所有字节都直接编码为 8 位二进制数字。零字节不会被省略。
`Float*` and `Decimal`	按其在内存中的表示进行编码。由于我们使用的是小端序架构，因此按小端序进行编码。前导或尾随的零字节不会被省略。
`UUID`	按大端序顺序编码为字符串。

语法

bin(arg)

参数

arg — 要转换为二进制的值。String 或 FixedString 或 (U)Int* 或 Float* 或 Decimal 或 Date 或 DateTime

返回值

返回参数二进制表示形式的字符串。String

示例

简单的整数

SELECT bin(14)

┌─bin(14)──┐
│ 00001110 │
└──────────┘

Float32 浮点数

SELECT bin(toFloat32(number)) AS bin_presentation FROM numbers(15, 2)

┌─bin_presentation─────────────────┐
│ 00000000000000000111000001000001 │
│ 00000000000000001000000001000001 │
└──────────────────────────────────┘

Float64 浮点数

SELECT bin(toFloat64(number)) AS bin_presentation FROM numbers(15, 2)

┌─bin_presentation─────────────────────────────────────────────────┐
│ 0000000000000000000000000000000000000000000000000010111001000000 │
│ 0000000000000000000000000000000000000000000000000011000001000000 │
└──────────────────────────────────────────────────────────────────┘

UUID 转换

SELECT bin(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0')) AS bin_uuid

┌─bin_uuid─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 01100001111100001100010000000100010111001011001100010001111001111001000001111011101001100000000001101010110100111101101110100000 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

bitPositionsToArray

自 v21.7 引入

该函数返回无符号整数二进制表示中所有值为 1 的位的位置（按升序排列）。带符号的输入整数会先被转换为无符号整数。

语法

bitPositionsToArray(arg)

参数

arg — 一个整数值。(U)Int*

返回值

返回一个数组，数组元素为输入值二进制表示中所有为 1 的位的位置，按升序排列。Array(UInt64)

示例

单个位被设置为 1

SELECT bitPositionsToArray(toInt8(1)) AS bit_positions

┌─bit_positions─┐
│ [0]           │
└───────────────┘

所有比特位已置 1

SELECT bitPositionsToArray(toInt8(-1)) AS bit_positions

┌─bit_positions─────────────┐
│ [0, 1, 2, 3, 4, 5, 6, 7]  │
└───────────────────────────┘

bitmaskToArray

引入版本：v1.1

此函数将一个整数分解为若干个 2 的幂之和。这些 2 的幂以升序排列的数组形式返回。

语法

bitmaskToArray(数字)

参数

num — 一个整数值。(U)Int*

返回值

返回一个数组，其中包含按升序排列的 2 的幂，其和等于输入值。Array(UInt64)

示例

基础示例

SELECT bitmaskToArray(50) AS powers_of_two

┌─powers_of_two───┐
│ [2, 16, 32]     │
└─────────────────┘

单一 2 的幂值

SELECT bitmaskToArray(8) AS powers_of_two

┌─powers_of_two─┐
│ [8]           │
└───────────────┘

bitmaskToList

引入版本：v1.1

类似 bitmaskToArray，但返回的是由 2 的幂值组成、以逗号分隔的字符串。

语法

bitmaskToList(数字)

参数

num — 整数。(U)Int*

返回值

返回一个包含用逗号分隔的 2 的幂的字符串。String

示例

基本示例

SELECT bitmaskToList(50) AS powers_list

┌─powers_list───┐
│ 2, 16, 32     │
└───────────────┘

char

引入版本：v20.1

返回一个长度等于传入参数个数的字符串，其中每个字节的值等于对应参数的值。接受多个数值类型的参数。

如果参数的值超出了 UInt8 数据类型的范围，则会被转换为 UInt8，在此过程中可能发生舍入和溢出。

语法

char(num1[, num2[, ...]])

参数

num1[, num2[, num3 ...]] — 按整数处理的数值参数。(U)Int8/16/32/64 或 Float*

返回值

返回由给定字节组成的字符串。String

示例

基本示例

SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;

┌─hello─┐
│ hello │
└───────┘

构建任意编码

-- 您可以通过传递相应的字节来构造任意编码的字符串。
-- 例如 UTF-8
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;

┌─hello──┐
│ привет │
└────────┘

hex

引入于：v1.1

根据不同类型，按以下逻辑返回一个包含参数十六进制表示形式的字符串：

Type	Description
`(U)Int*`	按从最高有效位到最低有效位的顺序（大端或“人类可读”顺序）输出十六进制数字（“半字节 / nibbles”）。从最高有效的非零字节开始（会省略前导零字节），但始终输出每个字节的两个数字，即使高位数字为零。
`Date` and `DateTime`	格式化为对应的整数（对于 `Date`，是自纪元起的天数；对于 `DateTime`，是 Unix 时间戳的值）。
`String` and `FixedString`	所有字节都直接编码为两个十六进制数字。零字节不会被省略。
`Float*` and `Decimal`	按其在内存中的表示进行编码。ClickHouse 在内部始终以小端格式表示这些值，因此也按小端方式进行编码。前导或尾随的零字节不会被省略。
`UUID`	按大端顺序编码为字符串。

该函数使用大写字母 A-F，且不使用任何前缀（如 0x）或后缀（如 h）。

语法

hex(arg)

参数

arg — 要转换为十六进制的值。String 或 (U)Int* 或 Float* 或 Decimal 或 Date 或 DateTime

返回值

返回一个以十六进制表示该参数的字符串。String

示例

简单整数

SELECT hex(1)

Float32 浮点数

SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2)

┌─hex_presentation─┐
│ 00007041         │
│ 00008041         │
└──────────────────┘

Float64 浮点数

SELECT hex(toFloat64(number)) AS hex_presentation FROM numbers(15, 2)

┌─hex_presentation─┐
│ 0000000000002E40 │
│ 0000000000003040 │
└──────────────────┘

UUID 转换

SELECT lower(hex(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0'))) AS uuid_hex

┌─uuid_hex─────────────────────────┐
│ 61f0c4045cb311e7907ba6006ad3dba0 │
└──────────────────────────────────┘

hilbertDecode

引入版本：v24.6

将 Hilbert 曲线索引解码回由无符号整数组成的元组，表示多维空间中的坐标。

与 hilbertEncode 函数一样，此函数有两种运行模式：

简单
扩展

简单模式

接受最多 2 个无符号整数作为参数，并生成一个 UInt64 代码。

扩展模式

接受一个范围掩码（元组）作为第一个参数，以及最多 2 个无符号整数作为其他参数。掩码中的每个数字用于配置对应参数左移的位数，从而在其范围内对参数进行有效缩放。

当你需要对范围（或基数）差异巨大的参数获得相似分布时，范围扩展会很有用。例如：'IP Address' (0...FFFFFFFF) 和 'Country code' (0...FF)。与编码函数相同，此模式最多支持 8 个数字。

语法

hilbertDecode(tuple_size, code)

参数

tuple_size — 不大于 2 的整数值。UInt8/16/32/64 或 Tuple(UInt8/16/32/64)
code — UInt64 类型的编码值。UInt64

返回值

返回一个指定大小的元组。Tuple(UInt64)

示例

简单模式

SELECT hilbertDecode(2, 31)

["3", "4"]

单一参数

-- 当只有一个参数时，其 Hilbert 编码始终就是该参数本身（作为元组）。
SELECT hilbertDecode(1, 1)

["1"]

展开模式

-- 当以单个参数传入一个指定位移位数的元组时，将按该元组指定的位数进行右移。
SELECT hilbertDecode(tuple(2), 32768)

["128"]

列使用情况

-- 首先创建表并插入数据
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1 SETTINGS index_granularity = 8192, index_granularity_bytes = '10Mi';
insert into hilbert_numbers (*) values(1,2);

-- 使用列名而非常量作为函数参数
SELECT untuple(hilbertDecode(2, hilbertEncode(n1, n2))) FROM hilbert_numbers;

1    2

hilbertEncode

引入版本：v24.6

为一组无符号整数计算 Hilbert 曲线编码。

该函数有两种工作模式：

简单模式
扩展模式

简单模式

接受最多 2 个无符号整数作为参数，并生成一个 UInt64 编码。

扩展模式

接受一个范围掩码（Tuple）作为第一个参数，并将最多 2 个无符号整数作为其余参数。

掩码中的每个数字用于配置对应参数左移的位数，从而在其范围内按比例缩放该参数。

语法

-- 简化模式
hilbertEncode(args)

-- 扩展模式
hilbertEncode(range_mask, args)

参数

args — 至多两个 UInt 值或 UInt 类型的列。UInt8/16/32/64
range_mask — 在扩展模式下，至多两个 UInt 值或 UInt 类型的列。UInt8/16/32/64

返回值

返回一个 UInt64 值。UInt64

示例

简单模式

SELECT hilbertEncode(3, 4)

展开模式

-- 当需要为范围（或基数）差异极大的参数实现相似的分布时，范围扩展会很有用。
-- 例如：'IP 地址'（0...FFFFFFFF）和'国家代码'（0...FF）。
-- 注意：元组大小必须等于其他参数的数量。
SELECT hilbertEncode((10, 6), 1024, 16)

4031541586602

单个参数

-- 当仅传入一个非元组的单个参数时，函数会将该参数本身作为 Hilbert 索引返回，
-- 因为不需要进行维度映射。
SELECT hilbertEncode(1)

展开的单参数形式

-- 如果只提供一个参数，并使用元组指定位移位数，函数会
-- 按指定的位数将该参数左移。
SELECT hilbertEncode(tuple(2), 128)

列用法

-- 首先创建表并插入一些数据
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1;
insert into hilbert_numbers (*) values(1, 2);

-- 使用列名而非常量作为函数参数
SELECT hilbertEncode(n1, n2) FROM hilbert_numbers;

mortonDecode

引入于：v24.6

将 Morton 编码（Z 曲线）解码为对应的无符号整数元组。

与 mortonEncode 函数一样，此函数有两种运行模式：

简单
扩展

简单模式

第一个参数为结果元组的大小，第二个参数为编码值。

扩展模式

第一个参数为范围掩码（元组），第二个参数为编码值。掩码中的每个数字用于配置范围收缩的倍数：

1 - 不收缩
2 - 2 倍收缩
3 - 3 倍收缩 ⋮
最多到 8 倍收缩。

当参数的取值范围（或基数）差异很大，但仍希望它们具有相近的分布时，范围扩展会很有用。例如：“IP Address” (0...FFFFFFFF) 和 “Country code” (0...FF)。与编码函数一样，此功能最多只能处理 8 个数字。

语法

-- 简单模式
mortonDecode(tuple_size, code)

-- 扩展模式
mortonDecode(range_mask, code)

参数

tuple_size — 不大于 8 的整数值。UInt8/16/32/64
range_mask — 在扩展模式下，用于配置每个参数的掩码。该掩码是一个无符号整数的元组。掩码中的每个数值用于配置区间收缩的程度。Tuple(UInt8/16/32/64)
code — UInt64 代码值。UInt64

返回值

返回一个指定大小的元组。Tuple(UInt64)

示例

简单模式

SELECT mortonDecode(3, 53)

["1", "2", "3"]

单个参数

SELECT mortonDecode(1, 1)

["1"]

扩展模式：缩减一个参数

SELECT mortonDecode(tuple(2), 32768)

["128"]

列使用情况

-- 首先创建表并写入一些数据
CREATE TABLE morton_numbers(
    n1 UInt32,
    n2 UInt32,
    n3 UInt16,
    n4 UInt16,
    n5 UInt8,
    n6 UInt8,
    n7 UInt8,
    n8 UInt8
)
ENGINE=MergeTree()
ORDER BY n1;
INSERT INTO morton_numbers (*) values(1, 2, 3, 4, 5, 6, 7, 8);

-- 将列名用作函数参数，而不是使用常量
SELECT untuple(mortonDecode(8, mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8))) FROM morton_numbers;

1 2 3 4 5 6 7 8

mortonEncode

引入于：v24.6

为一组无符号整数计算 Morton 编码（Z 曲线，ZCurve）。

该函数有两种运行模式：

简单模式
扩展模式*

简单模式

最多接受 8 个无符号整数作为参数，并生成一个 UInt64 编码。

扩展模式

接受一个范围掩码（Tuple）作为第一个参数，以及最多 8 个无符号整数作为其余参数。

掩码中的每个数字用于配置对应维度的范围扩展倍数：

1 - 不扩展
2 - 2 倍扩展
3 - 3 倍扩展 ⋮
最多 8 倍扩展。

语法

-- 简化模式
mortonEncode(args)

-- 扩展模式
mortonEncode(range_mask, args)

参数

args — 最多包含 8 个无符号整数或上述类型的列。UInt8/16/32/64
range_mask — 在扩展模式下，用于指定每个参数的掩码。该掩码是由 1 - 8 的无符号整数组成的元组。掩码中的每个数字用于配置区间收缩的程度。Tuple(UInt8/16/32/64)

返回值

返回一个 UInt64 编码值。UInt64

示例

简单模式

SELECT mortonEncode(1, 2, 3)

展开模式

-- 当你需要让取值范围（或基数）差异巨大的参数获得相似分布时，范围扩展会很有帮助
-- 例如：'IP Address' (0...FFFFFFFF) 和 'Country code' (0...FF)。
-- 注意：元组（Tuple）的大小必须等于其他参数的数量。
SELECT mortonEncode((1,2), 1024, 16)

单个参数

-- 单个参数的 Morton 编码始终是参数本身
SELECT mortonEncode(1)

单参数扩展形式

SELECT mortonEncode(tuple(2), 128)

列使用情况

-- 首先创建表并插入一些数据
CREATE TABLE morton_numbers(
    n1 UInt32,
    n2 UInt32,
    n3 UInt16,
    n4 UInt16,
    n5 UInt8,
    n6 UInt8,
    n7 UInt8,
    n8 UInt8
)
ENGINE=MergeTree()
ORDER BY n1;
INSERT INTO morton_numbers (*) values(1, 2, 3, 4, 5, 6, 7, 8);

-- 使用列名而不是常量作为函数参数
SELECT mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8) FROM morton_numbers;

2155374165

sqidDecode

首次引入于：v24.1

将一个 sqid 解码还原为数字数组。

语法

sqidDecode(sqid)

参数

sqid — 要解码的 sqid。String

返回值

返回由 sqid 解码得到的数字数组。Array(UInt64)

示例

使用示例

SELECT sqidDecode('gXHfJ1C6dN');

┌─sqidDecode('gXHfJ1C6dN')─────┐
│ [1, 2, 3, 4, 5]              │
└──────────────────────────────┘

sqidEncode

自 v24.1 起引入

将数字转换为 sqid，一种类似 YouTube 的 ID 字符串。

语法

sqidEncode(n1[, n2, ...])

别名：sqid

参数

n1[, n2, ...] — 任意数量的数字。UInt8/16/32/64

返回值

返回一个哈希 ID 字符串 String

示例

用法示例

SELECT sqidEncode(1, 2, 3, 4, 5);

┌─sqidEncode(1, 2, 3, 4, 5)─┐
│ gXHfJ1C6dN                │
└───────────────────────────┘

unbin

引入于：v21.8

将参数中的每一对二进制数字解释为一个数值，并将其转换为该数值所表示的字节。该函数执行与 bin 相反的操作。

对于数值型参数，unbin() 不会返回 bin() 的逆结果。如果你希望将结果转换为数值，可以使用 reverse 和 reinterpretAs<Type> 函数。

注意

如果在 clickhouse-client 中调用 unbin，二进制字符串将以 UTF-8 方式显示。

支持二进制数字 0 和 1。二进制数字的位数不必是 8 的倍数。如果参数字符串包含二进制数字以外的任何内容，其结果未定义（不会抛出异常）。

语法

unbin(arg)

参数

arg — 一个由任意数量二进制位组成的字符串。String

返回值

返回一个二进制字符串（BLOB）。String

示例

基本用法

SELECT UNBIN('001100000011000100110010'), UNBIN('0100110101111001010100110101000101001100')

┌─unbin('001100000011000100110010')─┬─unbin('0100110101111001010100110101000101001100')─┐
│ 012                               │ MySQL                                             │
└───────────────────────────────────┴───────────────────────────────────────────────────┘

转换为数值

SELECT reinterpretAsUInt64(reverse(unbin('1110'))) AS num

┌─num─┐
│  14 │
└─────┘

unhex

引入版本：v1.1

执行与 hex 相反的操作。它将参数中的每一对十六进制数字解释为一个数值，并将其转换为该数值所表示的字节。返回值是一个二进制字符串（BLOB）。

如果你希望将结果转换为数值，可以使用 reverse 和 reinterpretAs<Type> 函数。

注意

clickhouse-client 将字符串解释为 UTF-8。这可能会导致 hex 返回的值在显示时与预期不符。

同时支持大写和小写字母 A-F。十六进制数字的数量不必为偶数。如果是奇数，最后一个数字会被解释为 00-0F 字节中最低有效的半字节。如果参数字符串包含十六进制数字以外的任何内容，将返回某种依赖实现的结果（不会抛出异常）。对于数值类型参数，unhex() 不会执行 hex(N) 的逆运算。

语法

unhex(arg)

参数

arg — 一个包含任意数量的十六进制数字的字符串。String 或 FixedString

返回值

返回一个二进制字符串（BLOB）。String

示例

基本用法

SELECT unhex('303132'), UNHEX('4D7953514C')

┌─unhex('303132')─┬─unhex('4D7953514C')─┐
│ 012             │ MySQL               │
└─────────────────┴─────────────────────┘

转换为数值

SELECT reinterpretAsUInt64(reverse(unhex('FFF'))) AS num

┌──num─┐
│ 4095 │
└──────┘

bech32Decode​

bech32Encode​

bin​

bitPositionsToArray​

bitmaskToArray​

bitmaskToList​

char​

hex​

hilbertDecode​

hilbertEncode​

mortonDecode​

mortonEncode​

sqidDecode​

sqidEncode​

unbin​

unhex​

bech32Decode

bech32Encode

bin

bitPositionsToArray

bitmaskToArray

bitmaskToList

char

hex

hilbertDecode

hilbertEncode

mortonDecode

mortonEncode

sqidDecode

sqidEncode

unbin

unhex