引入版本：v25.6.0
解码由 bech32 或 bech32m 算法生成的 Bech32 地址字符串。
与编码函数不同，bech32Decode 会自动处理带填充的 FixedStrings。
bech32Decode(address[, 'raw'])
address — 要解码的 Bech32 字符串。String 或 FixedStringmode — 可选。传入 'raw' 可在解码时不将第一个字节剥离为 witness 版本。对于非 SegWit 地址 (例如 Cosmos SDK) ，请使用此选项。String
返回值
返回一个 (hrp, data) Tuple，表示编码该字符串时使用的值。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
使用 FixedString 数据类型时，如果某个值未完全占满其长度，则会用空字符进行填充。
虽然 bech32Encode 函数会自动处理 hrp 参数的这种情况，但对于 data 参数，其值不得被填充。
因此，不建议将 FixedString 数据类型用于你的数据值，除非你能
确定它们的长度都相同，并确保你的 FixedString 列也设置为相同的长度。 bech32Encode(hrp, data[, witver | 'bech32' | 'bech32m'])
hrp — 由 1 - 83 个小写字符组成的 String，用于指定编码中的“可读部分”。通常为 ‘bc’ 或 ‘tb’。String 或 FixedStringdata — 要编码的二进制数据 String。String 或 FixedStringwitver_or_variant — 可选。可以是 UInt* 见证版本 (默认值为 1，Bech32 为 0，Bech32m 为 1+) ，也可以是 String 编码变体：'bech32' (BIP173) 或 'bech32m' (BIP350) 。使用字符串变体时，不会预加见证版本字节——这对于 Cosmos SDK 等非 SegWit 地址是必需的。UInt* 或 String
返回值
返回一个 Bech32 地址字符串，由可读部分、一个始终为 ‘1’ 的分隔符字符以及数据部分组成。该字符串长度不会超过 90 个字符。如果算法无法根据输入生成有效地址，则返回空字符串。String
示例
默认 Bech32m
-- 当未提供见证版本时，默认值为 1，即使用更新后的 Bech32m 算法。
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'))
bc1w508d6qejxtdg4y5r3zarvary0c5xw7k8zcwmq
-- 见证版本为 0 将生成不同的地址字符串。
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 0)
bc1w508d6qejxtdg4y5r3zarvary0c5xw7kj7gz7z
-- 虽然 'bc'（主网）和 'tb'（测试网）是 SegWit 地址格式中唯一允许的 hrp 值，
-- 但 Bech32 允许任何满足上述要求的 hrp。
SELECT bech32Encode('abcdefg', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 10)
abcdefg1w508d6qejxtdg4y5r3zarvary0c5xw7k9rp8r4
-- 使用 'bech32' Variant 对原始数据进行编码，不附加见证版本字节，
-- 兼容 Cosmos SDK、Injective、Osmosis 及其他非 SegWit 链。
SELECT bech32Encode('inj', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 'bech32')
inj1w508d6qejxtdg4y5r3zarvary0c5xw7kgj5aqs
| 类型 | 描述 |
|---|
(U)Int* | 按从最高有效位到最低有效位的顺序 (大端序或“人类可读”顺序) 输出二进制数字。从最高的非零字节开始输出 (省略前导零字节) ，但如果某个字节的最高位为零，仍始终输出该字节完整的八位数字。 |
Date and DateTime | 格式化为对应的整数 (Date 为自纪元以来的天数，DateTime 为 Unix 时间戳值) 。 |
String and FixedString | 所有字节都会直接编码为 8 位二进制数，不会省略零字节。 |
Float* and Decimal | 按它们在内存中的表示进行编码。由于支持小端架构，因此按小端序编码。不会省略前导或尾随零字节。 |
UUID | 按大端序字符串编码。 |
String
示例
简单整数
┌─bin(14)──┐
│ 00001110 │
└──────────┘
SELECT bin(toFloat32(number)) AS bin_presentation FROM numbers(15, 2)
┌─bin_presentation─────────────────┐
│ 00000000000000000111000001000001 │
│ 00000000000000001000000001000001 │
└──────────────────────────────────┘
SELECT bin(toFloat64(number)) AS bin_presentation FROM numbers(15, 2)
┌─bin_presentation─────────────────────────────────────────────────┐
│ 0000000000000000000000000000000000000000000000000010111001000000 │
│ 0000000000000000000000000000000000000000000000000011000001000000 │
└──────────────────────────────────────────────────────────────────┘
SELECT bin(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0')) AS bin_uuid
┌─bin_uuid─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 01100001111100001100010000000100010111001011001100010001111001111001000001111011101001100000000001101010110100111101101110100000 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Array(UInt64)
示例
单个位被设置
SELECT bitPositionsToArray(toInt8(1)) AS bit_positions
┌─bit_positions─┐
│ [0] │
└───────────────┘
SELECT bitPositionsToArray(toInt8(-1)) AS bit_positions
┌─bit_positions─────────────┐
│ [0, 1, 2, 3, 4, 5, 6, 7] │
└───────────────────────────┘
Array(UInt64)
示例
基本示例
SELECT bitmaskToArray(50) AS powers_of_two
┌─powers_of_two───┐
│ [2, 16, 32] │
└─────────────────┘
SELECT bitmaskToArray(8) AS powers_of_two
┌─powers_of_two─┐
│ [8] │
└───────────────┘
String
示例
基本示例
SELECT bitmaskToList(50) AS powers_list
┌─powers_list───┐
│ 2, 16, 32 │
└───────────────┘
UInt8 数据类型的取值范围，则会将其转换为
UInt8，此过程中可能发生舍入和溢出。
语法
char(num1[, num2[, ...]])
String
示例
基础示例
SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;
┌─hello─┐
│ hello │
└───────┘
-- 您可以通过传入相应的字节来构造任意编码的字符串。
-- 例如 UTF8
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;
┌─hello──┐
│ привет │
└────────┘
| Type | Description |
|---|
(U)Int* | 按十六进制数字 (“半字节”) 从高位到低位的顺序输出 (大端序，即”人类可读”顺序) 。从最高的非零字节开始输出 (省略前导零字节) ，但每个字节始终都会输出两位，即使高位数字为 0 也不例外。 |
Date and DateTime | 格式化为对应的整数 (Date 为自纪元以来的天数，DateTime 为 Unix timestamp 的值) 。 |
String and FixedString | 所有字节都会直接编码为两个十六进制数字。不会省略零字节。 |
Float* and Decimal | 按它们在内存中的表示形式进行编码。ClickHouse 在内部始终以小端序表示这些值，因此编码结果也是小端序。不会省略前导或尾随的零字节。 |
UUID | 编码为大端序字符串。 |
A-F，且不使用任何前缀 (如 0x) 或后缀 (如 h) 。
语法
参数
返回值
返回参数的十六进制表示形式的字符串。String
示例
简单整数
Float32 数值
SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2)
┌─hex_presentation─┐
│ 00007041 │
│ 00008041 │
└──────────────────┘
SELECT hex(toFloat64(number)) AS hex_presentation FROM numbers(15, 2)
┌─hex_presentation─┐
│ 0000000000002E40 │
│ 0000000000003040 │
└──────────────────┘
SELECT lower(hex(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0'))) AS uuid_hex
┌─uuid_hex─────────────────────────┐
│ 61f0c4045cb311e7907ba6006ad3dba0 │
└──────────────────────────────────┘
hilbertEncode 函数一样，此函数有两种操作模式：
简单模式
最多接受 2 个无符号整数作为参数，并生成一个 UInt64 编码。
扩展模式
接受一个范围掩码 (元组) 作为第一个参数，以及最多 2 个无符号整数作为
其他参数。掩码中的每个数都用于指定对应参数左移的位数，
从而在其取值范围内对该参数进行缩放。
当你希望取值范围 (或基数) 差异很大的
参数具有相近的分布时，范围扩展会很有帮助。例如：‘IP 地址’ (0...FFFFFFFF)
和 ‘国家代码’ (0...FF)。与编码函数一样，这最多仅限于 8 个
数值。
语法
hilbertDecode(tuple_size, code)
Tuple(UInt64)
示例
简单模式
SELECT hilbertDecode(2, 31)
-- 单个参数的 Hilbert 编码始终是该参数本身（作为 Tuple）。
SELECT hilbertDecode(1, 1)
-- 单个参数配合指定位移量的 Tuple，将按相应位数进行右移。
SELECT hilbertDecode(tuple(2), 32768)
-- 首先创建表并插入一些数据
CREATE TABLE hilbert_numbers(
n1 UInt32,
n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1 SETTINGS index_granularity_bytes = '10Mi';
insert into hilbert_numbers (*) values(1,2);
-- 使用列名而非常量作为函数参数
SELECT untuple(hilbertDecode(2, hilbertEncode(n1, n2))) FROM hilbert_numbers;
-- 简单模式
hilbertEncode(args)
-- 扩展模式
hilbertEncode(range_mask, args)
UInt64 编码值。UInt64
示例
简单模式
SELECT hilbertEncode(3, 4)
-- 当参数的取值范围（或基数）差异悬殊时，范围扩展有助于实现相近的分布。
-- 例如：'IP Address'（0...FFFFFFFF）与 'Country code'（0...FF）。
-- 注意：Tuple 的大小必须与其他参数的数量相等。
SELECT hilbertEncode((10, 6), 1024, 16)
-- 对于不带元组的单个参数，函数将直接返回该参数本身作为 Hilbert 索引，因为无需进行维度映射。
SELECT hilbertEncode(1)
-- 如果提供单个参数并附带指定移位量的 Tuple，该函数将把参数向左移位指定的位数。
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;
mortonEncode 函数一样，此函数有两种操作模式：
简单模式
接受结果 Tuple 的大小作为第一个参数，编码值作为第二个参数。
扩展模式
接受范围掩码 (Tuple) 作为第一个参数，编码值作为第二个参数。
掩码中的每个数字用于配置范围收缩的幅度：
1 - 不收缩2 - 收缩 2 倍3 - 收缩 3 倍
⋮- 最多收缩 8 倍。
当你需要让取值范围 (或基数) 差异很大的参数获得相似的分布时，
范围扩展会很有帮助。例如：‘IP 地址’ (0...FFFFFFFF)
和 ‘国家代码’ (0...FF)。与编码函数一样，这里最多也只支持
8 个数字。
语法
-- 简单模式
mortonDecode(tuple_size, code)
-- 扩展模式
mortonDecode(range_mask, code)
Tuple(UInt64)
示例
简单模式
SELECT mortonDecode(3, 53)
SELECT mortonDecode(1, 1)
SELECT mortonDecode(tuple(2), 32768)
-- 首先创建表并插入一些数据
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;
UInt64 编码。
扩展模式
接受一个范围掩码 (Tuple) 作为第一个参数，
并接受最多 8 个无符号整数作为其余参数。
掩码中的每个数字用于指定范围扩展倍数：
- 1 - 不扩展
- 2 - 扩展 2 倍
- 3 - 扩展 3 倍
⋮
- 最多可扩展 8 倍。
语法
-- 简单模式
mortonEncode(args)
-- 扩展模式
mortonEncode(range_mask, args)
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;
sqid 解码得到的数字数组。 Array(UInt64)
示例
使用示例
SELECT sqidDecode('gXHfJ1C6dN');
┌─sqidDecode('gXHfJ1C6dN')─────┐
│ [1, 2, 3, 4, 5] │
└──────────────────────────────┘
sqidEncode(n1[, n2, ...])
sqid
参数
返回值
返回哈希 ID String
示例
使用示例
SELECT sqidEncode(1, 2, 3, 4, 5);
┌─sqidEncode(1, 2, 3, 4, 5)─┐
│ gXHfJ1C6dN │
└───────────────────────────┘
bin 相反的操作。
对于数值参数，unbin() 返回的结果并不是 bin() 的逆运算结果。如果要将结果转换为数值，可以使用 reverse 和 reinterpretAs<Type> 函数。
如果在 clickhouse-client 中调用 unbin，二进制字符串会以 UTF-8 格式显示。
0 和 1。二进制位数不必是 8 的倍数。如果参数字符串中包含二进制数字以外的任何内容，
则结果未定义 (不会抛出异常) 。
语法
参数
返回值
返回二进制字符串 (BLOB) 。String
示例
基本用法
SELECT UNBIN('001100000011000100110010'), UNBIN('0100110101111001010100110101000101001100')
┌─unbin('001100000011000100110010')─┬─unbin('0100110101111001010100110101000101001100')─┐
│ 012 │ MySQL │
└───────────────────────────────────┴───────────────────────────────────────────────────┘
SELECT reinterpretAsUInt64(reverse(unbin('1110'))) AS num
hex 相反的操作。它将参数中的每对十六进制数字解释为一个数值，并将其转换为该数值所表示的字节。返回值是二进制字符串 (BLOB) 。
如果要将结果转换为数值，可以使用 reverse 和 reinterpretAs<Type> 函数。
clickhouse-client 会将字符串解释为 UTF-8。
这可能会导致 hex 返回的值显示效果出乎意料。
A-F。
十六进制数字的位数不必为偶数。
如果是奇数，最后一位会被解释为 00-0F 字节的低半字节。
如果参数字符串中包含十六进制数字之外的其他内容，则会返回某种由具体实现定义的结果 (不会抛出异常) 。
对于数值参数，unhex() 不会执行 hex(N) 的逆操作。
语法
参数
返回值
返回二进制字符串 (BLOB) 。String
示例
基本用法
SELECT unhex('303132'), UNHEX('4D7953514C')
┌─unhex('303132')─┬─unhex('4D7953514C')─┐
│ 012 │ MySQL │
└─────────────────┴─────────────────────┘
SELECT reinterpretAsUInt64(reverse(unhex('FFF'))) AS num
┌──num─┐
│ 4095 │
└──────┘
