Функции кодирования

Добавленный в: v25.6.0

Декодирует строку адреса Bech32, сгенерированную алгоритмами bech32 или bech32m.

Синтаксис

bech32Decode(address[, 'raw'])

Аргументы

• address — Строка Bech32 для декодирования. String или FixedString
• mode — Необязательно. Передайте 'raw', чтобы декодировать без удаления первого байта, используемого как witness version. Используйте это для адресов, не относящихся к SegWit (например, Cosmos SDK). String

Возвращаемое значение

Возвращает кортеж (hrp, data), использованный для кодирования строки. Данные представлены в бинарном формате. Tuple(String, String)

Примеры

Декодирование адреса

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

┌─hrp─┬─data─────────────────────────────────────┐
│ bc  │ 751E76E8199196D454941C45D1B3A323F1433BD6 │
└─────┴──────────────────────────────────────────┘

Адрес тестнета

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

┌─hrp─┬─data─────────────────────────────────────┐
│ tb  │ 751E76E8199196D454941C45D1B3A323F1433BD6 │
└─────┴──────────────────────────────────────────┘

Добавленный в: v25.6.0

Кодирует строку двоичных данных вместе с человекочитаемой частью (HRP) с использованием алгоритмов Bech32 или Bech32m.

Синтаксис

bech32Encode(hrp, data[, witver | 'bech32' | 'bech32m'])

Аргументы

• hrp — Строка из 1 - 83 строчных символов, задающая "человекочитаемую часть" кода. Обычно это 'bc' или 'tb'. String или FixedString
• data — Строка двоичных данных для кодирования. String или FixedString
• witver_or_variant — Необязательно. Либо witness version типа UInt* (по умолчанию = 1, 0 для Bech32, 1+ для Bech32m), либо строковый вариант кодирования: 'bech32' (BIP173) или 'bech32m' (BIP350). При использовании строкового варианта байт witness version не добавляется в начало — это требуется для адресов, не относящихся к SegWit, например Cosmos SDK. UInt* или String

Возвращаемое значение

Возвращает строку адреса Bech32, состоящую из человекочитаемой части, символа-разделителя, которым всегда является '1', и части данных. Длина строки никогда не превышает 90 символов. Если алгоритм не может сгенерировать корректный адрес из входных данных, возвращается пустая строка. String

Примеры

Bech32m по умолчанию

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

bc1pw508d6qejxtdg4y5r3zarvary0c5xw7kj9wkru

Алгоритм Bech32

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

bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4

Пользовательский 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)

abcdefg12w508d6qejxtdg4y5r3zarvary0c5xw7kh526px

Адрес Cosmos SDK (BIP173, без witness version)

-- Using 'bech32' variant encodes raw data without a witness version byte,
-- compatible with Cosmos SDK, Injective, Osmosis, and other non-SegWit chains.
SELECT bech32Encode('inj', unhex('751e76e8199196d454941c45d1b3a323f1433bd6'), 'bech32')

inj1w508d6qejxtdg4y5r3zarvary0c5xw7ks5q7aq

Добавленный в: v21.8.0

Возвращает строку, содержащую двоичное представление аргумента согласно следующей логике для разных типов:

Синтаксис

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

Добавленный в: v21.7.0

Эта функция возвращает позиции (в порядке возрастания) битов со значением 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] │
└───────────────────┘

Добавленный в: v1.1.0

Эта функция раскладывает целое число на сумму степеней двойки. Степени двойки возвращаются в виде массива, упорядоченного по возрастанию.

Синтаксис

bitmaskToArray(num)

Аргументы

• num — Целое число. (U)Int*

Возвращаемое значение

Возвращает массив степеней двойки, упорядоченных по возрастанию, сумма которых равна входному числу. 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]           │
└───────────────┘

Добавленный в: v1.1.0

Как и bitmaskToArray, но возвращает степени двойки в виде строки, где значения разделены запятыми.

Синтаксис

bitmaskToList(num)

Аргументы

• num — Целое число. (U)Int*

Возвращаемое значение

Возвращает строку со степенями двойки, разделёнными запятыми. String

Примеры

Базовый пример

SELECT bitmaskToList(50) AS powers_list

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

Добавленный в: v20.1.0

Возвращает строку, длина которой равна числу переданных аргументов, при этом каждый байт имеет значение соответствующего аргумента. Принимает несколько аргументов числовых типов.

Если значение аргумента выходит за пределы диапазона типа данных 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 │
└───────┘

Создание произвольных кодировок

-- Можно построить строку произвольной кодировки, передав соответствующие байты.
-- например UTF8
SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;

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

Добавленный в: v1.1.0

Возвращает строку, содержащую шестнадцатеричное представление аргумента в соответствии со следующей логикой для разных типов:

Функция использует заглавные буквы A-F и не использует никаких префиксов (например, 0x) или суффиксов (например, h).

Синтаксис

hex(arg)

Аргументы

• arg — значение для преобразования в шестнадцатеричное представление. String или (U)Int* или Float* или Decimal или Date или DateTime

Возвращаемое значение

Строка с шестнадцатеричным представлением аргумента. 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 │
└──────────────────────────────────┘

Добавленный в: v24.6.0

Декодирует индекс кривой Гильберта обратно в кортеж беззнаковых целых чисел, представляющий координаты в многомерном пространстве.

Как и функция hilbertEncode, эта функция поддерживает два режима работы:

• Простой
• Расширенный

Простой режим

Принимает до 2 беззнаковых целых чисел в качестве аргументов и возвращает код UInt64.

Расширенный режим

Принимает маску диапазона (кортеж) в качестве первого аргумента и до 2 беззнаковых целых чисел в качестве остальных аргументов. Каждое число в маске задает количество битов, на которое соответствующий аргумент будет сдвинут влево, фактически масштабируя аргумент в пределах его диапазона.

Расширение диапазона может быть полезно, когда нужно получить схожее распределение для аргументов с сильно различающимися диапазонами (или мощностью). Например: 'IP-адрес' (0...FFFFFFFF) и 'код страны' (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 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)

(8192)

Использование столбцов

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

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

1	2

Добавленный в: v24.6.0

Вычисляет код кривой Гильберта для списка беззнаковых целых чисел.

У функции есть два режима работы:

• Простой
• Расширенный

Простой режим

Принимает до 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)

31

Расширенный режим

-- Расширение диапазона полезно, когда нужно схожее распределение для
-- аргументов с существенно различающимися диапазонами (или мощностью).
-- Например: 'IP-адрес' (0...FFFFFFFF) и 'Код страны' (0...FF).
-- Примечание: размер кортежа должен совпадать с количеством остальных аргументов.
SELECT hilbertEncode((10, 6), 1024, 16)

4031541586602

Один аргумент

-- Для одного аргумента без кортежа функция возвращает сам аргумент
-- в качестве индекса Гильберта, так как размерное отображение не требуется.
SELECT hilbertEncode(1)

1

Расширенный вариант с одним аргументом

-- Если передан один аргумент с кортежем, задающим битовые сдвиги, функция
-- сдвигает аргумент влево на указанное количество битов.
SELECT hilbertEncode(tuple(2), 128)

512

Использование столбцов

-- Сначала создайте таблицу и вставьте данные
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;

13

Добавленный в: v24.6.0

Декодирует кодировку Morton (ZCurve) в соответствующий кортеж беззнаковых целых чисел.

Как и функция mortonEncode, эта функция имеет два режима работы:

• Простой
• Расширенный

Простой режим

Принимает размер результирующего кортежа в качестве первого аргумента, а код — в качестве второго.

Расширенный режим

Принимает маску диапазона (кортеж) в качестве первого аргумента, а код — в качестве второго. Каждое число в маске задаёт степень сужения диапазона:

• 1 - без сужения
• 2 - сужение в 2 раза
• 3 - сужение в 3 раза ⋮
• До 8-кратного сужения.

Расширение диапазонов может быть полезно, если нужно получить схожее распределение для аргументов с сильно различающимися диапазонами (или мощностью). Например: '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)
• code — Код типа UInt64. 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

Добавленный в: v24.6.0

Вычисляет кодирование Morton (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)

53

Расширенный режим

-- Расширение диапазона полезно, когда требуется схожее распределение для
-- аргументов с существенно различающимися диапазонами (или мощностью)
-- Например: 'IP-адрес' (0...FFFFFFFF) и 'Код страны' (0...FF).
-- Примечание: размер Tuple должен быть равен количеству остальных аргументов.
SELECT mortonEncode((1,2), 1024, 16)

1572864

Один аргумент

-- Кодирование Мортона для одного аргумента всегда равно самому аргументу
SELECT mortonEncode(1)

1

Расширенный режим с одним аргументом

SELECT mortonEncode(tuple(2), 128)

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 mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8) FROM morton_numbers;

2155374165

Добавленный в: v24.1.0

Преобразует sqid обратно в массив чисел.

Синтаксис

sqidDecode(sqid)

Аргументы

• sqid — sqid, который нужно декодировать. String

Возвращаемое значение

Возвращает массив чисел, полученных из sqid. Array(UInt64)

Примеры

Пример использования

SELECT sqidDecode('gXHfJ1C6dN');

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

Добавленный в: v24.1.0

Преобразует числа в sqid — строковый идентификатор в стиле YouTube.

Синтаксис

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

Псевдонимы: sqid

Аргументы

• n1[, n2, ...] — Произвольное количество чисел. UInt8/16/32/64

Возвращаемое значение

Возвращает хеш-идентификатор в виде String

Примеры

Пример использования

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

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

Добавленный в: v21.8.0

Интерпретирует каждую пару двоичных цифр (в аргументе) как число и преобразует её в байт, представленный этим числом. Функция выполняет операцию, обратную bin.

Для числового аргумента unbin() не возвращает результат, обратный bin(). Если вы хотите преобразовать результат в число, можно использовать функции reverse и reinterpretAs<Type>.

Поддерживаются двоичные цифры 0 и 1. Количество двоичных цифр не обязательно должно быть кратно восьми. Если строковый аргумент содержит что-либо, кроме двоичных цифр, результат не определён (исключение не генерируется).

Синтаксис

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

Добавленный в: v1.1.0

Выполняет операцию, обратную hex. Интерпретирует каждую пару шестнадцатеричных цифр (в аргументе) как число и преобразует её в байт, соответствующий этому числу. Возвращаемое значение — двоичная строка (BLOB).

Если вы хотите преобразовать результат в число, можно использовать функции reverse и reinterpretAs<Type>.

Поддерживаются как прописные, так и строчные буквы A-F. Количество шестнадцатеричных цифр не обязательно должно быть чётным. Если оно нечётное, последняя цифра интерпретируется как младшая половина байта 00-0F. Если строка аргумента содержит символы, отличные от шестнадцатеричных цифр, возвращается некоторый зависящий от реализации результат (исключение не генерируется). Для числового аргумента обратное преобразование hex(N) с помощью unhex() не выполняется.

Синтаксис

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