Функции кодирования
bech32Decode
Появилась в: v25.6
Декодирует строку адреса Bech32, созданную с помощью алгоритма bech32 или bech32m.
В отличие от функции кодирования, Bech32Decode автоматически обрабатывает дополненные нулями значения типа FixedString.
Синтаксис
Аргументы
address— строка в формате Bech32 для декодирования.StringилиFixedString
Возвращаемое значение
Возвращает кортеж (hrp, data), который был использован для кодирования строки. Данные представлены в двоичном формате. Tuple(String, String)
Примеры
Декодирование адреса
Адрес в тестовой сети
bech32Encode
Впервые появилась в: v25.6
Кодирует строку двоичных данных вместе с человекочитаемой частью (HRP), используя алгоритмы Bech32 или Bech32m.
При использовании типа данных FixedString, если значение не полностью заполняет строку, оно дополняется нулевыми символами.
Функция bech32Encode автоматически обрабатывает это для аргумента hrp, но для аргумента data значения не должны быть дополнены.
По этой причине не рекомендуется использовать тип данных FixedString для ваших значений, если только вы не
уверены, что все они одной и той же длины и что столбец FixedString также имеет эту длину.
Синтаксис
Аргументы
hrp— Строка из1 - 83строчных символов, задающая «human-readable part» (человекочитаемую часть) кода. Обычноbcилиtb.StringилиFixedStringdata— Строка двоичных данных для кодирования.StringилиFixedStringwitver— Необязательный параметр. Версия witness (по умолчанию = 1). ТипUInt*, задающий версию алгоритма.0для Bech32 и1или больше для Bech32m.UInt*
Возвращаемое значение
Возвращает строку адреса Bech32, состоящую из human-readable part, символа-разделителя, который всегда равен 1, и части данных. Длина строки никогда не превышает 90 символов. Если алгоритм не может сгенерировать корректный адрес из входных данных, возвращается пустая строка. String
Примеры
Bech32m по умолчанию
Алгоритм Bech32
Пользовательский HRP
bin
Появилась в версии: v21.8
Возвращает строку, содержащую двоичное представление аргумента в соответствии со следующей логикой для разных типов:
| Тип | Описание |
|---|---|
(U)Int* | Выводит двоичные цифры от наиболее значащего к наименее значащему (big-endian или «удобочитаемый для человека» порядок). Начинает с наиболее значащего ненулевого байта (ведущие нулевые байты опускаются), но всегда выводит восемь цифр для каждого байта, если ведущая цифра равна нулю. |
Date и DateTime | Форматируются как соответствующие целые числа (количество дней с начала эпохи для Date и значение UNIX timestamp для DateTime). |
String и FixedString | Все байты просто кодируются как восемь двоичных цифр. Нулевые байты не опускаются. |
Float* и Decimal | Кодируются в соответствии с их представлением в памяти. Так как поддерживается архитектура little-endian, они кодируются в формате little-endian. Ведущие и замыкающие нулевые байты не опускаются. |
UUID | Кодируется как строка в порядке big-endian. |
Синтаксис
Аргументы
arg— значение, которое нужно преобразовать в двоичное представление.StringилиFixedStringили(U)Int*илиFloat*илиDecimalилиDateилиDateTime
Возвращаемое значение
Возвращает строку — двоичное представление аргумента. String
Примеры
Простое целое число
Числа типа Float32
Числа типа Float64
Конвертация UUID
bitPositionsToArray
Впервые появилась в версии: v21.7
Эта функция возвращает позиции (в порядке возрастания) битов, равных 1, в двоичном представлении беззнакового целого числа. Знаковые целые числа во входных данных предварительно приводятся к беззнаковому целому числу.
Синтаксис
Аргументы
arg— целое значение.(U)Int*
Возвращаемое значение
Возвращает массив с позициями битов, равных 1, в двоичном представлении входного значения, упорядоченными по возрастанию. Array(UInt64)
Примеры
Установлен один бит
Все биты равны 1
bitmaskToArray
Введена в версии v1.1
Эта функция разлагает целое число в сумму степеней двойки. Степени двойки возвращаются в виде массива, отсортированного по возрастанию.
Синтаксис
Аргументы
num— целое число.(U)Int*
Возвращаемое значение
Возвращает массив степеней двойки, упорядоченных по возрастанию, сумма которых равна входному числу. Array(UInt64)
Примеры
Базовый пример
Одна степень двойки
bitmaskToList
Добавлена в версии: v1.1
Аналогична функции bitmaskToArray, но возвращает степени двойки в виде строки, где значения разделены запятыми.
Синтаксис
Аргументы
num— целочисленное значение.(U)Int*
Возвращаемое значение
Возвращает строку со степенями двойки, разделёнными запятыми. String
Примеры
Простой пример
char
Впервые появилась в: v20.1
Возвращает строку длиной, равной количеству переданных аргументов, где каждый байт имеет значение соответствующего аргумента. Принимает несколько аргументов числовых типов.
Если значение аргумента выходит за пределы диапазона типа данных UInt8, то оно приводится
к UInt8 с возможным округлением и переполнением.
Синтаксис
Аргументы
num1[, num2[, num3 ...]]— числовые аргументы, рассматриваемые как целые числа.(U)Int8/16/32/64илиFloat*
Возвращаемое значение
Возвращает строку, составленную из указанных байтов. String
Примеры
Базовый пример
Создание произвольных кодировок
hex
Впервые появилась в: v1.1
Возвращает строку, содержащую шестнадцатеричное представление аргумента в соответствии со следующей логикой для разных типов:
| Type | Description |
|---|---|
(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).
Синтаксис
Аргументы
arg— значение, которое нужно преобразовать в шестнадцатеричный формат.Stringили(U)Int*илиFloat*илиDecimalилиDateилиDateTime
Возвращаемое значение
Возвращает строку с шестнадцатеричным представлением аргумента. String
Примеры
Простое целое число
Числа типа Float32
Числа с плавающей запятой Float64
Преобразование UUID
hilbertDecode
Добавлена в версии v24.6
Декодирует индекс кривой Гильберта обратно в кортеж беззнаковых целых чисел, представляющих координаты в многомерном пространстве.
Как и функция hilbertEncode, эта функция имеет два режима работы:
- Простой
- Расширенный
Простой режим
Принимает до 2 беззнаковых целых чисел в качестве аргументов и возвращает код типа UInt64.
Расширенный режим
Принимает маску диапазона (кортеж) в качестве первого аргумента и до 2 беззнаковых целых чисел в качестве остальных аргументов. Каждое число в маске задаёт количество бит, на которое соответствующий аргумент будет сдвинут влево, фактически масштабируя аргумент в пределах его диапазона.
Расширение диапазона может быть полезно, когда вам нужно схожее распределение для
аргументов с сильно различающимися диапазонами (или кардинальностью). Например: «IP Address» (0...FFFFFFFF)
и «Country code» (0...FF). Как и в функции кодирования, это ограничено максимум 8
числами.
Синтаксис
Аргументы
tuple_size— целое число не более2.UInt8/16/32/64илиTuple(UInt8/16/32/64)code— код типаUInt64.UInt64
Возвращаемое значение
Возвращает кортеж указанного размера. Tuple(UInt64)
Примеры
Простой режим
Один аргумент
Расширенный режим
Использование столбцов
hilbertEncode
Добавлена в версии v24.6
Вычисляет код кривой Гильберта для списка беззнаковых целых чисел.
Функция имеет два режима работы:
- Простой
- Расширенный
Простой режим
Принимает до 2 беззнаковых целых чисел в качестве аргументов и возвращает код типа UInt64.
Расширенный режим
Принимает маску диапазона (Tuple) в качестве первого аргумента и до 2 беззнаковых целых чисел в качестве остальных аргументов.
Каждое число в маске задаёт количество битов, на которое соответствующий аргумент будет сдвинут влево, фактически масштабируя аргумент в его диапазоне.
Синтаксис
Аргументы
args— до двух значенийUIntили столбцов типаUInt.UInt8/16/32/64range_mask— в расширенном режиме, до двух значенийUIntили столбцов типаUInt.UInt8/16/32/64
Возвращаемое значение
Возвращает код типа UInt64. UInt64
Примеры
Простой режим
Расширенный режим
Один аргумент
Расширенный вариант с одним аргументом
Использование столбцов
mortonDecode
Добавлена в: v24.6
Декодирует кодировку Morton (ZCurve) в соответствующий кортеж беззнаковых целых чисел.
Как и функция mortonEncode, эта функция имеет два режима работы:
- Простой
- Расширенный
Простой режим
Принимает требуемый размер результирующего кортежа в качестве первого аргумента и код в качестве второго аргумента.
Расширенный режим
Принимает маску диапазона (кортеж) в качестве первого аргумента и код в качестве второго аргумента. Каждое число в маске настраивает степень сжатия диапазона:
1— без сжатия2— сжатие в 2 раза3— сжатие в 3 раза ⋮- До сжатия в 8 раз.
Масштабирование диапазонов может быть полезно, когда вам требуется схожее распределение
для аргументов с сильно различающимися диапазонами (или кардинальностью). Например: 'IP Address' (0...FFFFFFFF)
и 'Country code' (0...FF). Как и при кодировании, это ограничено максимум
8 числами.
Синтаксис
Аргументы
tuple_size— целое число не больше 8.UInt8/16/32/64range_mask— для расширенного режима маска для каждого аргумента. Маска — это кортеж беззнаковых целых чисел. Каждое число в маске задаёт степень сужения диапазона.Tuple(UInt8/16/32/64)code— код целого числа типа UInt64.UInt64
Возвращаемое значение
Возвращает кортеж заданного размера. Tuple(UInt64)
Примеры
Простой режим
Один аргумент
Расширенный режим, сжатие одного аргумента
Использование столбца
mortonEncode
Добавлена в: v24.6
Вычисляет кодирование Мортона (ZCurve) для списка беззнаковых целых чисел.
Функция имеет два режима работы:
- Простой
- Расширенный*
Простой режим
Принимает до 8 беззнаковых целых чисел в качестве аргументов и возвращает код типа UInt64.
Расширенный режим
Принимает маску диапазона (Tuple) в качестве первого аргумента и до 8 беззнаковых целых чисел в качестве остальных аргументов.
Каждое число в маске задаёт степень расширения диапазона:
- 1 — без расширения
- 2 — расширение в 2 раза
- 3 — расширение в 3 раза ⋮
- До расширения в 8 раз.
Синтаксис
Аргументы
args— до 8 беззнаковых целых чисел или столбцов указанного выше типа.UInt8/16/32/64range_mask— для расширенного режима маска для каждого аргумента. Маска — это кортеж беззнаковых целых чисел от1до8. Каждое число в маске задаёт величину сжатия диапазона.Tuple(UInt8/16/32/64)
Возвращаемое значение
Возвращает код типа UInt64. UInt64
Примеры
Простой режим
Расширенный режим
Один аргумент
Расширенный вариант с одним аргументом
Использование столбца
sqidDecode
Впервые появилась в версии v24.1
Преобразует sqid обратно в массив чисел.
Синтаксис
Аргументы
sqid— sqid для декодирования.String
Возвращаемое значение
Возвращает массив чисел из sqid. Array(UInt64)
Примеры
Пример использования
sqidEncode
Добавлено в версии v24.1
Преобразует числа в sqid — строку идентификатора, похожую на идентификаторы YouTube.
Синтаксис
Псевдонимы: sqid
Аргументы
n1[, n2, ...]— Произвольное количество чисел.UInt8/16/32/64
Возвращаемое значение
Возвращает хеш-идентификатор String
Примеры
Пример использования
unbin
Появилась в: v21.8
Интерпретирует каждую пару двоичных цифр (в аргументе) как число и преобразует её в байт, представленный этим числом. Функция выполняет операцию, обратную функции bin.
Для числового аргумента unbin() не возвращает значение, обратное bin(). Если нужно преобразовать результат в число, вы можете использовать функции reverse и reinterpretAs<Type>.
Если unbin вызывается из clickhouse-client, двоичные строки отображаются с использованием UTF-8.
Поддерживаются двоичные цифры 0 и 1. Количество двоичных цифр не обязательно должно быть кратно восьми. Если строковый аргумент содержит что-либо, кроме двоичных цифр,
результат неопределён (исключение не генерируется).
Синтаксис
Аргументы
arg— Строка, содержащая произвольное количество двоичных цифр.String
Возвращаемое значение
Возвращает двоичную строку (BLOB). String
Примеры
Базовое использование
Преобразование в число
unhex
Добавлено в: v1.1
Выполняет операцию, обратную функции hex. Интерпретирует каждую пару шестнадцатеричных цифр (в аргументе) как число и
преобразует его в байт, который это число представляет. Возвращаемое значение — бинарная строка (BLOB).
Если вы хотите преобразовать результат в число, вы можете использовать функции reverse и reinterpretAs<Type>.
clickhouse-client интерпретирует строки как UTF-8.
Из-за этого значения, возвращаемые hex, могут отображаться неожиданным образом.
Поддерживает как заглавные, так и строчные буквы A-F.
Количество шестнадцатеричных цифр не обязательно должно быть чётным.
Если оно нечётное, последняя цифра интерпретируется как младшая половина байта в диапазоне 00-0F.
Если строковый аргумент содержит что-либо, кроме шестнадцатеричных цифр, возвращается результат, зависящий от реализации (исключение не выбрасывается).
Для числового аргумента функция unhex() не выполняет обратное преобразование результата hex(N).
Синтаксис
Аргументы
arg— Строка, содержащая произвольное количество шестнадцатеричных цифр.StringилиFixedString
Возвращаемое значение
Возвращает двоичную строку (BLOB). String
Примеры
Базовое использование
Преобразовать в число