> ## 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.

> 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에는 Unix 밀리초 단위의 48비트 타임스탬프가 포함되며, 그 뒤에 버전 "7"(4비트), 동일한 밀리초 내에서 UUID를 구분하기 위한 카운터(42비트, variant 필드 "2"의 2비트 포함), 그리고 랜덤 필드(32비트)가 이어집니다.
주어진 타임스탬프(`unix_ts_ms`)에서 카운터는 임의의 값으로 시작하며, 타임스탬프가 바뀔 때까지 새 UUID가 생성될 때마다 1씩 증가합니다. 카운터에 오버플로우가 발생하면 타임스탬프 필드는 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 타임스탬프가 밀리초 단위로 들어 있으며(상위 0 비트 41 + 1개), 그 뒤에 머신 ID(10비트)와 1밀리초 내에서 ID를 구분하기 위한 카운터(12비트)가 이어집니다. 각 타임스탬프(`unix_ts_ms`)에 대해 카운터는 0에서 시작하며, 타임스탬프가 바뀔 때까지 새 Snowflake ID가 생성될 때마다 1씩 증가합니다. 카운터에 오버플로우가 발생하면 타임스탬프 필드가 1 증가하고 카운터는 0으로 재설정됩니다.

<Note>
  생성된 Snowflake ID는 UNIX epoch 1970-01-01을 기준으로 합니다. Snowflake ID의 epoch에 대한 표준이나 권고는 없지만, 다른 시스템의 구현은 서로 다른 epoch를 사용할 수 있습니다. 예를 들어 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)`](/ko/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1)에서 지정한 variant입니다. 1 = `Big-endian`(기본값), 2 = `Microsoft`입니다. [`(U)Int*`](/ko/reference/data-types/int-uint)

**반환 값**

UUID를 문자열로 반환합니다. [`String`](/ko/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

`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` 포맷의 36자 문자열을 받아 해당 문자열의 바이너리 표현인 [FixedString(16)](/ko/reference/data-types/fixedstring)을 반환합니다. 포맷은 `variant`로 선택적으로 지정할 수 있으며 기본값은 `Big-endian`입니다.

**구문**

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

**인수**

* `string` — 36자 길이의 문자열 또는 고정 길이 문자열 [`String`](/ko/reference/data-types/string) 또는 [`FixedString(36)`](/ko/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1)에 지정된 Variant입니다. 1 = `Big-endian`(기본값), 2 = `Microsoft`. [`(U)Int*`](/ko/reference/data-types/int-uint)

**반환 값**

`string`의 이진 표현을 반환합니다. [`FixedString(16)`](/ko/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](/ko/reference/data-types/uuid)를 받아 해당 이진 표현을 [FixedString(16)](/ko/reference/data-types/fixedstring)으로 반환하며, `variant`로 포맷을 선택적으로 지정할 수 있습니다(기본값은 `Big-endian`).
이 함수는 별도의 두 함수 호출인 `UUIDStringToNum(toString(uuid))`를 대체하므로, UUID에서 바이트를 추출하기 위해 UUID를 문자열로 중간 변환할 필요가 없습니다.

**구문**

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

**인수**

* `uuid` — UUID입니다. [`String`](/ko/reference/data-types/string) 또는 [`FixedString`](/ko/reference/data-types/fixedstring)
* `variant` — [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1)에 지정된 Variant입니다. 1 = `Big-endian`(기본값), 2 = `Microsoft`. [`(U)Int*`](/ko/reference/data-types/int-uint)

**반환 값**

UUID의 이진 표현을 반환합니다. [`FixedString(16)`](/ko/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`](/ko/reference/data-types/string)
* `timezone` — 선택 사항입니다. 반환 값에 사용할 [시간대 이름](/ko/reference/settings/server-settings/settings#timezone)입니다. [`String`](/ko/reference/data-types/string)

**반환 값**

밀리초 정밀도의 타임스탬프를 반환합니다. UUID가 유효한 버전 7 UUID가 아니면 `1970-01-01 00:00:00.000`을 반환합니다. [`DateTime64(3)`](/ko/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`](/ko/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions)이 활성화된 경우에만 사용할 수 있습니다.
  이 함수는 향후 제거될 예정입니다.

  대신 [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID) 함수를 사용하십시오.
</Warning>

[DateTime64](/ko/reference/data-types/datetime64)를 지정된 시각에 해당하는 첫 번째 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)로 변환합니다.

**구문**

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

**인수**

* `value` — 시간이 포함된 날짜 및 시간 값입니다. [`DateTime64`](/ko/reference/data-types/datetime64)

**반환 값**

입력 값을 해당 시점의 첫 번째 Snowflake ID로 변환한 값을 반환합니다. [`Int64`](/ko/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](/ko/reference/data-types/datetime64) 값을 지정된 시점에 해당하는 첫 번째 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)로 변환합니다.

**구문**

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

**인수**

* `value` — 날짜 및 시간. [`DateTime64`](/ko/reference/data-types/datetime64)
* `epoch` — 1970-01-01부터 경과한 시간을 밀리초 단위로 나타낸 Snowflake ID의 epoch입니다. 기본값은 0(1970-01-01)입니다. Twitter/X epoch(2015-01-01)를 사용하려면 1288834974657을 지정하십시오. [`UInt*`](/ko/reference/data-types/int-uint)

**반환 값**

입력 값을 [`UInt64`](/ko/reference/data-types/int-uint)로 변환한 값입니다.

**예시**

**simple**

```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`](/ko/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions)이 활성화된 경우에만 사용할 수 있습니다.
  이 함수는 향후 어느 시점에 제거될 예정입니다.

  대신 [dateTimeToSnowflakeID](#dateTimeToSnowflakeID) 함수를 사용하십시오.
</Warning>

[DateTime](/ko/reference/data-types/datetime) 값을 지정된 시점의 첫 번째 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)로 변환합니다.

**구문**

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

**인수**

* `value` — 날짜 및 시간. [`DateTime`](/ko/reference/data-types/datetime)

**반환 값**

입력 값을 해당 시점의 첫 번째 Snowflake ID로 반환합니다. [`Int64`](/ko/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](/ko/reference/data-types/datetime) 값을 주어진 시각의 첫 번째 [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)로 변환합니다.

**구문**

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

**인수**

* `value` — 시간이 포함된 날짜입니다. [`DateTime`](/ko/reference/data-types/datetime)
* `epoch` — 1970-01-01부터 경과한 밀리초 단위의 Snowflake ID epoch입니다. 기본값은 0(1970-01-01)입니다. Twitter/X epoch(2015-01-01)에는 1288834974657을 지정하십시오. [`UInt*`](/ko/reference/data-types/int-uint)

**반환 값**

입력 값이 [`UInt64`](/ko/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](/ko/reference/data-types/datetime) 값을 [UUIDv7](https://en.wikipedia.org/wiki/UUID#Version_7)로 변환합니다.

UUID 구조, 카운터 관리, 동시성 보장에 대한 자세한 내용은 ["UUIDv7 생성"](#uuidv7-generation) 섹션을 참조하십시오.

<Note>
  2025년 9월 기준으로 버전 7 UUID는 초안 상태이며, 향후 내부 레이아웃이 변경될 수 있습니다.
</Note>

**구문**

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

**인수**

* `value` — 시간이 포함된 날짜/시간 값. [`DateTime`](/ko/reference/data-types/datetime)

**반환 값**

UUIDv7를 반환합니다. [`UUID`](/ko/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 generation"](#snowflake-id-generation) 섹션을 참조하십시오.

**구문**

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

**인수**

* `expr` — 쿼리에서 이 함수가 여러 번 호출될 때 [공통 하위 표현식 제거](/ko/reference/functions/regular-functions/overview#common-subexpression-elimination)를 우회하는 데 사용되는 임의의 [표현식](/ko/reference/syntax#expressions)입니다. 표현식 값은 반환되는 Snowflake ID에 영향을 주지 않습니다. 선택 사항입니다. - `machine_id` — 머신 ID입니다. 하위 10비트가 사용됩니다. [Int64](/ko/reference/data-types/int-uint). 선택 사항입니다.

**반환 값**

Snowflake ID를 반환합니다. [`UInt64`](/ko/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 │
└────────────────────────┴────────────────────────┘
```

**표현식과 머신 ID를 사용**

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

[버전 4](https://tools.ietf.org/html/rfc4122#section-4.4) [UUID](/ko/reference/data-types/uuid)를 생성합니다.

**구문**

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

**인수**

* `expr` — 선택 사항입니다. 함수가 하나의 쿼리에서 여러 번 호출될 때 [공통 하위 표현식 제거](/ko/reference/functions/regular-functions/overview#common-subexpression-elimination)을 우회하기 위해 사용하는 임의의 표현식입니다. 이 표현식의 값은 반환되는 UUID에 영향을 주지 않습니다.

**반환 값**

UUIDv4를 반환합니다. [`UUID`](/ko/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

[버전 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04) [UUID](/ko/reference/data-types/uuid)를 생성합니다.

UUID 구조, 카운터 관리, 동시성 보장에 관한 자세한 내용은 ["UUIDv7 생성"](#uuidv7-generation) 섹션을 참조하십시오.

<Note>
  2025년 9월 기준으로 버전 7 UUID는 초안 상태이며, 향후 레이아웃이 변경될 수 있습니다.
</Note>

**구문**

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

**인수**

* `expr` — 선택 사항입니다. 함수가 한 쿼리에서 여러 번 호출될 때 [공통 하위 표현식 제거](/ko/reference/functions/regular-functions/overview#common-subexpression-elimination)를 피하기 위해 사용하는 임의의 표현식입니다. 이 표현식의 값은 반환되는 UUID에 영향을 주지 않습니다. [`Any`](/ko/reference/data-types)

**반환 값**

UUIDv7을 반환합니다. [`UUID`](/ko/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](/ko/reference/data-types/datetime) 유형의 값으로 반환합니다.

**구문**

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

**인수**

* `value` — Snowflake ID입니다. [`UInt64`](/ko/reference/data-types/int-uint)
* `epoch` — 선택 사항입니다. 1970-01-01 이후 경과한 밀리초 단위의 Snowflake ID epoch입니다. 기본값은 0(1970-01-01)입니다. Twitter/X epoch(2015-01-01)의 경우 1288834974657을 지정하십시오. [`UInt*`](/ko/reference/data-types/int-uint)
* `time_zone` — 선택 사항입니다. [시간대](/ko/reference/settings/server-settings/settings#timezone)입니다. 함수는 `time_string`을 시간대에 따라 해석합니다. [`String`](/ko/reference/data-types/string)

**반환 값**

`value`의 timestamp 구성 요소를 반환합니다. [`DateTime`](/ko/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](/ko/reference/data-types/datetime64) 타입의 값으로 반환합니다.

**구문**

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

**인수**

* `value` — Snowflake ID. [`UInt64`](/ko/reference/data-types/int-uint)
* `epoch` — 선택 사항입니다. 1970-01-01부터 경과한 밀리초 단위의 Snowflake ID epoch입니다. 기본값은 0(1970-01-01)입니다. Twitter/X epoch(2015-01-01)를 사용하려면 1288834974657을 지정하십시오. [`UInt*`](/ko/reference/data-types/int-uint)
* `time_zone` — 선택 사항입니다. [시간대](/ko/reference/settings/server-settings/settings#timezone)입니다. 이 함수는 `time_string`을 해당 시간대에 따라 파싱합니다. [`String`](/ko/reference/data-types/string)

**반환 값**

`value`의 타임스탬프 구성 요소를 scale = 3, 즉 밀리초 정밀도의 `DateTime64`로 반환합니다. [`DateTime64`](/ko/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`](/ko/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions)이 활성화된 경우에만 사용할 수 있습니다.
  이 함수는 향후 제거될 예정입니다.

  대신 [`snowflakeIDToDateTime`](#snowflakeIDToDateTime) 함수를 사용하십시오.
</Warning>

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)에서 타임스탬프 구성 요소를 [DateTime](/ko/reference/data-types/datetime) 형식으로 추출합니다.

**구문**

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

**인수**

* `value` — Snowflake ID. [`Int64`](/ko/reference/data-types/int-uint)
* `time_zone` — 선택 사항입니다. [시간대](/ko/reference/settings/server-settings/settings#timezone). 함수는 `time_string`을 해당 시간대에 따라 파싱합니다. [`String`](/ko/reference/data-types/string)

**반환 값**

`value`의 타임스탬프 구성 요소를 반환합니다. [`DateTime`](/ko/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`](/ko/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions)이 활성화된 경우에만 사용할 수 있습니다.
  이 함수는 향후 어느 시점에 제거될 수 있습니다.

  대신 [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64) 함수를 사용하십시오.
</Warning>

[Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID)의 타임스탬프 부분을 [DateTime64](/ko/reference/data-types/datetime64) 포맷으로 추출합니다.

**구문**

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

**인수**

* `value` — Snowflake ID. [`Int64`](/ko/reference/data-types/int-uint)
* `time_zone` — 선택 사항입니다. [시간대](/ko/reference/settings/server-settings/settings#timezone)입니다. 함수는 `time_string`을 해당 시간대에 따라 해석합니다. [`String`](/ko/reference/data-types/string)

**반환 값**

`value`의 타임스탬프 구성 요소를 반환합니다. [`DateTime64(3)`](/ko/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 값을 반환합니다.

이 함수는 표준 UUID 포맷(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)의 36자 문자열을 파싱합니다.
문자열을 유효한 UUID로 변환할 수 없으면 제공된 기본 UUID 값을 반환합니다.

**구문**

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

**인수**

* `string` — UUID로 변환할 36자 String 또는 FixedString(36)입니다. - `default` — 첫 번째 인수를 UUID 타입으로 변환할 수 없을 때 반환할 UUID 값입니다.

**반환 값**

변환에 성공하면 변환된 UUID를 반환하고, 변환에 실패하면 기본 UUID를 반환합니다. [`UUID`](/ko/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`](/ko/reference/functions/regular-functions/type-conversion-functions#toUUID)와 유사하지만, 변환 오류 시 예외를 발생시키는 대신 `NULL`을 반환합니다.

지원되는 인수:

* 표준 포맷(8-4-4-4-12자리 16진수)의 UUID 문자열 표현.
* 하이픈이 없는 UUID 문자열 표현(32자리 16진수).

지원되지 않는 인수(`NULL` 반환):

* 잘못된 문자열 포맷.
* 문자열이 아닌 타입.
* 잘못된 형식의 UUID.

**구문**

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

**인수**

* `x` — UUID의 문자열 표현입니다. [`String`](/ko/reference/data-types/string)

**반환 값**

성공하면 UUID 값을 반환하고, 실패하면 `NULL`을 반환합니다. [`UUID`](/ko/reference/data-types/uuid) 또는 [`NULL`](/ko/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 │         ᴺᵁᴸᴸ │
└──────────────────────────────────────┴──────────────┘
```