mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-13 09:52:38 +00:00

Alexey Petrunyaka 29e70f5004 In-source and Russian .md UUIDv7 docs synced with English .md docs

2024-04-29 21:04:44 +03:00

26 KiB

Raw Blame History

slug	sidebar_position	sidebar_label
/ru/sql-reference/functions/uuid-functions	53	Функции для работы с UUID

Функции для работы с 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

::::note На апрель 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 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7ThreadMonotonic

Генерирует идентификатор UUID версии 7. Генерируемый UUID состоит из 48-битной временной метки (Unix time в миллисекундах), маркеров версии 7 и варианта 2, монотонно возрастающего счётчика для данной временной метки и случайных данных в указанной ниже последовательности. Для каждой новой временной метки счётчик стартует с нового случайного значения, а для следующих UUIDv7 он увеличивается на единицу. В случае переполнения счётчика временная метка принудительно увеличивается на 1, и счётчик снова стартует со случайного значения. Данная функция является ускоренным аналогом функции generateUUIDv7 за счёт потери гарантии монотонности счётчика при одной и той же метке времени между одновременно исполняемыми разными запросами. Монотонность счётчика гарантируется только в пределах одного треда, исполняющего данную функцию для генерации нескольких UUID.

Синтаксис

generateUUIDv7ThreadMonotonic([x])

Аргументы

x — выражение, возвращающее значение одного из поддерживаемых типов данных. Значение используется, чтобы избежать склейки одинаковых выражений, если функция вызывается несколько раз в одном запросе. Необязательный параметр.

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

Значение типа UUID.

Пример использования

Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUIDv7.

CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog

INSERT INTO t_uuid SELECT generateUUIDv7ThreadMonotonic()

SELECT * FROM t_uuid

┌────────────────────────────────────x─┐
│ 018f05e2-e3b2-70cb-b8be-64b09b626d32 │
└──────────────────────────────────────┘

Пример использования, для генерации нескольких значений в одной строке

SELECT generateUUIDv7ThreadMonotonic(1), generateUUIDv7ThreadMonotonic(7)

┌─generateUUIDv7ThreadMonotonic(1)─────┬─generateUUIDv7ThreadMonotonic(2)─────┐
│ 018f05e1-14ee-7bc5-9906-207153b400b1 │ 018f05e1-14ee-7bc5-9906-2072b8e96758 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7NonMonotonic

Генерирует идентификатор UUID версии 7. Генерируемый 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 находится в статусе черновика и его раскладка по битам может в итоге измениться. ::::

Синтаксис

generateUUIDv7NonMonotonic([x])

Аргументы

x — выражение, возвращающее значение одного из поддерживаемых типов данных. Значение используется, чтобы избежать склейки одинаковых выражений, если функция вызывается несколько раз в одном запросе. Необязательный параметр.

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

Значение типа UUID.

Пример использования

Этот пример демонстрирует, как создать таблицу с UUID-колонкой и добавить в нее сгенерированный UUIDv7.

CREATE TABLE t_uuid (x UUID) ENGINE=TinyLog

INSERT INTO t_uuid SELECT generateUUIDv7NonMonotonic()

SELECT * FROM t_uuid

┌────────────────────────────────────x─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b │
└──────────────────────────────────────┘

Пример использования, для генерации нескольких значений в одной строке

SELECT generateUUIDv7NonMonotonic(1), generateUUIDv7NonMonotonic(7)
┌─generateUUIDv7NonMonotonic(1)────────┬─generateUUIDv7NonMonotonic(2)────────┐
│ 018f05b1-8c2e-7567-a988-48d09606ae8c │ 018f05b1-8c2e-7946-895b-fcd7635da9a0 │
└──────────────────────────────────────┴──────────────────────────────────────┘

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.

26 KiB Raw Blame History Unescape Escape

Функции для работы с UUID

generateUUIDv4

generateUUIDv7

generateUUIDv7ThreadMonotonic

generateUUIDv7NonMonotonic

empty

notEmpty

toUUID (x)

toUUIDOrNull (x)

toUUIDOrZero (x)

UUIDStringToNum

UUIDNumToString

UUIDToNum

UUIDv7ToDateTime

serverUUID()

См. также:

26 KiB

Raw Blame History