Перейти к основному содержанию
Перейти к основному содержанию

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

bech32Decode

Появилась в: v25.6

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

Примечание

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

Синтаксис

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 строчных символов, задающая «human-readable part» (человекочитаемую часть) кода. Обычно bc или tb. String или FixedString
  • data — Строка двоичных данных для кодирования. String или FixedString
  • witver — Необязательный параметр. Версия witness (по умолчанию = 1). Тип UInt*, задающий версию алгоритма. 0 для Bech32 и 1 или больше для Bech32m. UInt*

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

Возвращает строку адреса Bech32, состоящую из human-readable part, символа-разделителя, который всегда равен 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*Выводит двоичные цифры от наиболее значащего к наименее значащему (big-endian или «удобочитаемый для человека» порядок). Начинает с наиболее значащего ненулевого байта (ведущие нулевые байты опускаются), но всегда выводит восемь цифр для каждого байта, если ведущая цифра равна нулю.
Date и DateTimeФорматируются как соответствующие целые числа (количество дней с начала эпохи для Date и значение UNIX timestamp для DateTime).
String и FixedStringВсе байты просто кодируются как восемь двоичных цифр. Нулевые байты не опускаются.
Float* и DecimalКодируются в соответствии с их представлением в памяти. Так как поддерживается архитектура little-endian, они кодируются в формате little-endian. Ведущие и замыкающие нулевые байты не опускаются.
UUIDКодируется как строка в порядке big-endian.

Синтаксис

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

Все биты равны 1

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

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

TypeDescription
(U)Int*Печатает шестнадцатеричные цифры («полубайты», nibbles) от старшего к младшему (big-endian или «читаемый человеком» порядок). Начинается со старшего ненулевого байта (ведущие нулевые байты опускаются), но всегда печатает обе цифры каждого байта, даже если старшая цифра равна нулю.
Date and DateTimeФорматируется как соответствующие целые числа (количество дней с начала эпохи Unix для Date и значение UNIX timestamp для DateTime).
String and FixedStringВсе байты просто кодируются как две шестнадцатеричные цифры. Нулевые байты не опускаются.
Float* and DecimalКодируются как их представление в памяти. ClickHouse всегда представляет значения во внутреннем виде в формате little endian, поэтому они кодируются именно так. Ведущие и замыкающие нулевые байты не опускаются.
UUIDКодируется как строка в порядке big-endian.

Функция использует заглавные буквы 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 │
└──────────────────────────────────┘

hilbertDecode

Добавлена в версии v24.6

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

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

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

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

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

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

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

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

Декодирует кодировку Morton (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)
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.

Синтаксис

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

unbin

Появилась в: v21.8

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

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

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