跳到主要内容
跳到主要内容

编码函数

bech32Decode

引入于:v25.6

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

备注

与 encode 函数不同,Bech32Decode 将自动处理填充的 FixedStrings。

语法

bech32Decode(address)

参数

返回值

返回一个元组,包含用来编码字符串的 (hrp, 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 数据类型时,如果某个值没有完全填满行,则用空字符填充。 虽然 bech32Encode 函数会自动处理 hrp 参数,但对于 data 参数,值不得填充。 因此,除非您确定所有数据值的长度相同并确保 FixedString 列设置为该长度,否则不建议使用 FixedString 数据类型。

语法

bech32Encode(hrp, data[, witver])

参数

  • hrp — 一个 1 - 83 个小写字符组成的字符串,指定代码的人类可读部分。通常为 'bc' 或 'tb'。 StringFixedString
  • data — 要编码的二进制数据字符串。 StringFixedString
  • witver — 可选。见证版本 (默认 = 1)。一个 UInt*,指定要运行的算法版本。0 表示 Bech32,1 或更大则表示 Bech32m。 UInt*

返回值

返回一个 Bech32 地址字符串,包含人类可读部分、一个总是为 '1' 的分隔符字符,以及一个数据部分。字符串的长度不会超过 90 个字符。如果算法无法从输入生成有效地址,将返回一个空字符串。 String

示例

默认 Bech32m

-- When no witness version is supplied, the default is 1, the updated Bech32m algorithm.
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'))
bc1w508d6qejxtdg4y5r3zarvary0c5xw7k8zcwmq

Bech32 算法

-- A witness version of 0 will result in a different address string.
SELECT bech32Encode('bc', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 0)
bc1w508d6qejxtdg4y5r3zarvary0c5xw7kj7gz7z

自定义 HRP

-- While 'bc' (Mainnet) and 'tb' (Testnet) are the only allowed hrp values for the
-- SegWit address format, Bech32 allows any hrp that satisfies the above requirements.
SELECT bech32Encode('abcdefg', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 10)
abcdefg1w508d6qejxtdg4y5r3zarvary0c5xw7k9rp8r4

bin

引入于:v21.8

返回一个包含参数的二进制表示的字符串,根据以下不同类型的逻辑:

类型描述
(U)Int*从最重要位到最不重要位打印二进制位(大端或“人类可读”顺序)。从最重要的非零字节开始(省略前导零字节)但始终打印每个字节的八位数字,即使前导数字为零。
DateDateTime格式化为相应的整数(Date 的自纪元以来的天数,以及 DateTime 的 Unix 时间戳值)。
StringFixedString所有字节简单地编码为八个二进制数字。零字节不会被省略。
Float*Decimal编码为它们在内存中的表示。由于我们支持小端架构,因此它们以小端方式编码。前导/结尾的零字节不被省略。
UUID编码为大端顺序字符串。

语法

bin(arg)

参数

返回值

返回参数的二进制表示字符串。 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)

示例

单个位被设置

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]  │
└───────────────────────────┘

bitmaskToArray

引入于:v1.1

该函数将整数分解为 2 的幂之和。 以升序排列的幂将作为数组返回。

语法

bitmaskToArray(num)

参数

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

返回值

返回一个包含组成输入数字的升序排列的幂的数组。 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)

参数

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

返回值

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

示例

基本示例

SELECT bitmaskToList(50) AS powers_list
┌─powers_list───┐
│ 2, 16, 32     │
└───────────────┘

char

引入于:v20.1

返回一个长度等于传递的参数个数的字符串,其中每个字节的值等于相应参数的值。接受多种数值类型的多个参数。

如果参数的值超出 UInt8 数据类型的范围,则可能会有舍入和溢出,转换为 UInt8

语法

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

参数

返回值

返回给定字节的字符串。 String

示例

基本示例

SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;
┌─hello─┐
│ hello │
└───────┘

构建任意编码

-- You can construct a string of arbitrary encoding by passing the corresponding bytes.
-- for example UTF8
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;
┌─hello──┐
│ привет │
└────────┘

hex

引入于:v1.1

返回一个字符串,其中包含参数的十六进制表示,按照以下不同类型的逻辑:

类型描述
(U)Int*从最重要到最不重要位打印十六进制数字(“半字节”)(大端或“人类可读”顺序)。从最重要的非零字节开始(省略前导零字节)但始终打印每个字节的两个数字,即使前导数字是零。
DateDateTime格式化为相应的整数(Date 的自纪元以来的天数,以及 DateTime 的 Unix 时间戳值)。
StringFixedString所有字节简单编码为两个十六进制数字。零字节不会被省略。
Float*Decimal编码为它们在内存中的表示。ClickHouse 内部始终以小端方式表示这些值,因此以此方式编码。前导/后缀的零字节不会被省略。
UUID编码为大端顺序字符串。

该函数使用大写字母 A-F,并且不使用前缀(如 0x)或后缀(如 h)。

语法

hex(arg)

参数

返回值

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

示例

简单整数

SELECT hex(1)
01

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 地址” (0...FFFFFFFF) 和 “国家代码” (0...FF)。与编码函数一样,这个限制为最多 8 个数字。

语法

hilbertDecode(tuple_size, code)

参数

返回值

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

示例

简单模式

SELECT hilbertDecode(2, 31)
["3", "4"]

单个参数

-- Hilbert code for one argument is always the argument itself (as a tuple).
SELECT hilbertDecode(1, 1)
["1"]

扩展模式

-- A single argument with a tuple specifying bit shifts will be right-shifted accordingly.
SELECT hilbertDecode(tuple(2), 32768)
["128"]

列用法

-- First create the table and insert some data
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);

-- Use column names instead of constants as function arguments
SELECT untuple(hilbertDecode(2, hilbertEncode(n1, n2))) FROM hilbert_numbers;
1    2

hilbertEncode

引入于:v24.6

为一系列无符号整数计算 Hilbert 曲线代码。

该函数有两种操作模式:

  • 简单
  • 扩展

简单模式

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

扩展模式

将范围掩码 (Tuple) 作为第一个参数,最多接受 2 个 无符号整数 作为其他参数。

掩码中的每个数字配置对应参数向左移动的位数,有效地在其范围内缩放参数。

语法

-- Simplified mode
hilbertEncode(args)

-- Expanded mode
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)
31

扩展模式

-- Range expansion can be beneficial when you need a similar distribution for
-- arguments with wildly different ranges (or cardinality).
-- For example: 'IP Address' (0...FFFFFFFF) and 'Country code' (0...FF).
-- Note: tuple size must be equal to the number of the other arguments.
SELECT hilbertEncode((10, 6), 1024, 16)
4031541586602

单个参数

-- For a single argument without a tuple, the function returns the argument
-- itself as the Hilbert index, since no dimensional mapping is needed.
SELECT hilbertEncode(1)
1

扩展单个参数

-- If a single argument is provided with a tuple specifying bit shifts, the function
-- shifts the argument left by the specified number of bits.
SELECT hilbertEncode(tuple(2), 128)
512

列用法

-- First create the table and insert some data
CREATE TABLE hilbert_numbers(
    n1 UInt32,
    n2 UInt32
)
ENGINE=MergeTree()
ORDER BY n1;
insert into hilbert_numbers (*) values(1, 2);

-- Use column names instead of constants as function arguments
SELECT hilbertEncode(n1, n2) FROM hilbert_numbers;
13

mortonDecode

引入于:v24.6

将摩顿编码 (ZCurve) 解码为对应的无符号整数元组。

mortonEncode 函数一样,该函数有两种操作模式:

  • 简单
  • 扩展

简单模式

接受结果的元组大小作为第一个参数,代码作为第二个参数。

扩展模式

将范围掩码(元组)作为第一个参数,将代码作为第二个参数。 掩码中的每个数字配置范围缩小的量:

  • 1 - 不缩小
  • 2 - 2x 缩小
  • 3 - 3x 缩小 ⋮
  • 最多 8x 缩小。

范围扩展在需要为具有截然不同范围(或基数)的参数提供相似分布时可能非常有用。例如:“IP 地址” (0...FFFFFFFF) 和 “国家代码” (0...FF)。与编码函数一样,这个限制为最多 8 个数字。

语法

-- Simple mode
mortonDecode(tuple_size, code)

-- Expanded mode
mortonDecode(range_mask, code)

参数

  • tuple_size — 不超过 8 的整数值。 UInt8/16/32/64
  • range_mask — 对于扩展模式,每个参数的掩码。掩码是无符号整数的元组。掩码中的每个数字配置范围缩小的量。 Tuple(UInt8/16/32/64)
  • codeUInt64 代码。 UInt64

返回值

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

示例

简单模式

SELECT mortonDecode(3, 53)
["1", "2", "3"]

单个参数

SELECT mortonDecode(1, 1)
["1"]

扩展模式,缩小一个参数

SELECT mortonDecode(tuple(2), 32768)
["128"]

列用法

-- First create the table and insert some data
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);

-- Use column names instead of constants as function arguments
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

为一系列无符号整数计算摩顿编码 (ZCurve)。

该函数有两种操作模式:

  • 简单
  • 扩展

简单模式

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

扩展模式

将范围掩码 (Tuple) 作为第一个参数,最多接受 8 个 无符号整数 作为其他参数。

掩码中的每个数字配置范围扩展的量:

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

语法

-- Simplified mode
mortonEncode(args)

-- Expanded mode
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)
53

扩展模式

-- Range expansion can be beneficial when you need a similar distribution for
-- arguments with wildly different ranges (or cardinality)
-- For example: 'IP Address' (0...FFFFFFFF) and 'Country code' (0...FF).
-- Note: the Tuple size must be equal to the number of the other arguments.
SELECT mortonEncode((1,2), 1024, 16)
1572864

单个参数

-- Morton encoding for one argument is always the argument itself
SELECT mortonEncode(1)
1

扩展单个参数

SELECT mortonEncode(tuple(2), 128)
32768

列用法

-- First create the table and insert some data
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);

-- Use column names instead of constants as function arguments
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, ...])

参数

返回值

返回哈希 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> 函数。

备注

如果 unbin 是从 clickhouse-client 中调用的,二进制字符串将以 UTF-8 显示。

支持二进制数字 01。二进制数字的数量不必是八的倍数。如果参数字符串包含除二进制数字以外的任何内容,结果是未定义的(不会抛出异常)。

语法

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)。

如果您想将结果转换为数字,可以使用 reversereinterpretAs<Type> 函数。

备注

clickhouse-client 将字符串解释为 UTF-8。 这可能会导致通过 hex 返回的值被意外地显示。

支持大写和小写字母 A-F。 十六进制数字的数量不必是偶数。 如果是奇数,最后一个数字被解释为 00-0F 字节的最低有效位。 如果参数字符串包含除十六进制数字以外的任何内容,则返回一些实现定义的结果(不会抛出异常)。 对于数值参数,unhex() 不执行 hex(N) 的逆操作。

语法

unhex(arg)

参数

  • arg — 一个包含任意数量十六进制数字的字符串。 StringFixedString

返回值

返回一个二进制字符串(BLOB)。 String

示例

基本用法

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

转换为数字

SELECT reinterpretAsUInt64(reverse(unhex('FFF'))) AS num
┌──num─┐
│ 4095 │
└──────┘