> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по функциям для работы с UUID

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

export const DeprecatedBadge = () => {
  return <div className="deprecatedBadge">
            <div className="deprecatedIcon">
            <svg width="14" height="10" viewBox="0 0 14 10" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M13 0H1C0.734784 0 0.48043 0.105357 0.292893 0.292893C0.105357 0.48043 0 0.734784 0 1V2.5C0 2.76522 0.105357 3.01957 0.292893 3.20711C0.48043 3.39464 0.734784 3.5 1 3.5V9C1 9.26522 1.10536 9.51957 1.29289 9.70711C1.48043 9.89464 1.73478 10 2 10H12C12.2652 10 12.5196 9.89464 12.7071 9.70711C12.8946 9.51957 13 9.26522 13 9V3.5C13.2652 3.5 13.5196 3.39464 13.7071 3.20711C13.8946 3.01957 14 2.76522 14 2.5V1C14 0.734784 13.8946 0.48043 13.7071 0.292893C13.5196 0.105357 13.2652 0 13 0ZM12 9H2V3.5H12V9ZM13 2.5H1V1H13V2.5ZM5 5.5C5 5.36739 5.05268 5.24021 5.14645 5.14645C5.24021 5.05268 5.36739 5 5.5 5H8.5C8.63261 5 8.75979 5.05268 8.85355 5.14645C8.94732 5.24021 9 5.36739 9 5.5C9 5.63261 8.94732 5.75979 8.85355 5.85355C8.75979 5.94732 8.63261 6 8.5 6H5.5C5.36739 6 5.24021 5.94732 5.14645 5.85355C5.05268 5.75979 5 5.63261 5 5.5Z" fill="currentColor" />
            </svg>
        </div>
            Deprecated feature
        </div>;
};

<div id="uuidv7-generation">
  ## Генерация UUIDv7
</div>

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

```text theme={null}
 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
```

<div id="snowflake-id-generation">
  ## Генерация Snowflake ID
</div>

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

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

```text theme={null}
 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    |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
```

{/*AUTOGENERATED_START*/}

<div id="UUIDNumToString">
  ## UUIDNumToString
</div>

Добавленный в: v1.1.0

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

**Синтаксис**

```sql theme={null}
UUIDNumToString(binary[, variant])
```

**Аргументы**

* `binary` — Двоичное представление UUID. [`FixedString(16)`](/ru/reference/data-types/fixedstring)
* `variant` — Вариант в соответствии с [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (по умолчанию), 2 = `Microsoft`. [`(U)Int*`](/ru/reference/data-types/int-uint)

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

Возвращает UUID в виде строки. [`String`](/ru/reference/data-types/string)

**Примеры**

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

```sql title=Query theme={null}
SELECT
    'a/<@];!~p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16)) AS uuid
```

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

**Вариант Microsoft**

```sql title=Query theme={null}
SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
```

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

<div id="UUIDStringToNum">
  ## UUIDStringToNum
</div>

Добавленный в: v1.1.0

Принимает строку из 36 символов в формате `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` и возвращает [FixedString(16)](/ru/reference/data-types/fixedstring) с её двоичным представлением; при необходимости формат можно указать с помощью `variant` (по умолчанию — `Big-endian`).

**Синтаксис**

```sql theme={null}
UUIDStringToNum(string[, variant = 1])
```

**Аргументы**

* `string` — Строка или строка фиксированной длины из 36 символов [`String`](/ru/reference/data-types/string) или [`FixedString(36)`](/ru/reference/data-types/fixedstring)
* `variant` — Вариант согласно [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (по умолчанию), 2 = `Microsoft`. [`(U)Int*`](/ru/reference/data-types/int-uint)

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

Возвращает двоичное представление `string`. [`FixedString(16)`](/ru/reference/data-types/fixedstring)

**Примеры**

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

```sql title=Query theme={null}
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid) AS bytes
```

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

**Вариант Microsoft**

```sql title=Query theme={null}
SELECT
    '612f3c40-5d3b-217e-707b-6a546a3d7b29' AS uuid,
    UUIDStringToNum(uuid, 2) AS bytes
```

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

<div id="UUIDToNum">
  ## UUIDToNum
</div>

Добавленный в: v24.5.0

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

**Синтаксис**

```sql theme={null}
UUIDToNum(uuid[, variant = 1])
```

**Аргументы**

* `uuid` — UUID. [`String`](/ru/reference/data-types/string) или [`FixedString`](/ru/reference/data-types/fixedstring)
* `variant` — Variant, как указано в [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (по умолчанию), 2 = `Microsoft`. [`(U)Int*`](/ru/reference/data-types/int-uint)

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

Возвращает двоичное представление UUID. [`FixedString(16)`](/ru/reference/data-types/fixedstring)

**Примеры**

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

```sql title=Query theme={null}
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid) AS bytes
```

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

**Вариант Microsoft**

```sql title=Query theme={null}
SELECT
    toUUID('612f3c40-5d3b-217e-707b-6a546a3d7b29') AS uuid,
    UUIDToNum(uuid, 2) AS bytes
```

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

<div id="UUIDv7ToDateTime">
  ## UUIDv7ToDateTime
</div>

Добавленный в: v24.5.0

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

**Синтаксис**

```sql theme={null}
UUIDv7ToDateTime(uuid[, timezone])
```

**Аргументы**

* `uuid` — UUID версии 7. [`String`](/ru/reference/data-types/string)
* `timezone` — Необязательный параметр. [Имя часового пояса](/ru/reference/settings/server-settings/settings#timezone) для возвращаемого значения. [`String`](/ru/reference/data-types/string)

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

Возвращает временную метку с точностью до миллисекунд. Если UUID не является корректным UUID версии 7, возвращает `1970-01-01 00:00:00.000`. [`DateTime64(3)`](/ru/reference/data-types/datetime64)

**Примеры**

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

```sql title=Query theme={null}
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
```

```response title=Response theme={null}
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 15:30:29.048 │
└──────────────────────────────────────────────────────────────────┘
```

**С указанием часового пояса**

```sql title=Query theme={null}
SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
```

```response title=Response theme={null}
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                             2024-04-22 11:30:29.048 │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="dateTime64ToSnowflake">
  ## dateTime64ToSnowflake
</div>

Добавленный в: v21.10.0

<Warning>
  Эта функция устарела и может использоваться только при включенной настройке [`allow_deprecated_snowflake_conversion_functions`](/ru/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions).
  В будущем функция будет удалена.

  Вместо нее используйте функцию [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID).
</Warning>

Преобразует [DateTime64](/ru/reference/data-types/datetime64) в первый [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) для указанного момента времени.

**Синтаксис**

```sql theme={null}
dateTime64ToSnowflake(value)
```

**Аргументы**

* `value` — дата и время. [`DateTime64`](/ru/reference/data-types/datetime64)

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

Возвращает входное значение, преобразованное в первый Snowflake ID для этого момента времени. [`Int64`](/ru/reference/data-types/int-uint)

**Примеры**

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

```sql title=Query theme={null}
WITH toDateTime64('2021-08-15 18:57:56.492', 3, 'Asia/Shanghai') AS dt64 SELECT dateTime64ToSnowflake(dt64);
```

```response title=Response theme={null}
┌─dateTime64ToSnowflake(dt64)─┐
│         1426860704886947840 │
└─────────────────────────────┘
```

<div id="dateTime64ToSnowflakeID">
  ## dateTime64ToSnowflakeID
</div>

Добавленный в: v24.6.0

Преобразует значение [DateTime64](/ru/reference/data-types/datetime64) в первый [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID), соответствующий заданному моменту времени.

**Синтаксис**

```sql theme={null}
dateTime64ToSnowflakeID(value[, epoch])
```

**Аргументы**

* `value` — Дата и время. [`DateTime64`](/ru/reference/data-types/datetime64)
* `epoch` — Эпоха для Snowflake ID в миллисекундах с 1970-01-01. По умолчанию — 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. [`UInt*`](/ru/reference/data-types/int-uint)

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

Входное значение, преобразованное в [`UInt64`](/ru/reference/data-types/int-uint)

**Примеры**

**простой**

```sql title=Query theme={null}
SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
```

```response title=Response theme={null}
6832626394434895872
```

<div id="dateTimeToSnowflake">
  ## dateTimeToSnowflake
</div>

Добавленный в: v21.10.0

<Warning>
  Эта функция устарела и может использоваться только при включенном параметре [`allow_deprecated_snowflake_conversion_functions`](/ru/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions).
  В будущем функция будет удалена.

  Вместо нее используйте функцию [dateTimeToSnowflakeID](#dateTimeToSnowflakeID).
</Warning>

Преобразует значение [DateTime](/ru/reference/data-types/datetime) в первый [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) для указанного момента времени.

**Синтаксис**

```sql theme={null}
dateTimeToSnowflake(value)
```

**Аргументы**

* `value` — Дата и время. [`DateTime`](/ru/reference/data-types/datetime)

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

Возвращает входное значение в виде первого Snowflake ID для данного момента времени. [`Int64`](/ru/reference/data-types/int-uint)

**Примеры**

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

```sql title=Query theme={null}
WITH toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai') AS dt SELECT dateTimeToSnowflake(dt);
```

```response title=Response theme={null}
┌─dateTimeToSnowflake(dt)─┐
│     1426860702823350272 │
└─────────────────────────┘
```

<div id="dateTimeToSnowflakeID">
  ## dateTimeToSnowflakeID
</div>

Добавленный в: v24.6.0

Преобразует значение [DateTime](/ru/reference/data-types/datetime) в первый [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) для заданного момента времени.

**Синтаксис**

```sql theme={null}
dateTimeToSnowflakeID(value[, epoch])
```

**Аргументы**

* `value` — Дата и время. [`DateTime`](/ru/reference/data-types/datetime)
* `epoch` — эпоха Snowflake ID в миллисекундах с 1970-01-01. По умолчанию — 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. [`UInt*`](/ru/reference/data-types/int-uint)

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

Входное значение, преобразованное в [`UInt64`](/ru/reference/data-types/int-uint)

**Примеры**

**простой**

```sql title=Query theme={null}
SELECT dateTimeToSnowflakeID(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))
```

```response title=Response theme={null}
6832626392367104000
```

<div id="dateTimeToUUIDv7">
  ## dateTimeToUUIDv7
</div>

Добавленный в: v25.8.0

Преобразует значение [DateTime](/ru/reference/data-types/datetime) в [UUIDv7](https://en.wikipedia.org/wiki/UUID#Version_7) для указанного момента времени.

Подробные сведения о структуре UUID, управлении счётчиком и гарантиях параллелизма см. в разделе ["Генерация UUIDv7"](#uuidv7-generation).

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

**Синтаксис**

```sql theme={null}
dateTimeToUUIDv7(value)
```

**Аргументы**

* `value` — Дата и время. [`DateTime`](/ru/reference/data-types/datetime)

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

Возвращает UUIDv7. [`UUID`](/ru/reference/data-types/uuid)

**Примеры**

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

```sql title=Query theme={null}
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'));
```

```response title=Response theme={null}
┌─dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56', 'Asia/Shanghai'))─┐
│ 018f05af-f4a8-778f-beee-1bedbc95c93b                                   │
└─────────────────────────────────────────────────────────────────────────┘
```

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

```sql title=Query theme={null}
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
SELECT dateTimeToUUIDv7(toDateTime('2021-08-15 18:57:56'));
```

```response title=Response theme={null}
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcc23a8c550 │
└──────────────────────────────────────┘
┌─dateTimeToUUIDv7(t⋯08-15 18:57:56'))─┐
│ 017b4b2d-7720-76ed-ae44-bbcf71ed0fd3 │
└──────────────────────────────────────┘
```

<div id="generateSnowflakeID">
  ## generateSnowflakeID
</div>

Добавленный в: v24.6.0

Генерирует [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID).

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

Подробности реализации см. в разделе ["Генерация Snowflake ID"](#snowflake-id-generation).

**Синтаксис**

```sql theme={null}
generateSnowflakeID([expr, [machine_id]])
```

**Аргументы**

* `expr` — Произвольное [выражение](/ru/reference/syntax#expressions), используемое для обхода [устранения общих подвыражений](/ru/reference/functions/regular-functions/overview#common-subexpression-elimination), если функция вызывается в запросе несколько раз. Значение выражения не влияет на возвращаемый Snowflake ID. Необязательно. - `machine_id` — Идентификатор машины; используются младшие 10 бит. [Int64](/ru/reference/data-types/int-uint). Необязательно.

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

Возвращает Snowflake ID. [`UInt64`](/ru/reference/data-types/int-uint)

**Примеры**

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

```sql title=Query theme={null}
CREATE TABLE tab (id UInt64)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;
```

```response title=Response theme={null}
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘
```

**Генерация нескольких Snowflake ID для каждой строки**

```sql title=Query theme={null}
SELECT generateSnowflakeID(1), generateSnowflakeID(2);
```

```response title=Response theme={null}
┌─generateSnowflakeID(1)─┬─generateSnowflakeID(2)─┐
│    7199081609652224000 │    7199081609652224001 │
└────────────────────────┴────────────────────────┘
```

**С выражением и идентификатором машины**

```sql title=Query theme={null}
SELECT generateSnowflakeID('expr', 1);
```

```response title=Response theme={null}
┌─generateSnowflakeID('expr', 1)─┐
│            7201148511606784002 │
└────────────────────────────────┘
```

<div id="generateUUIDv4">
  ## generateUUIDv4
</div>

Добавленный в: v1.1.0

Генерирует [UUID версии 4](https://tools.ietf.org/html/rfc4122#section-4.4) [UUID](/ru/reference/data-types/uuid).

**Синтаксис**

```sql theme={null}
generateUUIDv4([expr])
```

**Аргументы**

* `expr` — Необязательный. Произвольное выражение, используемое для обхода [устранения общих подвыражений](/ru/reference/functions/regular-functions/overview#common-subexpression-elimination), если функция вызывается в запросе несколько раз. Значение выражения не влияет на возвращаемый UUID.

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

Возвращает UUIDv4. [`UUID`](/ru/reference/data-types/uuid)

**Примеры**

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

```sql title=Query theme={null}
SELECT generateUUIDv4(number) FROM numbers(3);
```

```response title=Response theme={null}
┌─generateUUIDv4(number)───────────────┐
│ fcf19b77-a610-42c5-b3f5-a13c122f65b6 │
│ 07700d36-cb6b-4189-af1d-0972f23dc3bc │
│ 68838947-1583-48b0-b9b7-cf8268dd343d │
└──────────────────────────────────────┘
```

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

```sql title=Query theme={null}
SELECT generateUUIDv4(1), generateUUIDv4(1);
```

```response title=Response theme={null}
┌─generateUUIDv4(1)────────────────────┬─generateUUIDv4(2)────────────────────┐
│ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │ 2d49dc6e-ddce-4cd0-afb8-790956df54c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```

<div id="generateUUIDv7">
  ## generateUUIDv7
</div>

Добавленный в: v24.5.0

Генерирует [UUID версии 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04) типа [UUID](/ru/reference/data-types/uuid).

Подробные сведения о структуре UUID, управлении счётчиком и гарантиях параллелизма см. в разделе ["Генерация UUIDv7"](#uuidv7-generation).

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

**Синтаксис**

```sql theme={null}
generateUUIDv7([expr])
```

**Аргументы**

* `expr` — Необязательный. Произвольное выражение, используемое для отключения [устранения общих подвыражений](/ru/reference/functions/regular-functions/overview#common-subexpression-elimination), если функция вызывается в запросе несколько раз. Значение выражения не влияет на возвращаемый UUID. [`Any`](/ru/reference/data-types)

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

Возвращает UUIDv7. [`UUID`](/ru/reference/data-types/uuid)

**Примеры**

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

```sql title=Query theme={null}
SELECT generateUUIDv7(number) FROM numbers(3);
```

```response title=Response theme={null}
┌─generateUUIDv7(number)───────────────┐
│ 019947fb-5766-7ed0-b021-d906f8f7cebb │
│ 019947fb-5766-7ed0-b021-d9072d0d1e07 │
│ 019947fb-5766-7ed0-b021-d908dca2cf63 │
└──────────────────────────────────────┘
```

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

```sql title=Query theme={null}
SELECT generateUUIDv7(1), generateUUIDv7(1);
```

```response title=Response theme={null}
┌─generateUUIDv7(1)────────────────────┬─generateUUIDv7(1)────────────────────┐
│ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │ 019947ff-0f87-7d88-ace0-8b5b3a66e0c1 │
└──────────────────────────────────────┴──────────────────────────────────────┘
```

<div id="snowflakeIDToDateTime">
  ## snowflakeIDToDateTime
</div>

Добавленный в: v24.6.0

Возвращает компонент временной метки [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) в виде значения типа [DateTime](/ru/reference/data-types/datetime).

**Синтаксис**

```sql theme={null}
snowflakeIDToDateTime(value[, epoch[, time_zone]])
```

**Аргументы**

* `value` — Snowflake ID. [`UInt64`](/ru/reference/data-types/int-uint)
* `epoch` — Необязательно. Эпоха Snowflake ID в миллисекундах, отсчитываемых с 1970-01-01. Значение по умолчанию — 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. [`UInt*`](/ru/reference/data-types/int-uint)
* `time_zone` — Необязательно. [Часовой пояс](/ru/reference/settings/server-settings/settings#timezone). Функция разбирает `time_string` с учетом часового пояса. [`String`](/ru/reference/data-types/string)

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

Возвращает компонент временной метки значения `value`. [`DateTime`](/ru/reference/data-types/datetime)

**Примеры**

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

```sql title=Query theme={null}
SELECT snowflakeIDToDateTime(7204436857747984384) AS res
```

```response title=Response theme={null}
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
```

<div id="snowflakeIDToDateTime64">
  ## snowflakeIDToDateTime64
</div>

Добавленный в: v24.6.0

Возвращает компонент временной метки [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) в виде значения типа [DateTime64](/ru/reference/data-types/datetime64).

**Синтаксис**

```sql theme={null}
snowflakeIDToDateTime64(value[, epoch[, time_zone]])
```

**Аргументы**

* `value` — Snowflake ID. [`UInt64`](/ru/reference/data-types/int-uint)
* `epoch` — Необязательно. Эпоха Snowflake ID в миллисекундах с 1970-01-01. По умолчанию — 0 (1970-01-01). Для эпохи Twitter/X (2015-01-01) укажите 1288834974657. [`UInt*`](/ru/reference/data-types/int-uint)
* `time_zone` — Необязательно. [Часовой пояс](/ru/reference/settings/server-settings/settings#timezone). Функция интерпретирует `time_string` в соответствии с часовым поясом. [`String`](/ru/reference/data-types/string)

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

Возвращает компонент временной метки из `value` в виде `DateTime64` с scale = 3, то есть с точностью до миллисекунд. [`DateTime64`](/ru/reference/data-types/datetime64)

**Примеры**

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

```sql title=Query theme={null}
SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
```

```response title=Response theme={null}
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘
```

<div id="snowflakeToDateTime">
  ## snowflakeToDateTime
</div>

Добавленный в: v21.10.0

<Warning>
  Эта функция устарела и может использоваться только при включенной настройке [`allow_deprecated_snowflake_conversion_functions`](/ru/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions).
  В будущем функция будет удалена.

  Вместо нее используйте функцию [`snowflakeIDToDateTime`](#snowflakeIDToDateTime).
</Warning>

Извлекает компонент временной метки из [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) в формате [DateTime](/ru/reference/data-types/datetime).

**Синтаксис**

```sql theme={null}
snowflakeToDateTime(value[, time_zone])
```

**Аргументы**

* `value` — Snowflake ID. [`Int64`](/ru/reference/data-types/int-uint)
* `time_zone` — Необязательно. [Часовой пояс](/ru/reference/settings/server-settings/settings#timezone). Функция разбирает `time_string` с учетом часового пояса. [`String`](/ru/reference/data-types/string)

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

Возвращает компонент временной метки значения `value`. [`DateTime`](/ru/reference/data-types/datetime)

**Примеры**

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

```sql title=Query theme={null}
SELECT snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC');
```

```response title=Response theme={null}
┌─snowflakeToDateTime(CAST('1426860702823350272', 'Int64'), 'UTC')─┐
│                                              2021-08-15 10:57:56 │
└──────────────────────────────────────────────────────────────────┘
```

<div id="snowflakeToDateTime64">
  ## snowflakeToDateTime64
</div>

Добавленный в: v21.10.0

<Warning>
  Эта функция устарела и может использоваться только при включенной настройке [`allow_deprecated_snowflake_conversion_functions`](/ru/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions).
  В будущем функция будет удалена.

  Вместо нее используйте функцию [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64).
</Warning>

Извлекает компонент временной метки из [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) в формате [DateTime64](/ru/reference/data-types/datetime64).

**Синтаксис**

```sql theme={null}
snowflakeToDateTime64(value[, time_zone])
```

**Аргументы**

* `value` — Snowflake ID. [`Int64`](/ru/reference/data-types/int-uint)
* `time_zone` — Необязательно. [Часовой пояс](/ru/reference/settings/server-settings/settings#timezone). Функция разбирает `time_string` с учётом часового пояса. [`String`](/ru/reference/data-types/string)

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

Возвращает компонент временной метки значения `value`. [`DateTime64(3)`](/ru/reference/data-types/datetime64)

**Примеры**

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

```sql title=Query theme={null}
SELECT snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC');
```

```response title=Response theme={null}
┌─snowflakeToDateTime64(CAST('1426860802823350272', 'Int64'), 'UTC')─┐
│                                            2021-08-15 10:58:19.841 │
└────────────────────────────────────────────────────────────────────┘
```

<div id="toUUIDOrDefault">
  ## toUUIDOrDefault
</div>

Добавленный в: v21.1.0

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

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

**Синтаксис**

```sql theme={null}
toUUIDOrDefault(string, default)
```

**Аргументы**

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

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

Возвращает преобразованный UUID в случае успеха или UUID по умолчанию, если преобразование не удалось. [`UUID`](/ru/reference/data-types/uuid)

**Примеры**

**При успешном преобразовании возвращается разобранный UUID**

```sql title=Query theme={null}
SELECT toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
```

```response title=Response theme={null}
┌─toUUIDOrDefault('61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

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

```sql title=Query theme={null}
SELECT toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'));
```

```response title=Response theme={null}
┌─toUUIDOrDefault('-----61f0c404-5cb3-11e7-907b-a6006ad3dba0', toUUID('59f0c404-5cb3-11e7-907b-a6006ad3dba0'))─┐
│ 59f0c404-5cb3-11e7-907b-a6006ad3dba0                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="toUUIDOrNull">
  ## toUUIDOrNull
</div>

Добавленный в: v20.12.0

Преобразует входное значение в значение типа `UUID`, но в случае ошибки возвращает `NULL`.

Аналогична [`toUUID`](/ru/reference/functions/regular-functions/type-conversion-functions#toUUID), но при ошибках преобразования возвращает `NULL` вместо того, чтобы генерировать исключение.

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

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

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

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

**Синтаксис**

```sql theme={null}
toUUIDOrNull(x)
```

**Аргументы**

* `x` — Строковое представление UUID. [`String`](/ru/reference/data-types/string)

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

Возвращает UUID при успешном выполнении, в противном случае — `NULL`. [`UUID`](/ru/reference/data-types/uuid) или [`NULL`](/ru/reference/syntax#null)

**Примеры**

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

```sql title=Query theme={null}
SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid
```

```response title=Response theme={null}
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
```