--- slug: /ru/sql-reference/functions/uuid-functions sidebar_position: 53 sidebar_label: "Функции для работы с UUID" --- # Функции для работы с UUID {#funktsii-dlia-raboty-s-uuid} ## generateUUIDv4 {#uuid-function-generate} Генерирует идентификатор [UUID версии 4](https://tools.ietf.org/html/rfc4122#section-4.4). **Синтаксис** ``` sql generateUUIDv4([x]) ``` **Аргументы** - `x` — [выражение](../syntax.md#syntax-expressions), возвращающее значение одного из [поддерживаемых типов данных](../data-types/index.md#data_types). Значение используется, чтобы избежать [склейки одинаковых выражений](index.md#common-subexpression-elimination), если функция вызывается несколько раз в одном запросе. Необязательный параметр. **Возвращаемое значение** Значение типа [UUID](../../sql-reference/functions/uuid-functions.md). **Пример использования** Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUID. ``` sql CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog INSERT INTO t_uuid SELECT generateUUIDv4() SELECT * FROM t_uuid ``` ``` text ┌────────────────────────────────────x─┐ │ f4bf890f-f9dc-4332-ad5c-0c18e73f28e9 │ └──────────────────────────────────────┘ ``` **Пример использования, для генерации нескольких значений в одной строке** ```sql SELECT generateUUIDv4(1), generateUUIDv4(2) ┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐ │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 8abf8c13-7dea-4fdf-af3e-0e18767770e6 │ └──────────────────────────────────────┴──────────────────────────────────────┘ ``` ## generateUUIDv7 {#uuidv7-function-generate} Генерирует идентификатор [UUID версии 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04). Генерируемый 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 | └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘ ``` ::::note На апрель 2024 года UUIDv7 находится в статусе черновика и его раскладка по битам может в итоге измениться. :::: **Синтаксис** ``` sql generateUUIDv7([x]) ``` **Аргументы** - `x` — [выражение](../syntax.md#syntax-expressions), возвращающее значение одного из [поддерживаемых типов данных](../data-types/index.md#data_types). Значение используется, чтобы избежать [склейки одинаковых выражений](index.md#common-subexpression-elimination), если функция вызывается несколько раз в одном запросе. Необязательный параметр. **Возвращаемое значение** Значение типа [UUID](../../sql-reference/functions/uuid-functions.md). **Пример использования** Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUIDv7. ``` sql CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog INSERT INTO t_uuid SELECT generateUUIDv7WithCounter() SELECT * FROM t_uuid ``` ``` text ┌────────────────────────────────────x─┐ │ 018f05c7-56e3-7ac3-93e9-1d93c4218e0e │ └──────────────────────────────────────┘ ``` **Пример использования, для генерации нескольких значений в одной строке** ```sql SELECT generateUUIDv7(1), generateUUIDv7(2) ┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(2)────────────────────┐ │ 018f05c9-4ab8-7b86-b64e-c9f03fbd45d1 │ 018f05c9-4ab8-7b86-b64e-c9f12efb7e16 │ └──────────────────────────────────────┴──────────────────────────────────────┘ ``` ## generateUUIDv7ThreadMonotonic {#uuidv7threadmonotonic-function-generate} Генерирует идентификатор [UUID версии 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04). Генерируемый UUID состоит из 48-битной временной метки (Unix time в миллисекундах), маркеров версии 7 и варианта 2, монотонно возрастающего счётчика для данной временной метки и случайных данных в указанной ниже последовательности. Для каждой новой временной метки счётчик стартует с нового случайного значения, а для следующих UUIDv7 он увеличивается на единицу. В случае переполнения счётчика временная метка принудительно увеличивается на 1, и счётчик снова стартует со случайного значения. Данная функция является ускоренным аналогом функции `generateUUIDv7` за счёт потери гарантии монотонности счётчика при одной и той же метке времени между одновременно исполняемыми разными запросами. Монотонность счётчика гарантируется только в пределах одного треда, исполняющего данную функцию для генерации нескольких UUID. **Синтаксис** ``` sql generateUUIDv7ThreadMonotonic([x]) ``` **Аргументы** - `x` — [выражение](../syntax.md#syntax-expressions), возвращающее значение одного из [поддерживаемых типов данных](../data-types/index.md#data_types). Значение используется, чтобы избежать [склейки одинаковых выражений](index.md#common-subexpression-elimination), если функция вызывается несколько раз в одном запросе. Необязательный параметр. **Возвращаемое значение** Значение типа [UUID](../../sql-reference/functions/uuid-functions.md). **Пример использования** Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUIDv7. ``` sql CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog INSERT INTO t_uuid SELECT generateUUIDv7ThreadMonotonic() SELECT * FROM t_uuid ``` ``` text ┌────────────────────────────────────x─┐ │ 018f05e2-e3b2-70cb-b8be-64b09b626d32 │ └──────────────────────────────────────┘ ``` **Пример использования, для генерации нескольких значений в одной строке** ```sql SELECT generateUUIDv7ThreadMonotonic(1), generateUUIDv7ThreadMonotonic(7) ┌─generateUUIDv7ThreadMonotonic(1)─────┬─generateUUIDv7ThreadMonotonic(2)─────┐ │ 018f05e1-14ee-7bc5-9906-207153b400b1 │ 018f05e1-14ee-7bc5-9906-2072b8e96758 │ └──────────────────────────────────────┴──────────────────────────────────────┘ ``` ## generateUUIDv7NonMonotonic {#uuidv7nonmonotonic-function-generate} Генерирует идентификатор [UUID версии 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04). Генерируемый UUID состоит из 48-битной временной метки (Unix time в миллисекундах), маркеров версии 7 и варианта 2, и случайных данных в следующей последовательности: ``` 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 | rand_a | ├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤ |var| rand_b | ├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤ | rand_b | └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘ ``` ::::note На апрель 2024 года UUIDv7 находится в статусе черновика и его раскладка по битам может в итоге измениться. :::: **Синтаксис** ``` sql generateUUIDv7NonMonotonic([x]) ``` **Аргументы** - `x` — [выражение](../syntax.md#syntax-expressions), возвращающее значение одного из [поддерживаемых типов данных](../data-types/index.md#data_types). Значение используется, чтобы избежать [склейки одинаковых выражений](index.md#common-subexpression-elimination), если функция вызывается несколько раз в одном запросе. Необязательный параметр. **Возвращаемое значение** Значение типа [UUID](../../sql-reference/functions/uuid-functions.md). **Пример использования** Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUIDv7. ``` sql CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog INSERT INTO t_uuid SELECT generateUUIDv7NonMonotonic() SELECT * FROM t_uuid ``` ``` text ┌────────────────────────────────────x─┐ │ 018f05af-f4a8-778f-beee-1bedbc95c93b │ └──────────────────────────────────────┘ ``` **Пример использования, для генерации нескольких значений в одной строке** ```sql SELECT generateUUIDv7NonMonotonic(1), generateUUIDv7NonMonotonic(7) ┌─generateUUIDv7NonMonotonic(1)────────┬─generateUUIDv7NonMonotonic(2)────────┐ │ 018f05b1-8c2e-7567-a988-48d09606ae8c │ 018f05b1-8c2e-7946-895b-fcd7635da9a0 │ └──────────────────────────────────────┴──────────────────────────────────────┘ ``` ## empty {#empty} Проверяет, является ли входной UUID пустым. **Синтаксис** ```sql empty(UUID) ``` UUID считается пустым, если он содержит все нули (нулевой UUID). Функция также поддерживает работу с типами [Array](array-functions.md#function-empty) и [String](string-functions.md#empty). **Параметры** - `x` — UUID на входе функции. [UUID](../data-types/uuid.md). **Возвращаемое значение** - Возвращает `1` для пустого UUID или `0` — для непустого UUID. Тип: [UInt8](../data-types/int-uint.md). **Пример** Для генерации UUID-значений предназначена функция [generateUUIDv4](#uuid-function-generate). Запрос: ```sql SELECT empty(generateUUIDv4()); ``` Ответ: ```text ┌─empty(generateUUIDv4())─┐ │ 0 │ └─────────────────────────┘ ``` ## notEmpty {#notempty} Проверяет, является ли входной UUID непустым. **Синтаксис** ```sql notEmpty(UUID) ``` UUID считается пустым, если он содержит все нули (нулевой UUID). Функция также поддерживает работу с типами [Array](array-functions.md#function-notempty) и [String](string-functions.md#function-notempty). **Параметры** - `x` — UUID на входе функции. [UUID](../data-types/uuid.md). **Возвращаемое значение** - Возвращает `1` для непустого UUID или `0` — для пустого UUID. Тип: [UInt8](../data-types/int-uint.md). **Пример** Для генерации UUID-значений предназначена функция [generateUUIDv4](#uuid-function-generate). Запрос: ```sql SELECT notEmpty(generateUUIDv4()); ``` Результат: ```text ┌─notEmpty(generateUUIDv4())─┐ │ 1 │ └────────────────────────────┘ ``` ## toUUID (x) {#touuid-x} Преобразует значение типа String в тип UUID. ``` sql toUUID(String) ``` **Возвращаемое значение** Значение типа UUID. **Пример использования** ``` sql SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid ``` ``` text ┌─────────────────────────────────uuid─┐ │ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │ └──────────────────────────────────────┘ ``` ## toUUIDOrNull (x) {#touuidornull-x} Принимает строку, и пытается преобразовать в тип UUID. При неудаче возвращает NULL. ``` sql toUUIDOrNull(String) ``` **Возвращаемое значение** Значение типа Nullable(UUID). **Пример использования** ``` sql SELECT toUUIDOrNull('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid ``` ``` text ┌─uuid─┐ │ ᴺᵁᴸᴸ │ └──────┘ ``` ## toUUIDOrZero (x) {#touuidorzero-x} Принимает строку, и пытается преобразовать в тип UUID. При неудаче возвращает нулевой UUID. ``` sql toUUIDOrZero(String) ``` **Возвращаемое значение** Значение типа UUID. **Пример использования** ``` sql SELECT toUUIDOrZero('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid ``` ``` text ┌─────────────────────────────────uuid─┐ │ 00000000-0000-0000-0000-000000000000 │ └──────────────────────────────────────┘ ``` ## UUIDStringToNum {#uuidstringtonum} Принимает строку, содержащую 36 символов в формате `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, и возвращает в виде набора байт в [FixedString(16)](../../sql-reference/functions/uuid-functions.md). ``` sql UUIDStringToNum(String) ``` **Возвращаемое значение** FixedString(16) **Пример использования** ``` sql SELECT '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid, UUIDStringToNum(uuid) AS bytes ``` ``` text ┌─uuid─────────────────────────────────┬─bytes────────────┐ │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │ └──────────────────────────────────────┴──────────────────┘ ``` ## UUIDNumToString {#uuidnumtostring} Принимает значение типа [FixedString(16)](../../sql-reference/functions/uuid-functions.md). Возвращает строку из 36 символов в текстовом виде. ``` sql UUIDNumToString(FixedString(16)) ``` **Возвращаемое значение** Значение типа String. **Пример использования** ``` sql SELECT 'a/<@];!~p{jTj={)' AS bytes, UUIDNumToString(toFixedString(bytes, 16)) AS uuid ``` ``` text ┌─bytes────────────┬─uuid─────────────────────────────────┐ │ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ └──────────────────┴──────────────────────────────────────┘ ``` ## UUIDToNum {#uuidtonum} Принимает UUID и возвращает в виде набора байт в [FixedString(16)](../../sql-reference/functions/uuid-functions.md). Также принимает необязательный второй параметр - вариант представления UUID, по умолчанию 1 - `Big-endian` (2 означает представление в формате `Microsoft`). Данная функция заменяет последовательность из двух отдельных функций `UUIDStringToNum(toString(uuid))`, так что промежуточная конвертация из UUID в String для извлечения набора байт из UUID не требуется. ``` sql UUIDToNum(UUID[, variant = 1]) ``` **Возвращаемое значение** FixedString(16) **Примеры использования** ``` sql SELECT toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid, UUIDToNum(uuid) AS bytes ``` ``` text ┌─uuid─────────────────────────────────┬─bytes────────────┐ │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │ └──────────────────────────────────────┴──────────────────┘ ``` ``` sql SELECT toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid, UUIDToNum(uuid, 2) AS bytes ``` ```text ┌─uuid─────────────────────────────────┬─bytes────────────┐ │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @