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

generateUUIDv4

Генерирует версию 4 UUID.

Синтаксис

Аргументы

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

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

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

Пример

Сначала создайте таблицу со столбцом типа UUID, затем вставьте сгенерированный UUIDv4 в таблицу.

Результат:

Пример с несколькими UUID, сгенерированными за строку

generateUUIDv7

Генерирует версию 7 UUID.

Сгенерированный UUID содержит текущую Unix временную метку в миллисекундах (48 бит), за которой следует версия "7" (4 бита), счетчик (42 бита), чтобы различать UUID в пределах одной миллисекунды (включая поле варианта "2", 2 бита), и случайное поле (32 бита). Для данной временной метки (unix_ts_ms) счетчик начинается с случайного значения и увеличивается на 1 для каждого нового UUID, пока временная метка не изменится. В случае переполнения счетчика поле временной метки увеличивается на 1, а счетчик сбрасывается на новое случайное стартовое значение.

Функция generateUUIDv7 гарантирует, что поле счетчика внутри временной метки увеличивается монотонно при всех вызовах функции в одновременно выполняемых потоках и запросах.

примечание

На апрель 2024 года UUID версии 7 находятся в статусе черновика, и их структура может изменяться в будущем.

Синтаксис

Аргументы

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

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

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

Пример

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

Результат:

Пример с несколькими UUID, сгенерированными за строку

empty

Проверяет, пустой ли входной UUID.

Синтаксис

UUID считается пустым, если он содержит только нули (ноль UUID).

Функция также работает для Массивов и Строк.

Аргументы

• x — UUID. UUID.

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

• Возвращает 1 для пустого UUID или 0 для непустого UUID. UInt8.

Пример

Чтобы сгенерировать значение UUID, ClickHouse предоставляет функцию generateUUIDv4.

Запрос:

Результат:

notEmpty

Проверяет, непустой ли входной UUID.

Синтаксис

UUID считается пустым, если он содержит только нули (ноль UUID).

Функция также работает для Массивов или Строк.

Аргументы

• x — UUID. UUID.

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

• Возвращает 1 для непустого UUID или 0 для пустого UUID. UInt8.

Пример

Чтобы сгенерировать значение UUID, ClickHouse предоставляет функцию generateUUIDv4.

Запрос:

Результат:

toUUID

Превращает значение типа String в UUID.

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

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

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

Результат:

toUUIDOrDefault

Аргументы

• string — Строка из 36 символов или FixedString(36). String.
• default — UUID, который будет использоваться как значение по умолчанию, если первый аргумент не может быть преобразован в тип UUID. UUID.

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

UUID

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

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

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

Первый пример возвращает первый аргумент, преобразованный в тип UUID, так как его можно преобразовать:

Результат:

Этот второй пример возвращает второй аргумент (предоставленный UUID по умолчанию), так как первый аргумент не может быть преобразован в тип UUID:

Результат:

toUUIDOrNull

Принимает аргумент типа String и пытается разобрать его в UUID. Если не удалось, возвращает NULL.

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

Значение типа Nullable(UUID).

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

Результат:

toUUIDOrZero

Принимает аргумент типа String и пытается разобрать его в UUID. Если не удалось, возвращает нулевой UUID.

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

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

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

Результат:

UUIDStringToNum

Принимает string, содержащую 36 символов в формате xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, и возвращает FixedString(16) его двоичного представления, формат которого можно дополнительно указать с помощью variant (по умолчанию Big-endian).

Синтаксис

Аргументы

• string — String из 36 символов или FixedString
• variant — Целое число, представляющее вариант, как указано в RFC4122. 1 = Big-endian (по умолчанию), 2 = Microsoft.

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

FixedString(16)

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

Результат:

Результат:

UUIDNumToString

Принимает binary, содержащий двоичное представление UUID, формат которого можно дополнительно указать с помощью variant (по умолчанию Big-endian), и возвращает строку, содержащую 36 символов в текстовом формате.

Синтаксис

Аргументы

• binary — FixedString(16) в качестве двоичного представления UUID.
• variant — Целое число, представляющее вариант, как указано в RFC4122. 1 = Big-endian (по умолчанию), 2 = Microsoft.

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

Строка.

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

Результат:

Результат:

UUIDToNum

Принимает UUID и возвращает его двоичное представление в виде FixedString(16), формат которого можно дополнительно указать с помощью variant (по умолчанию Big-endian). Эта функция заменяет вызовы двух отдельных функций UUIDStringToNum(toString(uuid)), так что промежуточное преобразование из UUID в строку не требуется для извлечения байтов из UUID.

Синтаксис

Аргументы

• uuid — UUID.
• variant — Целое число, представляющее вариант, как указано в RFC4122. 1 = Big-endian (по умолчанию), 2 = Microsoft.

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

Двоичное представление UUID.

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

Результат:

Результат:

UUIDv7ToDateTime

Возвращает компонент временной метки UUID версии 7.

Синтаксис

Аргументы

• uuid — UUID версии 7.
• timezone — Имя часового пояса для возвращаемого значения (необязательный). String.

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

• Временная метка с миллисекундной точностью. Если UUID не является допустимым UUID версии 7, возвращает 1970-01-01 00:00:00.000. DateTime64(3).

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

Результат:

Результат:

serverUUID

Возвращает случайный UUID, сгенерированный при первом запуске сервера ClickHouse. UUID хранится в файле uuid в директории сервера ClickHouse (например, /var/lib/clickhouse/) и сохраняется между перезагрузками сервера.

Синтаксис

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

• UUID сервера. UUID.

generateSnowflakeID

Генерирует Snowflake ID.

Сгенерированный Snowflake ID содержит текущую Unix временную метку в миллисекундах (41 + 1 старший нулевой бит), за которой следует идентификатор машины (10 бит) и счетчик (12 бит), чтобы различать идентификаторы в пределах одной миллисекунды. Для данной временной метки (unix_ts_ms) счетчик начинается с 0 и увеличивается на 1 для каждого нового Snowflake ID, пока временная метка не изменится. В случае переполнения счетчика поле временной метки увеличивается на 1, а счетчик сбрасывается на 0.

Функция generateSnowflakeID гарантирует, что поле счетчика внутри временной метки увеличивается монотонно при всех вызовах функции в одновременно выполняемых потоках и запросах.

примечание

Сгенерированные Snowflake ID основаны на эпохе UNIX 1970-01-01. Хотя не существует стандарта или рекомендации для эпохи Snowflake ID, реализации в других системах могут использовать другую эпоху, например, Twitter/X (2010-11-04) или Mastodon (2015-01-01).

Синтаксис

Аргументы

• expr — Произвольное выражение, используемое для обхода устранения общих подпроцессов, если функция вызывается несколько раз в запросе. Значение выражения не влияет на возвращаемый Snowflake ID. Необязательный.
• machine_id — Идентификатор машины, используются младшие 10 бит. Int64. Необязательный.

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

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

Пример

Сначала создайте таблицу со столбцом типа UInt64, затем вставьте сгенерированный Snowflake ID в таблицу.

Результат:

Пример с несколькими Snowflake ID, сгенерированными за строку

Пример с выражением и идентификатором машины

snowflakeToDateTime

Deprecated feature

осторожно

Эта функция устарела и может использоваться только если настройка allow_deprecated_snowflake_conversion_functions включена. Функция будет удалена в будущем.

Извлекает компонент временной метки Snowflake ID в формате DateTime.

Синтаксис

Аргументы

• value — Snowflake ID. Int64.
• time_zone — Часовой пояс. Функция разбирает time_string в соответствии с часовым поясом. Необязательный. String.

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

• Компонент временной метки value в качестве значения DateTime.

Пример

Запрос:

Результат:

snowflakeToDateTime64

Deprecated feature

осторожно

Эта функция устарела и может использоваться только если настройка allow_deprecated_snowflake_conversion_functions включена. Функция будет удалена в будущем.

Извлекает компонент временной метки Snowflake ID в формате DateTime64.

Синтаксис

Аргументы

• value — Snowflake ID. Int64.
• time_zone — Часовой пояс. Функция разбирает time_string в соответствии с часовым поясом. Необязательный. String.

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

• Компонент временной метки value в качестве DateTime64 с масштабом = 3, т.е. с миллисекундной точностью.

Пример

Запрос:

Результат:

dateTimeToSnowflake

Deprecated feature

осторожно

Эта функция устарела и может использоваться только если настройка allow_deprecated_snowflake_conversion_functions включена. Функция будет удалена в будущем.

Преобразует значение DateTime в первый Snowflake ID в заданное время.

Синтаксис

Аргументы

• value — Дата с временем. DateTime.

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

• Входное значение преобразуется в тип Int64 как первый Snowflake ID в это время.

Пример

Запрос:

Результат:

dateTime64ToSnowflake

Deprecated feature

осторожно

Эта функция устарела и может использоваться только если настройка allow_deprecated_snowflake_conversion_functions включена. Функция будет удалена в будущем.

Преобразует DateTime64 в первый Snowflake ID в заданное время.

Синтаксис

Аргументы

• value — Дата с временем. DateTime64.

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

• Входное значение преобразуется в тип Int64 как первый Snowflake ID в это время.

Пример

Запрос:

Результат:

snowflakeIDToDateTime

Возвращает компонент временной метки Snowflake ID в качестве значения типа DateTime.

Синтаксис

Аргументы

• value — Snowflake ID. UInt64.
• epoch - Эпоха Snowflake ID в миллисекундах с 1970-01-01. По умолчанию 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. Необязательный. UInt*.
• time_zone — Часовой пояс. Функция разбирает time_string в соответствии с часовым поясом. Необязательный. String.

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

• Компонент временной метки value в качестве значения DateTime.

Пример

Запрос:

Результат:

snowflakeIDToDateTime64

Возвращает компонент временной метки Snowflake ID в качестве значения типа DateTime64.

Синтаксис

Аргументы

• value — Snowflake ID. UInt64.
• epoch - Эпоха Snowflake ID в миллисекундах с 1970-01-01. По умолчанию 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. Необязательный. UInt*.
• time_zone — Часовой пояс. Функция разбирает time_string в соответствии с часовым поясом. Необязательный. String.

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

• Компонент временной метки value в качестве DateTime64 с масштабом = 3, т.е. с миллисекундной точностью.

Пример

Запрос:

Результат:

dateTimeToSnowflakeID

Преобразует значение DateTime в первый Snowflake ID в заданное время.

Синтаксис

Аргументы

• value — Дата с временем. DateTime.
• epoch - Эпоха Snowflake ID в миллисекундах с 1970-01-01. По умолчанию 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. Необязательный. UInt*.

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

• Входное значение преобразуется в UInt64 как первый Snowflake ID в это время.

Пример

Запрос:

Результат:

dateTime64ToSnowflakeID

Преобразует DateTime64 в первый Snowflake ID в заданное время.

Синтаксис

Аргументы

• value — Дата с временем. DateTime64.
• epoch - Эпоха Snowflake ID в миллисекундах с 1970-01-01. По умолчанию 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. Необязательный. UInt*.

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

• Входное значение преобразуется в UInt64 как первый Snowflake ID в это время.

Пример

Запрос:

Результат:

See also

• dictGetUUID