Функции кодирования
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 части, разделительного символа, который всегда равен '1', и части данных. Длина строки никогда не превышает 90 символов. Если алгоритм не может сгенерировать корректный адрес из входных данных, возвращается пустая строка. String
Примеры
Bech32m по умолчанию
Алгоритм Bech32
Пользовательский HRP
bin
Введена в: v21.8
Возвращает строку, содержащую двоичное представление аргумента в соответствии со следующей логикой для разных типов:
| Type | Description |
|---|---|
(U)Int* | Выводит двоичные разряды от старшего к младшему (порядок big-endian или «читаемый человеком»). Начинает с первого (самого старшего) ненулевого байта (ведущие нулевые байты опускаются), но всегда выводит восемь разрядов для каждого байта, если старший разряд равен нулю. |
Date and DateTime | Форматируются как соответствующие целые числа (количество дней с начала эпохи Unix для Date и значение UNIX timestamp для DateTime). |
String and FixedString | Все байты просто кодируются как восемь двоичных разрядов. Нулевые байты не опускаются. |
Float* and 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*
Возвращаемое значение
Возвращает массив с позициями единичных битов в двоичном представлении входного значения, упорядоченными по возрастанию. Array(UInt64)
Примеры
Установлен один бит
Все биты установлены
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
Возвращает строку, содержащую шестнадцатеричное представление аргумента в соответствии со следующей логикой для разных типов:
| Тип | Описание |
|---|---|
(U)Int* | Выводит шестнадцатеричные цифры («полубайты», nibbles) от старшего к младшему разряду (порядок big-endian или «читаемый человеком» порядок). Начинает со старшего ненулевого байта (ведущие нулевые байты опускаются), но всегда выводит обе цифры каждого байта, даже если старшая цифра равна нулю. |
Date и DateTime | Форматируются как соответствующие целые числа (количество дней, прошедших с начала эпохи, для Date и значение метки времени Unix для DateTime). |
String и FixedString | Все байты просто кодируются как две шестнадцатеричные цифры. Нулевые байты не опускаются. |
Float* и 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, эта функция имеет два режима работы:
- Простой
- Расширенный
Простой режим
Принимает до двух беззнаковых целых чисел в качестве аргументов и возвращает код типа UInt64.
Расширенный режим
Принимает маску диапазона (кортеж) в качестве первого аргумента и до двух беззнаковых целых чисел в качестве остальных аргументов. Каждое число в маске задаёт количество бит, на которое соответствующий аргумент будет сдвинут влево, фактически масштабируя аргумент внутри его диапазона.
Расширение диапазона может быть полезно, когда требуется получить схожее распределение для
аргументов с сильно различающимися диапазонами (или кардинальностями). Например: «IP-адрес» (0...FFFFFFFF)
и «код страны» (0...FF). Как и при кодировании, количество чисел ограничено максимум 8.
Синтаксис
Аргументы
tuple_size— целое число не более2.UInt8/16/32/64илиTuple(UInt8/16/32/64)code— код типаUInt64.UInt64
Возвращаемое значение
Возвращает кортеж указанного размера. Tuple(UInt64)
Примеры
Простой режим
Один аргумент
Расширенный режим
Использование столбцов
hilbertEncode
Добавлена в версии: v24.6
Вычисляет код кривой Гильберта для списка беззнаковых целых чисел.
Функция имеет два режима работы:
- Простой
- Расширенный
Простой режим
Принимает до двух беззнаковых целых чисел в качестве аргументов и возвращает код типа UInt64.
Расширенный режим
Принимает маску диапазона (Tuple) в качестве первого аргумента и до двух беззнаковых целых чисел в качестве остальных аргументов.
Каждое число в маске задаёт количество бит, на которое соответствующий аргумент будет сдвинут влево, эффективно масштабируя аргумент внутри его диапазона.
Синтаксис
Аргументы
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
Вычисляет кодирование Мортон (Z-curve) для списка беззнаковых целых чисел.
Функция работает в двух режимах:
- Простой
- Расширенный*
Простой режим
Принимает до 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.
Если строковый аргумент содержит что-либо, кроме шестнадцатеричных цифр, возвращается зависящий от реализации результат (исключение не выбрасывается).
Для числового аргумента обратная операция к hex(N) функцией unhex() не выполняется.
Синтаксис
Аргументы
arg— Строка с любым количеством шестнадцатеричных цифр.StringилиFixedString
Возвращаемое значение
Возвращает двоичную строку (BLOB). String
Примеры
Базовое использование
Преобразовать в число