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

char

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

Синтаксис

char(number_1, [number_2, ..., number_n]);

Аргументы

• number_1, number_2, ..., number_n — Числовые аргументы, интерпретируемые как целые числа. Типы: Int, Float.

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

• строка заданных байтов. String.

Пример

Запрос:

SELECT char(104.1, 101, 108.9, 108.9, 111) AS hello;

Результат:

┌─hello─┐
│ hello │
└───────┘

Вы можете сконструировать строку произвольной кодировки, передавая соответствующие байты. Вот пример для UTF-8:

Запрос:

SELECT char(0xD0, 0xBF, 0xD1, 0x80, 0xD0, 0xB8, 0xD0, 0xB2, 0xD0, 0xB5, 0xD1, 0x82) AS hello;

Результат:

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

Запрос:

SELECT char(0xE4, 0xBD, 0xA0, 0xE5, 0xA5, 0xBD) AS hello;

Результат:

┌─hello─┐
│ 你好  │
└───────┘

hex

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

Псевдоним: HEX.

Синтаксис

hex(arg)

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

Для целочисленных аргументов она выводит шестнадцатеричные цифры ("нибблы") от наиболее значительного к наименее значительному (big-endian или "читаемый человеком" порядок). Начинает с наиболее значимого ненулевого байта (ведущие нулевые байты опускаются), но всегда выводит обе цифры каждого байта, даже если ведущая цифра нулевая.

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

Для String и FixedString все байты просто кодируются как две шестнадцатеричные цифры. Нулевые байты не опускаются.

Значения Float и Decimal типов кодируются как их представление в памяти. Так как мы поддерживаем архитектуру little-endian, они кодируются в little-endian. Нулевые ведущие/окончательные байты не опускаются.

Значения типа UUID кодируются в виде строки в порядке big-endian.

Аргументы

• arg — Значение, которое необходимо преобразовать в шестнадцатеричное. Типы: String, UInt, Float, Decimal, Date или DateTime.

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

• Строка с шестнадцатеричным представлением аргумента. String.

Примеры

Запрос:

SELECT hex(1);

Результат:

01

Запрос:

SELECT hex(toFloat32(number)) AS hex_presentation FROM numbers(15, 2);

Результат:

┌─hex_presentation─┐
│ 00007041         │
│ 00008041         │
└──────────────────┘

Запрос:

SELECT hex(toFloat64(number)) AS hex_presentation FROM numbers(15, 2);

Результат:

┌─hex_presentation─┐
│ 0000000000002E40 │
│ 0000000000003040 │
└──────────────────┘

Запрос:

SELECT lower(hex(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0'))) as uuid_hex

Результат:

┌─uuid_hex─────────────────────────┐
│ 61f0c4045cb311e7907ba6006ad3dba0 │
└──────────────────────────────────┘

unhex

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

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

примечание

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

Псевдоним: UNHEX.

Синтаксис

unhex(arg)

Аргументы

• arg — Строка, содержащая любое количество шестнадцатеричных цифр. String, FixedString.

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

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

• Бинарная строка (BLOB). String.

Пример

Запрос:

SELECT unhex('303132'), UNHEX('4D7953514C');

Результат:

┌─unhex('303132')─┬─unhex('4D7953514C')─┐
│ 012             │ MySQL               │
└─────────────────┴─────────────────────┘

Запрос:

SELECT reinterpretAsUInt64(reverse(unhex('FFF'))) AS num;

Результат:

┌──num─┐
│ 4095 │
└──────┘

bin

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

Синтаксис

bin(arg)

Псевдоним: BIN.

Для целочисленных аргументов она выводит двоичные цифры от наиболее значительного к наименее значительному (big-endian или "читаемый человеком" порядок). Начинает с наиболее значимого ненулевого байта (ведущие нулевые байты опускаются), но всегда выводит восемь цифр каждого байта, даже если ведущая цифра нулевая.

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

Для String и FixedString все байты просто кодируются как восемь двоичных чисел. Нулевые байты не опускаются.

Значения типов Float и Decimal кодируются как их представление в памяти. Так как мы поддерживаем архитектуру little-endian, они кодируются в little-endian. Нулевые ведущие/окончательные байты не опускаются.

Значения типа UUID кодируются как строка в порядке big-endian.

Аргументы

• arg — Значение, которое необходимо преобразовать в двоичное. String, FixedString, UInt, Float, Decimal, Date или DateTime.

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

• Строка с двоичным представлением аргумента. String.

Примеры

Запрос:

SELECT bin(14);

Результат:

┌─bin(14)──┐
│ 00001110 │
└──────────┘

Запрос:

SELECT bin(toFloat32(number)) AS bin_presentation FROM numbers(15, 2);

Результат:

┌─bin_presentation─────────────────┐
│ 00000000000000000111000001000001 │
│ 00000000000000001000000001000001 │
└──────────────────────────────────┘

Запрос:

SELECT bin(toFloat64(number)) AS bin_presentation FROM numbers(15, 2);

Результат:

┌─bin_presentation─────────────────────────────────────────────────┐
│ 0000000000000000000000000000000000000000000000000010111001000000 │
│ 0000000000000000000000000000000000000000000000000011000001000000 │
└──────────────────────────────────────────────────────────────────┘

Запрос:

SELECT bin(toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0')) as bin_uuid

Результат:

┌─bin_uuid─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 01100001111100001100010000000100010111001011001100010001111001111001000001111011101001100000000001101010110100111101101110100000 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

unbin

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

Синтаксис

unbin(arg)

Псевдоним: UNBIN.

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

примечание

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

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

Аргументы

• arg — Строка, содержащая любое количество двоичных цифр. String.

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

• Бинарная строка (BLOB). String.

Примеры

Запрос:

SELECT UNBIN('001100000011000100110010'), UNBIN('0100110101111001010100110101000101001100');

Результат:

┌─unbin('001100000011000100110010')─┬─unbin('0100110101111001010100110101000101001100')─┐
│ 012                               │ MySQL                                             │
└───────────────────────────────────┴───────────────────────────────────────────────────┘

Запрос:

SELECT reinterpretAsUInt64(reverse(unbin('1110'))) AS num;

Результат:

┌─num─┐
│  14 │
└─────┘

bitmaskToList(num)

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

bitmaskToArray(num)

Принимает целое число. Возвращает массив чисел типа UInt64, содержащий список степеней двух, которые в сумме дают исходное число. Числа в массиве расположены в порядке возрастания.

bitPositionsToArray(num)

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

Синтаксис

bitPositionsToArray(arg)

Аргументы

• arg — Целое значение. Int/UInt.

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

• Массив, содержащий список позиций битов, равных 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] │
└───────────────────┘

mortonEncode

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

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

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

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

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

Синтаксис

mortonEncode(args)

Параметры

• args: до 8 неотрицательных целых чисел или колонок указанного типа.

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

• Код UInt64. UInt64

Пример

Запрос:

SELECT mortonEncode(1, 2, 3);

Результат:

53

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

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

Каждое число в маске настраивает количество расширения диапазона:
1 - без расширения
2 - 2x расширение
3 - 3x расширение
...
До 8x расширения.

Синтаксис

mortonEncode(range_mask, args)

Параметры

• range_mask: 1-8.
• args: до 8 неотрицательных целых чисел или колонок указанного типа.

Примечание: при использовании колонок для args предоставленная кортежная маска по-прежнему должна быть константой.

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

• Код UInt64. UInt64

Пример

Расширение диапазона может быть полезным, когда вам нужно подобное распределение для аргументов с сильно различающимися диапазонами (или кардинальностью). Например: 'IP Address' (0...FFFFFFFF) и 'Country code' (0...FF).

Запрос:

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 SETTINGS index_granularity = 8192, index_granularity_bytes = '10Mi';
insert into morton_numbers (*) values(1,2,3,4,5,6,7,8);

Используйте имена колонок вместо констант в качестве аргументов для mortonEncode.

Запрос:

SELECT mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8) FROM morton_numbers;

Результат:

2155374165

детали реализации

Пожалуйста, обратите внимание, что вы можете вместить лишь столько битов информации в код Мортона, сколько может содержать UInt64. Два аргумента будут иметь диапазон максимум 2^32 (64/2) каждый, три аргумента — диапазон максимум 2^21 (64/3) каждый и так далее. Все переполнения будут обрезаны до нуля.

mortonDecode

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

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

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

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

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

Синтаксис

mortonDecode(tuple_size, code)

Параметры

• tuple_size: целое значение не более 8.
• code: UInt64 код.

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

• tuple указанного размера. UInt64

Пример

Запрос:

SELECT mortonDecode(3, 53);

Результат:

["1","2","3"]

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

Принимает маску диапазона (кортеж) в качестве первого аргумента и код во втором аргументе. Каждое число в маске настраивает количество сжатия диапазона:
1 - без сжатия
2 - 2x сжатие
3 - 3x сжатие
...
До 8x сжатия.

Расширение диапазона может быть полезным, когда вам нужно подобное распределение для аргументов с сильно различающимися диапазонами (или кардинальностью). Например: 'IP Address' (0...FFFFFFFF) и 'Country code' (0...FF). Как и в функции кодирования, это ограничено максимум 8 числами.

Пример

Код Мортона для одного аргумента всегда будет соответствовать самому аргументу (в качестве кортежа).

Запрос:

SELECT mortonDecode(1, 1);

Результат:

["1"]

Пример

Один аргумент с кортежем, указывающим сдвиги битов, будет сдвинут вправо соответственно.

Запрос:

SELECT mortonDecode(tuple(2), 32768);

Результат:

["128"]

Пример

Функция принимает колонку кодов в качестве второго аргумента:

Сначала создайте таблицу и вставьте некоторые данные.

Запрос:

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 SETTINGS index_granularity = 8192, index_granularity_bytes = '10Mi';
insert into morton_numbers (*) values(1,2,3,4,5,6,7,8);

Используйте имена колонок вместо констант в качестве аргументов для mortonDecode.

Запрос:

select untuple(mortonDecode(8, mortonEncode(n1, n2, n3, n4, n5, n6, n7, n8))) from morton_numbers;

Результат:

1    2    3    4    5    6    7    8

hilbertEncode

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

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

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

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

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

Синтаксис

hilbertEncode(args)

Параметры

• args: до 2 неотрицательных целых чисел или колонок указанного типа.

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

• Код UInt64

Тип: UInt64

Пример

Запрос:

SELECT hilbertEncode(3, 4);

Результат:

31

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

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

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

Синтаксис

hilbertEncode(range_mask, args)

Параметры

• range_mask: (tuple)
• args: до 2 неотрицательных целых чисел или колонок указанного типа.

Примечание: при использовании колонок для args предоставленная кортежная маска по-прежнему должна быть константой.

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

• Код UInt64

Тип: UInt64

Пример

Расширение диапазона может быть полезным, когда вам нужно подобное распределение для аргументов с сильно различающимися диапазонами (или кардинальностью). Например: 'IP Address' (0...FFFFFFFF) и 'Country code' (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 SETTINGS index_granularity = 8192, index_granularity_bytes = '10Mi';
insert into hilbert_numbers (*) values(1,2);

Используйте имена колонок вместо констант в качестве аргументов для hilbertEncode.

Запрос:

SELECT hilbertEncode(n1, n2) FROM hilbert_numbers;

Результат:

13

детали реализации

Пожалуйста, обратите внимание, что вы можете вместить лишь столько битов информации в код Хилберта, сколько может содержать UInt64. Два аргумента будут иметь диапазон максимум 2^32 (64/2) каждый. Все переполнения будут обрезаны до нуля.

hilbertDecode

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

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

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

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

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

Синтаксис

hilbertDecode(tuple_size, code)

Параметры

• tuple_size: целое значение не более 2.
• code: UInt64 код.

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

• tuple указанного размера.

Тип: UInt64

Пример

Запрос:

SELECT hilbertDecode(2, 31);

Результат:

["3", "4"]

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

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

Расширение диапазона может быть полезным, когда вам нужно подобное распределение для аргументов с сильно различающимися диапазонами (или кардинальностью), как, например, 'IP Address' (0...FFFFFFFF) и 'Country code' (0...FF). Как и в функции кодирования, это ограничено максимум 8 числами.

Пример

Код Хилберта для одного аргумента всегда будет соответствовать самому аргументу (в качестве кортежа).

Запрос:

SELECT hilbertDecode(1, 1);

Результат:

["1"]

Пример

Единственный аргумент с кортежем, указывающим сдвиги битов, будет сдвинут вправо соответственно.

Запрос:

SELECT hilbertDecode(tuple(2), 32768);

Результат:

["128"]

Пример

Функция принимает колонку кодов в качестве второго аргумента:

Сначала создайте таблицу и вставьте некоторые данные.

Запрос:

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

Используйте имена колонок вместо констант в качестве аргументов для hilbertDecode.

Запрос:

select untuple(hilbertDecode(2, hilbertEncode(n1, n2))) from hilbert_numbers;

Результат:

1    2