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

> Documentation for Functions for Working with UUIDs

# Functions for Working with UUIDs

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>;
};

# Functions for working with UUIDs

<h2 id="uuidv7-generation">
  UUIDv7 generation
</h2>

The generated UUID contains a 48-bit timestamp in Unix milliseconds, followed by version "7" (4 bits), a counter (42 bits) to distinguish UUIDs within a millisecond (including a variant field "2", 2 bits), and a random field (32 bits).
For any given timestamp (`unix_ts_ms`), the counter starts at a random value and is incremented by 1 for each new UUID until the timestamp changes. In case the counter overflows, the timestamp field is incremented by 1 and the counter is reset to a random new start value.
The UUID generation functions guarantee that the counter field within a timestamp increments monotonically across all function invocations in concurrently running threads and queries.

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

<h2 id="snowflake-id-generation">
  Snowflake ID generation
</h2>

The generated Snowflake ID contains the current Unix timestamp in milliseconds (41 + 1 top zero bits), followed by a machine id (10 bits), and a counter (12 bits) to distinguish IDs within a millisecond. For any given timestamp (`unix_ts_ms`), the counter starts at 0 and is incremented by 1 for each new Snowflake ID until the timestamp changes. In case the counter overflows, the timestamp field is incremented by 1 and the counter is reset to 0.

<Note>
  The generated Snowflake IDs are based on the UNIX epoch 1970-01-01. While no standard or recommendation exists for the epoch of Snowflake IDs, implementations in other systems may use a different epoch, e.g. Twitter/X (2010-11-04) or 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*/}

<h2 id="UUIDNumToString">
  UUIDNumToString
</h2>

Introduced in: v1.1.0

Takes a binary representation of a UUID, with its format optionally specified by `variant` (`Big-endian` by default), and returns a string containing 36 characters in text format.

**Syntax**

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

**Arguments**

* `binary` — Binary representation of a UUID. [`FixedString(16)`](/reference/data-types/fixedstring)
* `variant` — Variant as specified by [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (default), 2 = `Microsoft`. [`(U)Int*`](/reference/data-types/int-uint)

**Returned value**

Returns the UUID as a string. [`String`](/reference/data-types/string)

**Examples**

**Usage example**

```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 variant**

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

<h2 id="UUIDStringToNum">
  UUIDStringToNum
</h2>

Introduced in: v1.1.0

Accepts a string containing 36 characters in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, and returns a [FixedString(16)](/reference/data-types/fixedstring) as its binary representation, with its format optionally specified by `variant` (`Big-endian` by default).

**Syntax**

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

**Arguments**

* `string` — A string or fixed-string of 36 characters) [`String`](/reference/data-types/string) or [`FixedString(36)`](/reference/data-types/fixedstring)
* `variant` — Variant as specified by [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (default), 2 = `Microsoft`. [`(U)Int*`](/reference/data-types/int-uint)

**Returned value**

Returns the binary representation of `string`. [`FixedString(16)`](/reference/data-types/fixedstring)

**Examples**

**Usage example**

```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 variant**

```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={) │
└──────────────────────────────────────┴──────────────────┘
```

<h2 id="UUIDToNum">
  UUIDToNum
</h2>

Introduced in: v24.5.0

Accepts a [UUID](/reference/data-types/uuid) and returns its binary representation as a [FixedString(16)](/reference/data-types/fixedstring), with its format optionally specified by `variant` (`Big-endian` by default).
This function replaces calls to two separate functions `UUIDStringToNum(toString(uuid))` so no intermediate conversion from UUID to string is required to extract bytes from a UUID.

**Syntax**

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

**Arguments**

* `uuid` — UUID. [`String`](/reference/data-types/string) or [`FixedString`](/reference/data-types/fixedstring)
* `variant` — Variant as specified by [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (default), 2 = `Microsoft`. [`(U)Int*`](/reference/data-types/int-uint)

**Returned value**

Returns a binary representation of the UUID. [`FixedString(16)`](/reference/data-types/fixedstring)

**Examples**

**Usage example**

```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 variant**

```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={) │
└──────────────────────────────────────┴──────────────────┘
```

<h2 id="UUIDv7ToDateTime">
  UUIDv7ToDateTime
</h2>

Introduced in: v24.5.0

Returns the timestamp component of a UUID version 7.

**Syntax**

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

**Arguments**

* `uuid` — A UUID version 7. [`String`](/reference/data-types/string)
* `timezone` — Optional. [Timezone name](/reference/settings/server-settings/settings#timezone) for the returned value. [`String`](/reference/data-types/string)

**Returned value**

Returns a timestamp with milliseconds precision. If the UUID is not a valid version 7 UUID, it returns `1970-01-01 00:00:00.000`. [`DateTime64(3)`](/reference/data-types/datetime64)

**Examples**

**Usage example**

```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 │
└──────────────────────────────────────────────────────────────────┘
```

**With timezone**

```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 │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

<h2 id="dateTime64ToSnowflake">
  dateTime64ToSnowflake
</h2>

Introduced in: v21.10.0

<Warning>
  This function is deprecated and can only be used if setting [`allow_deprecated_snowflake_conversion_functions`](/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) is enabled.
  The function will be removed at some point in future.

  Please use function [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID) instead.
</Warning>

Converts a [DateTime64](/reference/data-types/datetime64) to the first [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) at the giving time.

**Syntax**

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

**Arguments**

* `value` — Date with time. [`DateTime64`](/reference/data-types/datetime64)

**Returned value**

Returns the input value converted as the first Snowflake ID at that time. [`Int64`](/reference/data-types/int-uint)

**Examples**

**Usage example**

```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 │
└─────────────────────────────┘
```

<h2 id="dateTime64ToSnowflakeID">
  dateTime64ToSnowflakeID
</h2>

Introduced in: v24.6.0

Converts a [DateTime64](/reference/data-types/datetime64) value to the first [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) at the giving time.

**Syntax**

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

**Arguments**

* `value` — Date with time. [`DateTime64`](/reference/data-types/datetime64)
* `epoch` — Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657. [`UInt*`](/reference/data-types/int-uint)

**Returned value**

Input value converted to [`UInt64`](/reference/data-types/int-uint)

**Examples**

**simple**

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

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

<h2 id="dateTimeToSnowflake">
  dateTimeToSnowflake
</h2>

Introduced in: v21.10.0

<Warning>
  This function is deprecated and can only be used if setting [`allow_deprecated_snowflake_conversion_functions`](/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) is enabled.
  The function will be removed at some point in future.

  Please use function [dateTimeToSnowflakeID](#dateTimeToSnowflakeID) instead.
</Warning>

Converts a [DateTime](/reference/data-types/datetime) value to the first [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) at the giving time.

**Syntax**

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

**Arguments**

* `value` — Date with time. [`DateTime`](/reference/data-types/datetime)

**Returned value**

Returns the input value as the first Snowflake ID at that time. [`Int64`](/reference/data-types/int-uint)

**Examples**

**Usage example**

```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 │
└─────────────────────────┘
```

<h2 id="dateTimeToSnowflakeID">
  dateTimeToSnowflakeID
</h2>

Introduced in: v24.6.0

Converts a [DateTime](/reference/data-types/datetime) value to the first [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) at the giving time.

**Syntax**

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

**Arguments**

* `value` — Date with time. [`DateTime`](/reference/data-types/datetime)
* `epoch` — Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657. [`UInt*`](/reference/data-types/int-uint)

**Returned value**

Input value converted to [`UInt64`](/reference/data-types/int-uint)

**Examples**

**simple**

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

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

<h2 id="dateTimeToUUIDv7">
  dateTimeToUUIDv7
</h2>

Introduced in: v25.8.0

Converts a [DateTime](/reference/data-types/datetime) value to a [UUIDv7](https://en.wikipedia.org/wiki/UUID#Version_7) at the given time.

See section ["UUIDv7 generation"](#uuidv7-generation) for details on UUID structure, counter management, and concurrency guarantees.

<Note>
  As of September 2025, version 7 UUIDs are in draft status and their layout may change in future.
</Note>

**Syntax**

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

**Arguments**

* `value` — Date with time. [`DateTime`](/reference/data-types/datetime)

**Returned value**

Returns a UUIDv7. [`UUID`](/reference/data-types/uuid)

**Examples**

**Usage example**

```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                                   │
└─────────────────────────────────────────────────────────────────────────┘
```

**multiple UUIDs for the same timestamp**

```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 │
└──────────────────────────────────────┘
```

<h2 id="generateSnowflakeID">
  generateSnowflakeID
</h2>

Introduced in: v24.6.0

Generates a [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID).

Function `generateSnowflakeID` guarantees that the counter field within a timestamp increments monotonically across all function invocations in concurrently running threads and queries.

See section ["Snowflake ID generation"](#snowflake-id-generation) for implementation details.

**Syntax**

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

**Arguments**

* `expr` — An arbitrary [expression](/reference/syntax#expressions) used to bypass [common subexpression elimination](/reference/functions/regular-functions/overview#common-subexpression-elimination) if the function is called multiple times in a query. The value of the expression has no effect on the returned Snowflake ID. Optional. - `machine_id` — A machine ID, the lowest 10 bits are used. [Int64](/reference/data-types/int-uint). Optional.

**Returned value**

Returns the Snowflake ID. [`UInt64`](/reference/data-types/int-uint)

**Examples**

**Usage example**

```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 │
└─────────────────────┘
```

**Multiple Snowflake IDs generated per row**

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

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

**With expression and a machine ID**

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

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

<h2 id="generateUUIDv4">
  generateUUIDv4
</h2>

Introduced in: v1.1.0

Generates a [version 4](https://tools.ietf.org/html/rfc4122#section-4.4) [UUID](/reference/data-types/uuid).

**Syntax**

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

**Arguments**

* `expr` — Optional. An arbitrary expression used to bypass [common subexpression elimination](/reference/functions/regular-functions/overview#common-subexpression-elimination) if the function is called multiple times in a query. The value of the expression has no effect on the returned UUID.

**Returned value**

Returns a UUIDv4. [`UUID`](/reference/data-types/uuid)

**Examples**

**Usage example**

```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 │
└──────────────────────────────────────┘
```

**Common subexpression elimination**

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

<h2 id="generateUUIDv7">
  generateUUIDv7
</h2>

Introduced in: v24.5.0

Generates a [version 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04) [UUID](/reference/data-types/uuid).

See section ["UUIDv7 generation"](#uuidv7-generation) for details on UUID structure, counter management, and concurrency guarantees.

<Note>
  As of September 2025, version 7 UUIDs are in draft status and their layout may change in future.
</Note>

**Syntax**

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

**Arguments**

* `expr` — Optional. An arbitrary expression used to bypass [common subexpression elimination](/reference/functions/regular-functions/overview#common-subexpression-elimination) if the function is called multiple times in a query. The value of the expression has no effect on the returned UUID. [`Any`](/reference/data-types/index)

**Returned value**

Returns a UUIDv7. [`UUID`](/reference/data-types/uuid)

**Examples**

**Usage example**

```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 │
└──────────────────────────────────────┘
```

**Common subexpression elimination**

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

<h2 id="snowflakeIDToDateTime">
  snowflakeIDToDateTime
</h2>

Introduced in: v24.6.0

Returns the timestamp component of a [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) as a value of type [DateTime](/reference/data-types/datetime).

**Syntax**

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

**Arguments**

* `value` — Snowflake ID. [`UInt64`](/reference/data-types/int-uint)
* `epoch` — Optional. Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657. [`UInt*`](/reference/data-types/int-uint)
* `time_zone` — Optional. [Timezone](/reference/settings/server-settings/settings#timezone). The function parses `time_string` according to the timezone. [`String`](/reference/data-types/string)

**Returned value**

Returns the timestamp component of `value`. [`DateTime`](/reference/data-types/datetime)

**Examples**

**Usage example**

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

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

<h2 id="snowflakeIDToDateTime64">
  snowflakeIDToDateTime64
</h2>

Introduced in: v24.6.0

Returns the timestamp component of a [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) as a value of type [DateTime64](/reference/data-types/datetime64).

**Syntax**

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

**Arguments**

* `value` — Snowflake ID. [`UInt64`](/reference/data-types/int-uint)
* `epoch` — Optional. Epoch of the Snowflake ID in milliseconds since 1970-01-01. Defaults to 0 (1970-01-01). For the Twitter/X epoch (2015-01-01), provide 1288834974657. [`UInt*`](/reference/data-types/int-uint)
* `time_zone` — Optional. [Timezone](/reference/settings/server-settings/settings#timezone). The function parses `time_string` according to the timezone. [`String`](/reference/data-types/string)

**Returned value**

Returns the timestamp component of `value` as a `DateTime64` with scale = 3, i.e. millisecond precision. [`DateTime64`](/reference/data-types/datetime64)

**Examples**

**Usage example**

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

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

<h2 id="snowflakeToDateTime">
  snowflakeToDateTime
</h2>

Introduced in: v21.10.0

<Warning>
  This function is deprecated and can only be used if setting [`allow_deprecated_snowflake_conversion_functions`](/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) is enabled.
  The function will be removed at some point in future.

  Please use function [`snowflakeIDToDateTime`](#snowflakeIDToDateTime) instead.
</Warning>

Extracts the timestamp component of a [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) in [DateTime](/reference/data-types/datetime) format.

**Syntax**

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

**Arguments**

* `value` — Snowflake ID. [`Int64`](/reference/data-types/int-uint)
* `time_zone` — Optional. [Timezone](/reference/settings/server-settings/settings#timezone). The function parses `time_string` according to the timezone. [`String`](/reference/data-types/string)

**Returned value**

Returns the timestamp component of `value`. [`DateTime`](/reference/data-types/datetime)

**Examples**

**Usage example**

```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 │
└──────────────────────────────────────────────────────────────────┘
```

<h2 id="snowflakeToDateTime64">
  snowflakeToDateTime64
</h2>

Introduced in: v21.10.0

<Warning>
  This function is deprecated and can only be used if setting [`allow_deprecated_snowflake_conversion_functions`](/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) is enabled.
  The function will be removed at some point in future.

  Please use function [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64) instead.
</Warning>

Extracts the timestamp component of a [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) in [DateTime64](/reference/data-types/datetime64) format.

**Syntax**

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

**Arguments**

* `value` — Snowflake ID. [`Int64`](/reference/data-types/int-uint)
* `time_zone` — Optional. [Timezone](/reference/settings/server-settings/settings#timezone). The function parses `time_string` according to the timezone. [`String`](/reference/data-types/string)

**Returned value**

Returns the timestamp component of `value`. [`DateTime64(3)`](/reference/data-types/datetime64)

**Examples**

**Usage example**

```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 │
└────────────────────────────────────────────────────────────────────┘
```

<h2 id="toUUIDOrDefault">
  toUUIDOrDefault
</h2>

Introduced in: v21.1.0

Converts a String value to UUID type. If the conversion fails, returns a default UUID value instead of throwing an error.

This function attempts to parse a string of 36 characters in the standard UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
If the string cannot be converted to a valid UUID, the function returns the provided default UUID value.

**Syntax**

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

**Arguments**

* `string` — String of 36 characters or FixedString(36) to be converted to UUID. - `default` — UUID value to be returned if the first argument cannot be converted to UUID type.

**Returned value**

Returns the converted UUID if successful, or the default UUID if conversion fails. [`UUID`](/reference/data-types/uuid)

**Examples**

**Successful conversion returns the parsed 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                                                                     │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

**Failed conversion returns the default 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                                                                          │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<h2 id="toUUIDOrNull">
  toUUIDOrNull
</h2>

Introduced in: v20.12.0

Converts an input value to a value of type `UUID` but returns `NULL` in case of an error.

Like [`toUUID`](/reference/functions/regular-functions/type-conversion-functions#toUUID) but returns `NULL` instead of throwing an exception on conversion errors.

Supported arguments:

* String representations of UUID in standard format (8-4-4-4-12 hexadecimal digits).
* String representations of UUID without hyphens (32 hexadecimal digits).

Unsupported arguments (return `NULL`):

* Invalid string formats.
* Non-string types.
* Malformed UUIDs.

**Syntax**

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

**Arguments**

* `x` — A string representation of a UUID. [`String`](/reference/data-types/string)

**Returned value**

Returns a UUID value if successful, otherwise `NULL`. [`UUID`](/reference/data-types/uuid) or [`NULL`](/reference/syntax#null)

**Examples**

**Usage examples**

```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 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
```