Перейти к основному содержанию
Перейти к основному содержанию

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

Генерация UUIDv7​

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

 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Генерация Snowflake ID​

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

Примечание

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

 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
├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|0|                         timestamp                           |
├─┼                 ┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
|                   |     machine_id    |    machine_seq_num    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

generateUUIDv4​

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

Синтаксис

generateUUIDv4([expr])

Аргументы

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

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

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

Пример

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

CREATE TABLE tab (uuid UUID) ENGINE = Memory;

INSERT INTO tab SELECT generateUUIDv4();

SELECT * FROM tab;

Результат:

┌─────────────────────────────────uuid─┐
│ f4bf890f-f9dc-4332-ad5c-0c18e73f28e9 │
└──────────────────────────────────────┘

Пример, в котором для каждой строки генерируется несколько UUID

SELECT generateUUIDv4(1), generateUUIDv4(2);

┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 8abf8c13-7dea-4fdf-af3e-0e18767770e6 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7​

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

См. раздел "Генерация UUIDv7" для подробностей о структуре UUID, управлении счётчиком и гарантиях при конкурентном доступе.

Примечание

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

Синтаксис

generateUUIDv7([expr])

Аргументы

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

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

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

Пример

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

CREATE TABLE tab (uuid UUID) ENGINE = Memory;

INSERT INTO tab SELECT generateUUIDv7();

SELECT * FROM tab;

Результат:

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

Пример с несколькими UUID, генерируемыми для каждой строки

SELECT generateUUIDv7(1), generateUUIDv7(2);

┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(2)────────────────────┐
│ 018f05c9-4ab8-7b86-b64e-c9f03fbd45d1 │ 018f05c9-4ab8-7b86-b64e-c9f12efb7e16 │
└──────────────────────────────────────┴──────────────────────────────────────┘

dateTimeToUUIDv7​

Преобразует значение DateTime в UUIDv7 на заданный момент времени.

См. раздел «UUIDv7 generation» для подробностей о структуре UUID, управлении счётчиком и гарантиях корректной работы при конкурентном доступе.

Примечание

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

Синтаксис

dateTimeToUUIDv7(value)

Аргументы

  • value — Дата и время. DateTime.

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

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

Пример

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));

Результат:

┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘

Пример с несколькими UUID для одной и той же временной метки

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));

Результат

   ┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
1. │ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
   └──────────────────────────────────────┘

   ┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
1. │ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
   └──────────────────────────────────────┘

Функция гарантирует, что несколько вызовов с одинаковым значением временной метки генерируют уникальные, монотонно возрастающие UUID.

empty​

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

Синтаксис

empty(UUID)

UUID считается пустым, если он состоит полностью из нулей (нулевой UUID).

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

Аргументы

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

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

Пример

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

Запрос:

SELECT empty(generateUUIDv4());

Результат:

┌─empty(generateUUIDv4())─┐
│                       0 │
└─────────────────────────┘

notEmpty​

Проверяет, что переданный UUID не пустой.

Синтаксис

notEmpty(UUID)

UUID считается пустым, если он состоит полностью из нулей (нулевой UUID).

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

Аргументы

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

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

Пример

Для генерации значения UUID в ClickHouse предусмотрена функция generateUUIDv4.

Запрос:

SELECT notEmpty(generateUUIDv4());

Результат:

┌─notEmpty(generateUUIDv4())─┐
│                          1 │
└────────────────────────────┘

toUUID​

Преобразует значение типа String в значение типа UUID.

toUUID(string)

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

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

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

SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid

Результат:

┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘

toUUIDOrDefault​

Аргументы

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

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

UUID

toUUIDOrDefault(string, default)

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

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

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

В этом первом примере возвращается первый аргумент, преобразованный к типу UUID, так как его можно привести к этому типу:

SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', cast('59f0c404-5cb3-11e7-907b-a6006ad3dba0' AS UUID));

Результат:

┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', CAST('59f0c404-5cb3-11e7-907b-a6006ad3dba0', 'UUID'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

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

SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', cast('59f0c404-5cb3-11e7-907b-a6006ad3dba0' AS UUID));

Результат:

┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', CAST('59f0c404-5cb3-11e7-907b-a6006ad3dba0', 'UUID'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                               │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

toUUIDOrNull​

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

toUUIDOrNull(string)

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

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

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

SELECT toUUIDOrNull('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid

Результат:

┌─uuid─┐
│ ᴺᵁᴸᴸ │
└──────┘

toUUIDOrZero​

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

toUUIDOrZero(string)

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

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

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

SELECT toUUIDOrZero('61f0c404-5cb3-11e7-907b-a6006ad3dba0T') AS uuid

Результат:

┌─────────────────────────────────uuid─┐
│ 00000000-0000-0000-0000-000000000000 │
└──────────────────────────────────────┘

UUIDStringToNum​

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

Синтаксис

UUIDStringToNum(string[, variant = 1])

Аргументы

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

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

FixedString(16)

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

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes

Результат:

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes

Результат:

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

UUIDNumToString​

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

Синтаксис

UUIDNumToString(binary[, variant = 1])

Аргументы

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

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

Строка.

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

SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid

Результат:

┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid

Результат:

┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

UUIDToNum​

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

Синтаксис

UUIDToNum(uuid[, variant = 1])

Аргументы

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

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

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

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

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, возвращается 1970-01-01 00:00:00.000. 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, сгенерированный при первом запуске сервера ClickHouse. UUID хранится в файле uuid в каталоге сервера ClickHouse (например, /var/lib/clickhouse/) и сохраняется между перезапусками сервера.

Синтаксис

serverUUID()

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

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

generateSnowflakeID​

Генерирует Snowflake ID. Эта функция гарантирует, что поле счётчика внутри метки времени монотонно увеличивается при всех вызовах функции в одновременно выполняющихся потоках и запросах.

См. раздел "Генерация Snowflake ID" для подробных сведений о реализации.

Синтаксис

generateSnowflakeID([expr, [machine_id]])

Аргументы

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

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

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

Пример

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

CREATE TABLE tab (id UInt64) ENGINE = Memory;

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;

Результат:

┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘

Пример с несколькими Snowflake ID, создаваемыми для каждой строки

SELECT generateSnowflakeID(1), generateSnowflakeID(2);

┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘

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

SELECT generateSnowflakeID('expr', 1);

┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘

snowflakeToDateTime​

Deprecated feature
Примечание

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

Вместо неё используйте функцию snowflakeIDToDateTime.

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

Синтаксис

snowflakeToDateTime(value[, time_zone])

Аргументы

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

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

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

Пример

Запрос:

SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');

Результат:


┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘

snowflakeToDateTime64​

Deprecated feature
Примечание

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

Используйте вместо неё функцию snowflakeIDToDateTime64.

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

Синтаксис

snowflakeToDateTime64(value[, time_zone])

Аргументы

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

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

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

Пример

Запрос:

SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');

Результат:


┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘

dateTimeToSnowflake​

Deprecated feature
Примечание

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

Пожалуйста, используйте вместо неё функцию dateTimeToSnowflakeID.

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

Синтаксис

dateTimeToSnowflake(value)

Аргументы

  • value — дата и время. DateTime.

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

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

Пример

Запрос:

WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);

Результат:

┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘

dateTime64ToSnowflake​

Deprecated feature
Примечание

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

Используйте вместо неё функцию dateTime64ToSnowflakeID.

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

Синтаксис

dateTime64ToSnowflake(value)

Аргументы

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

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

Пример

Запрос:

WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);

Результат:

┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘

snowflakeIDToDateTime​

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

Синтаксис

snowflakeIDToDateTime(value[, epoch[, time_zone]])

Аргументы

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

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

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

Пример

Запрос:

SELECT snowflakeIDToDateTime(7204436857747984384) AS res

Результат:

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeIDToDateTime64​

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

Синтаксис

snowflakeIDToDateTime64(value[, epoch[, time_zone]])

Аргументы

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

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

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

Пример

Запрос:

SELECT snowflakeIDToDateTime64(7204436857747984384) AS res

Результат:

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

dateTimeToSnowflakeID​

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

Синтаксис

dateTimeToSnowflakeID(value[, epoch])

Аргументы

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

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

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

Пример

Запрос:

SELECT toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt, dateTimeToSnowflakeID(dt) AS res;

Результат:

┌──────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56 │ 6832626392367104000 │
└─────────────────────┴─────────────────────┘

dateTime64ToSnowflakeID​

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

Синтаксис

dateTime64ToSnowflakeID(value[, epoch])

Аргументы

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

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

  • Входное значение, преобразованное в UInt64 как значение первого Snowflake ID для этого момента времени.

Пример

Запрос:

SELECT toDateTime('2021-08-15 18:57:56.493', 3, 'Asia/Shanghai') AS dt, dateTime64ToSnowflakeID(dt) AS res;

Результат:

┌──────────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56.493 │ 6832626394434895872 │
└─────────────────────────┴─────────────────────┘

См. также​

UUIDNumToString​

Впервые представлена в версии v1.1

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

Синтаксис

UUIDNumToString(binary[, variant])

Аргументы

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

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

Возвращает UUID в виде строки. String

Примеры

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

SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid

┌─bytes────────────┬─uuid─────────────────────────────────┐
│ a/<@];!~p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

Вариант от Microsoft

SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid

┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

UUIDStringToNum​

Появилась в: v1.1

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

Синтаксис

UUIDStringToNum(string[, variant = 1])

Аргументы

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

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

Возвращает двоичное представление 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={) │
└──────────────────────────────────────┴──────────────────┘

Вариант Microsoft

SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes

┌─uuid─────────────────────────────────┬─bytes────────────┐
│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ @</a;]~!p{jTj={) │
└──────────────────────────────────────┴──────────────────┘

UUIDToNum​

Введена в версии v24.5

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

Синтаксис

UUIDToNum(uuid[, variant = 1])

Аргументы

  • uuid — UUID. String или FixedString
  • variant — вариант в соответствии с RFC4122. 1 = Big-endian (по умолчанию), 2 = Microsoft. (U)Int*

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

Возвращает двоичное представление UUID. 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={) │
└──────────────────────────────────────┴──────────────────┘

Вариант от Microsoft

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​

Появилась в версии: v24.5

Возвращает временную составляющую (timestamp) UUID версии 7.

Синтаксис

UUIDv7ToDateTime(uuid[, timezone])

Аргументы

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

Возвращает метку времени с точностью до миллисекунд. Если UUID не является корректным UUID версии 7, возвращает 1970-01-01 00:00:00.000. 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 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘

dateTime64ToSnowflake​

Добавлена в: v21.10

Deprecated feature
Примечание

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

Используйте вместо неё функцию dateTime64ToSnowflakeID.

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

Синтаксис

dateTime64ToSnowflake(value)

Аргументы

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

Возвращает входное значение, преобразованное в первый идентификатор Snowflake для этого момента времени. Int64

Примеры

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

WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);

┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘

dateTime64ToSnowflakeID​

Добавлена в версии: v24.6

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

См. раздел "Генерация идентификаторов Snowflake" для подробностей реализации.

Синтаксис

dateTime64ToSnowflakeID(value[, epoch])

Аргументы

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

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

Возвращает входное значение в виде первого Snowflake ID для этого момента времени. UInt64

Примеры

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

SELECT toDateTime64('2025-08-15 18:57:56.493', 3, 'Asia/Shanghai') AS dt, dateTime64ToSnowflakeID(dt) AS res;

┌──────────────────────dt─┬─────────────────res─┐
│ 2025-08-15 18:57:56.493 │ 7362075066076495872 │
└─────────────────────────┴─────────────────────┘

dateTimeToSnowflake​

Добавлена в: v21.10

Deprecated feature
Примечание

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

Используйте вместо неё функцию dateTimeToSnowflakeID.

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

Синтаксис

dateTimeToSnowflake(value)

Аргументы

  • value — дата и время. DateTime

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

Возвращает первый идентификатор Snowflake для этого момента времени. Int64

Примеры

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

WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);

┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘

dateTimeToSnowflakeID​

Добавлена в версии: v24.6

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

Синтаксис

dateTimeToSnowflakeID(value[, epoch])

Аргументы

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

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

Возвращает первое возможное значение Snowflake ID для указанного момента времени. UInt64

Примеры

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

SELECT toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt, dateTimeToSnowflakeID(dt) AS res;

┌──────────────────dt─┬─────────────────res─┐
│ 2021-08-15 18:57:56 │ 6832626392367104000 │
└─────────────────────┴─────────────────────┘

dateTimeToUUIDv7​

Добавлена в версии: v25.9

Преобразует значение DateTime в UUIDv7 в указанное время.

См. раздел «UUIDv7 generation» для подробностей о структуре UUID, управлении счётчиком и гарантиях при параллельном использовании.

Примечание

По состоянию на сентябрь 2025 года UUID версии 7 находятся в статусе черновика, и их структура может измениться в будущем.

Синтаксис

dateTimeToUUIDv7(value)

Аргументы

  • value — Дата и время. DateTime

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

Возвращает UUIDv7. UUID

Примеры

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

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));

┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘

несколько UUID для одной и той же метки времени

SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));

┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘

generateSnowflakeID​

Появилась в версии v24.6

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

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

См. раздел «Генерация Snowflake ID» для получения подробностей реализации.

Синтаксис

generateSnowflakeID([expr, [machine_id]])

Аргументы

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

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

Возвращает Snowflake ID. UInt64

Примеры

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

CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;

┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘

Несколько идентификаторов Snowflake, генерируемых для одной строки

SELECT generateSnowflakeID(1), generateSnowflakeID(2);

┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘

С выражением и идентификатором хоста

SELECT generateSnowflakeID('expr', 1);

┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘

generateUUIDv4​

Впервые появилась в версии v1.1

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

Синтаксис

generateUUIDv4([expr])

Аргументы

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

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

Возвращает UUIDv4. UUID

Примеры

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

SELECT generateUUIDv4(number) FROM numbers(3);

┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘

Устранение общих подвыражений

SELECT generateUUIDv4(1), generateUUIDv4(1);

┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

generateUUIDv7​

Добавлено в: v24.5

Генерирует идентификатор версии 7 UUID.

См. раздел «Генерация UUIDv7» для подробностей о структуре UUID, управлении счётчиком и гарантиях при конкурентном доступе.

Примечание

По состоянию на сентябрь 2025 года UUID версии 7 имеют статус черновика, и их структура может измениться в будущем.

Синтаксис

generateUUIDv7([expr])

Аргументы

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

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

Возвращает UUIDv7. UUID

Примеры

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

SELECT generateUUIDv7(number) FROM numbers(3);

┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘

Устранение общих подвыражений

SELECT generateUUIDv7(1), generateUUIDv7(1);

┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘

readWKTLineString​

Добавлена в: v

Разбирает представление геометрии LineString в формате Well-Known Text (WKT) и возвращает его во внутреннем формате ClickHouse.

Синтаксис

readWKTLineString(wkt_string)

Аргументы

  • wkt_string — входная строка WKT, представляющая геометрию типа LineString. String

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

Функция возвращает внутреннее представление геометрии типа LineString в ClickHouse.

Примеры

Первый вызов

SELECT readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)');

┌─readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)')─┐
│ [(1,1),(2,2),(3,3),(1,1)]                            │
└──────────────────────────────────────────────────────┘

второй вызов

SELECT toTypeName(readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)'));

┌─toTypeName(readWKTLineString('LINESTRING (1 1, 2 2, 3 3, 1 1)'))─┐
│ LineString                                                       │
└──────────────────────────────────────────────────────────────────┘

snowflakeIDToDateTime​

Появилась в версии: v24.6

Возвращает временную компоненту Snowflake ID как значение типа DateTime.

Синтаксис

snowflakeIDToDateTime(value[, epoch[, time_zone]])

Аргументы

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

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

Возвращает компонент метки времени из value. DateTime

Примеры

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

SELECT snowflakeIDToDateTime(7204436857747984384) AS res

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeIDToDateTime64​

Добавлена в версии: v24.6

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

Синтаксис

snowflakeIDToDateTime64(value[, epoch[, time_zone]])

Аргументы

  • 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, то есть с точностью до миллисекунд. DateTime64

Примеры

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

SELECT snowflakeIDToDateTime64(7204436857747984384) AS res

┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeToDateTime​

Введена в версии v21.10

Deprecated feature
Примечание

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

Пожалуйста, используйте вместо неё функцию snowflakeIDToDateTime.

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

Синтаксис

snowflakeToDateTime(value[, time_zone])

Аргументы

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

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

Возвращает компонент метки времени из значения value. DateTime

Примеры

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

SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');

┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘

snowflakeToDateTime64​

Добавлена в версии: v21.10

Deprecated feature
Примечание

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

Используйте вместо неё функцию snowflakeIDToDateTime64.

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

Синтаксис

snowflakeToDateTime64(value[, time_zone])

Аргументы

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

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

Возвращает компонент отметки времени из value. DateTime64(3)

Примеры

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

SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');

┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘

toUUIDOrDefault​

Введена в версии: v21.1

Преобразует значение типа String в тип UUID. Если преобразование не удалось, возвращает UUID по умолчанию вместо генерации ошибки.

Функция пытается разобрать строку из 36 символов в стандартном формате UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Если строку нельзя преобразовать в корректный UUID, функция возвращает указанный UUID по умолчанию.

Синтаксис

toUUIDOrDefault(string, default)

Аргументы

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

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

Возвращает преобразованный UUID при успешном преобразовании или UUID по умолчанию, если преобразование завершается ошибкой. UUID

Примеры

Успешное преобразование возвращает распарсенный UUID

SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘

В случае неудачного преобразования возвращается UUID по умолчанию

SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));

┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

toUUIDOrNull​

Введена в версии v20.12

Преобразует входное значение в значение типа UUID, но в случае ошибки возвращает NULL. Аналог функции toUUID, но возвращает NULL вместо выбрасывания исключения при ошибках преобразования.

Поддерживаемые аргументы:

  • Строковые представления UUID в стандартном формате (8-4-4-4-12 шестнадцатеричных цифр).
  • Строковые представления UUID без дефисов (32 шестнадцатеричные цифры).

Неподдерживаемые аргументы (возвращают NULL):

  • Неверные строковые форматы.
  • Типы, отличные от строк.
  • Некорректные UUID.

Синтаксис

toUUIDOrNull(x)

Аргументы

  • x — строковое представление UUID. String

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

Возвращает значение UUID при успешном преобразовании, в противном случае — NULL. UUID или NULL

Примеры

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

SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid

┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘