Функции для работы с UUID
generateUUIDv4
Генерирует идентификатор UUID версии 4.
Синтаксис
generateUUIDv4([x])
Аргументы
x— выражение, возвращающее значение одного из поддерживаемых типов данных. Значение используется, чтобы избежать склейки одинаковых выражений, если функция вызывается несколько раз в одном запросе. Необязательный параметр.
Возвращаемое значение
Значение типа UUID.
Пример использования
Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUID.
CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog
INSERT INTO t_uuid SELECT generateUUIDv4()
SELECT * FROM t_uuid
┌────────────────────────────────────x─┐
│ f4bf890f-f9dc-4332-ad5c-0c18e73f28e9 │
└──────────────────────────────────────┘
Пример использования, для генерации нескольких значений в одной строке
SELECT generateUUIDv4(1), generateUUIDv4(2)
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 8abf8c13-7dea-4fdf-af3e-0e18767770e6 │
└──────────────────────────────────────┴──────────────────────────────────────┘
generateUUIDv7
Генерирует идентификатор UUID версии 7. Генерируемый UUID состоит из 48-битной временной метки (Unix time в миллисекундах), маркеров версии 7 и варианта 2, монотонно возрастающего счётчика для данной временной метки и случайных данных в указанной ниже последовательности. Для каждой новой временной метки счётчик стартует с нового случайного значения, а для следующих UUIDv7 он увеличивается на единицу. В случае переполнения счётчика временная метка принудительно увеличивается на 1, и счётчик снова стартует со случайного значения. Монотонность возрастания счётчика для каждой временной метки гарантируется между всеми одновременно работающими функциями generateUUIDv7.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
| unix_ts_ms |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
| unix_ts_ms | ver | counter_high_bits |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|var| counter_low_bits |
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
| rand_b |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
На апрель 2024 года UUIDv7 находится в статусе черновика и его раскладка по битам может в итоге измениться.
Синтаксис
generateUUIDv7([x])
Аргументы
x— выражение, возвращающее значение одного из поддерживаемых типов данных. Значение используется, чтобы избежать склейки одинаковых выражений, если функция вызывается несколько раз в одном запросе. Необязательный параметр.
Возвращаемое значение
Значение типа UUID.
Пример использования
Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUIDv7.
CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog
INSERT INTO t_uuid SELECT generateUUIDv7WithCounter()
SELECT * FROM t_uuid
┌────────────────────────────────────x─┐
│ 018f05c7-56e3-7ac3-93e9-1d93c4218e0e │
└──────────────────────────────────────┘
Пример использования, для генерации нескольких значений в одной строке
SELECT generateUUIDv7(1), generateUUIDv7(2)
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(2)────────────────────┐
│ 018f05c9-4ab8-7b86-b64e-c9f03fbd45d1 │ 018f05c9-4ab8-7b86-b64e-c9f12efb7e16 │
└──────────────────────────────────────┴──────────────────────────────────────┘
empty
Проверяет, является ли входной UUID пустым.
Синтаксис
empty(UUID)
UUID считается пустым, если он содержит все нули (нулевой UUID).
Функция также поддерживает работу с типами Array и String.
Параметры
x— UUID на входе функции. UUID.
Возвращаемое значение
- Возвращает
1для пустого UUID или0— для непустого UUID.
Тип: UInt8.
Пример
Для генерации UUID-значений предназначена функция generateUUIDv4.
Запрос:
SELECT empty(generateUUIDv4());
Ответ:
┌─empty(generateUUIDv4())─┐
│ 0 │
└─────────────────────────┘
notEmpty
Проверяет, является ли входной UUID непустым.
Синтаксис
notEmpty(UUID)
UUID считается пустым, если он содержит все нули (нулевой UUID).
Функция также поддерживает работу с типами Array и String.
Параметры
x— UUID на входе функции. UUID.
Возвращаемое значение
- Возвращает
1для непустого UUID или0— для пустого UUID.
Тип: UInt8.
Пример
Для генерации UUID-значений предназначена функция generateUUIDv4.
Запрос:
SELECT notEmpty(generateUUIDv4());
Результат:
┌─notEmpty(generateUUIDv4())─┐
│ 1 │
└────────────────────────────┘
toUUID (x)
Преобразует значение типа String в тип UUID.
toUUID(String)
Возвращаемое значение
Значение типа UUID.
Пример использования
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
toUUIDOrNull (x)
Принимает строку, и пытается преобразовать в тип UUID. При неудаче возвращает NULL.
toUUIDOrNull(String)
Возвращаемое значение
Значение типа Nullable(UUID).
Пример использования
SELECT toUUIDOrNull('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
┌─uuid─┐
│ ᴺᵁᴸᴸ │
└──────┘
toUUIDOrZero (x)
Принимает строку, и пытается преобразовать в тип UUID. При неудаче возвращает нулевой UUID.
toUUIDOrZero(String)
Возвращаемое значение
Значение типа UUID.
Пример использования
SELECT toUUIDOrZero('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid
┌─────────────────────────────────uuid─┐
│ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┘
UUIDStringToNum
Принимает строку, содержащую 36 символов в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, и возвращает в виде набора байт в FixedString(16).
UUIDStringToNum(String)
Возвращаемое значение
FixedString(16)
Пример использования
SELECT
'612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
UUIDStringToNum(uuid) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
UUIDNumToString
Принимает значение типа FixedString(16). Возвращает строку из 36 символов в текстовом виде.
UUIDNumToString(FixedString(16))
Возвращаемое значение
Значение типа String.
Пример использования
SELECT
'a/<@];!~p{jTj={)' AS bytes,
UUIDNumToString(toFixedString(bytes, 16)) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘
UUIDToNum
Принимает UUID и возвращает в виде набора байт в FixedString(16). Также принимает необязательный второй параметр - вариант представления UUID, по умолчанию 1 - Big-endian (2 означает представление в формате Microsoft). Данная функция заменяет последовательность из двух отдельных функций UUIDStringToNum(toString(uuid)), так что промежуточная конвертация из UUID в String для извлечения набора байт из UUID не требуется.
UUIDToNum(UUID[, variant = 1])
Возвращаемое значение
FixedString(16)
Примеры использования
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
SELECT
toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
UUIDToNum(uuid, 2) AS bytes
┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘
UUIDv7ToDateTime
Принимает UUID версии 7 и извлекает из него временную метку.
UUIDv7ToDateTime(uuid[, timezone])
Параметры
uuid— UUID версии 7.timezone— Часовой пояс для возвращаемого значения (необязательный параметр). String.
Возвращаемое значение
- Временная метка с миллисекундной точностью (1970-01-01 00:00:00.000 в случае UUID не версии 7).
Type: DateTime64(3).
Примеры использования
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│ 2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│ 2024-04-22 08:30:29.048 │
└──────────────────────────────────────────────────────────────────────────────────────┘
serverUUID()
Возвращает случайный и уникальный UUID, который генерируется при первом запуске сервера и сохраняется навсегда. Результат записывается в файл uuid, расположенный в каталоге сервера ClickHouse /var/lib/clickhouse/.
Синтаксис
serverUUID()
Возвращаемое значение
- UUID сервера.
Тип: UUID.