Кодировочные функции

bech32Decode

Введено в: v25.6

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

примечание

В отличие от функции encode, Bech32Decode автоматически обрабатывает дополненные FixedStrings.

Синтаксис

bech32Decode(address)

Аргументы

address — Строка Bech32 для декодирования. String или FixedString

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

Возвращает кортеж, состоящий из (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

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

примечание

При использовании типа данных FixedString значение, если оно не заполняет полностью строку, дополняется нулевыми символами. Хотя функция bech32Encode автоматически обрабатывает это для аргумента hrp, для аргумента data значения не должны быть дополнены. По этой причине не рекомендуется использовать тип данных FixedString для ваших значений данных, если вы не уверены, что они все одной длины и что ваша колонка FixedString также установлена на эту длину.

Синтаксис

bech32Encode(hrp, data[, witver])

Аргументы

hrp — Строка из 1 - 83 строчных символов, указывающая "человеко-читаемую часть" кода. Обычно 'bc' или 'tb'. String или FixedString
data — Строка двоичных данных для кодирования. String или FixedString
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*`	Печатает двоичные цифры от наиболее значимого к наименее значимому (большой порядок или "человеко-читаемый" порядок). Начинает с наиболее значимого ненулевого байта (ведущие нулевые байты опускаются), но всегда печатает восемь цифр каждого байта, если ведущая цифра равна нулю.
`Date` и `DateTime`	Форматируется как соответствующие целые числа (количество дней с начала эпохи для Date и значение unix временной метки для DateTime).
`String` и `FixedString`	Все байты просто кодируются как восемь двоичных чисел. Нулевые байты не опускаются.
`Float*` и `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

Эта функция возвращает позиции (в порядке возрастания) единичных битов в двоичном представлении без знакового целого числа. Значения входных знаковых целых чисел сначала преобразуются в беззнаковые целые числа.

Синтаксис

bitPositionsToArray(arg)

Аргументы

arg — Целочисленное значение. (U)Int*

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

Возвращает массив с упорядоченными по возрастанию позициями единичных битов в двоичном представлении входного значения. 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

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

Синтаксис

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

bitmaskToList

Введено в: v1.1

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

Синтаксис

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[, ...]])

Аргументы

num1[, num2[, num3 ...]] — Числовые аргументы, интерпретируемые как целые числа. (U)Int8/16/32/64 или Float*

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

Возвращает строку данных байтов. 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*`	Печатает шестнадцатеричные цифры ("нibbles") от наиболее значимого к наименее значимому (большой порядок или "человеко-читаемый" порядок). Начинает с наиболее значимого ненулевого байта (ведущие нулевые байты опускаются), но всегда печатает обе цифры каждого байта, даже если ведущая цифра равна нулю.
`Date` и `DateTime`	Форматируется как соответствующие целые числа (количество дней с начала эпохи для Date и значение unix временной метки для DateTime).
`String` и `FixedString`	Все байты просто кодируются как два шестнадцатеричных числа. Нулевые байты не опускаются.
`Float*` и `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

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

Как и функция 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 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

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

Функция имеет два режима работы:

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

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

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

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

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

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

Синтаксис

-- Simplified mode
hilbertEncode(args)

-- Expanded mode
hilbertEncode(range_mask, args)

Аргументы

args — До двух значений или колонок типа UInt. UInt8/16/32/64
range_mask — Для расширенного режима, до двух значений или колонок типа UInt. UInt8/16/32/64

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

Возвращает код UInt64. UInt64

Примеры

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

SELECT hilbertEncode(3, 4)

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

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

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

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

Использование колонки

-- 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;

mortonDecode

Введено в: v24.6

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

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

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

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

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

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

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

1 - без уменьшения
2 - уменьшение в 2 раза
3 - уменьшение в 3 раза ⋮
Уменьшение до 8 раз.

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

mortonEncode

Введено в: v24.6

Вычисляет кодировку Мортона (ZCurve) для списка беззнаковых целых чисел.

Функция имеет два режима работы:

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

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

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

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

Принимает маску диапазона (Tuple) в качестве первого аргумента и до 8 беззнаковых целых чисел в качестве других аргументов.

Каждое число в маске настраивает величину расширения диапазона:

1 - без расширения
2 - расширение в 2 раза
3 - расширение в 3 раза ⋮
Увеличение до 8 раз.

Синтаксис

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

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

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

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

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

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

SELECT mortonEncode(tuple(2), 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 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.

Синтаксис

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

Аргументы

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(). Если вы хотите преобразовать результат в число, вы можете использовать функции обратного и reinterpretAs<Type>.

примечание

Если unbin вызывается изнутри clickhouse-client, двоичные строки отображаются с использованием UTF-8.

Поддерживает двоичные цифры 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 │
└─────┘

unhex

Введено в: v1.1

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

Если вы хотите преобразовать результат в число, вы можете использовать функции обратного и 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