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

> Documentação sobre funções para trabalhar com UUIDs

# Funções para trabalhar com 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>;
};

<div id="uuidv7-generation">
  ## Geração de UUIDv7
</div>

O UUID gerado contém um timestamp de 48 bits em milissegundos Unix, seguido pela versão "7" (4 bits), um contador (42 bits) para distinguir UUIDs dentro de um mesmo milissegundo (incluindo um campo de variante "2", 2 bits) e um campo aleatório (32 bits).
Para um determinado timestamp (`unix_ts_ms`), o contador começa em um valor aleatório e é incrementado em 1 para cada novo UUID até que o timestamp mude. Em caso de overflow do contador, o campo de timestamp é incrementado em 1 e o contador é redefinido para um novo valor inicial aleatório.
As funções de geração de UUID garantem que o campo do contador dentro de um timestamp seja incrementado monotonicamente em todas as invocações da função, em threads e queries executadas concorrentemente.

```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">
  ## Geração de Snowflake ID
</div>

O Snowflake ID gerado contém o timestamp Unix atual em milissegundos (41 + 1 bits mais significativos zerados), seguido por um ID de máquina (10 bits) e um contador (12 bits) para diferenciar IDs dentro de um mesmo milissegundo. Para um determinado timestamp (`unix_ts_ms`), o contador começa em 0 e é incrementado em 1 para cada novo Snowflake ID até que o timestamp mude. Se o contador sofrer overflow, o campo de timestamp será incrementado em 1 e o contador será redefinido para 0.

<Note>
  Os Snowflake IDs gerados são baseados na epoch Unix 1970-01-01. Embora não exista um padrão ou recomendação para a epoch de Snowflake IDs, implementações em outros sistemas podem usar uma epoch diferente, por exemplo, Twitter/X (2010-11-04) ou 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>

Introduzido em: v1.1.0

Recebe uma representação binária de um UUID, com o formato opcionalmente especificado por `variant` (`Big-endian` por padrão), e retorna uma string de 36 caracteres em formato de texto.

**Sintaxe**

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

**Argumentos**

* `binary` — Representação binária de um UUID. [`FixedString(16)`](/pt-BR/reference/data-types/fixedstring)
* `variant` — Variante conforme especificado na [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (padrão), 2 = `Microsoft`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna o UUID como uma string. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Exemplo de uso**

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

**Variante da 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>

Introduzido em: v1.1.0

Aceita uma string contendo 36 caracteres no formato `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` e retorna uma [FixedString(16)](/pt-BR/reference/data-types/fixedstring) como sua representação binária, com o formato opcionalmente especificado por `variant` (`Big-endian` por padrão).

**Sintaxe**

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

**Argumentos**

* `string` — Uma string ou string de tamanho fixo com 36 caracteres) [`String`](/pt-BR/reference/data-types/string) ou [`FixedString(36)`](/pt-BR/reference/data-types/fixedstring)
* `variant` — Variante conforme especificado pela [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (padrão), 2 = `Microsoft`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna a representação binária de `string`. [`FixedString(16)`](/pt-BR/reference/data-types/fixedstring)

**Exemplos**

**Exemplo de uso**

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

**variante da 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>

Introduzido em: v24.5.0

Aceita um [UUID](/pt-BR/reference/data-types/uuid) e retorna sua representação binária como [FixedString(16)](/pt-BR/reference/data-types/fixedstring), com o formato opcionalmente especificado por `variant` (`Big-endian` por padrão).
Esta função substitui chamadas a duas funções separadas, `UUIDStringToNum(toString(uuid))`, portanto não é necessária nenhuma conversão intermediária de UUID para string para extrair bytes de um UUID.

**Sintaxe**

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

**Argumentos**

* `uuid` — UUID. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `variant` — Variante conforme especificado na [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.1). 1 = `Big-endian` (padrão), 2 = `Microsoft`. [`(U)Int*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna uma representação binária do UUID. [`FixedString(16)`](/pt-BR/reference/data-types/fixedstring)

**Exemplos**

**Exemplo de uso**

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

**variante da 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>

Introduzido em: v24.5.0

Retorna o componente de timestamp de um UUID versão 7.

**Sintaxe**

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

**Argumentos**

* `uuid` — Um UUID da versão 7. [`String`](/pt-BR/reference/data-types/string)
* `timezone` — Opcional. [Nome do fuso horário](/pt-BR/reference/settings/server-settings/settings#timezone) do valor retornado. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna um timestamp com precisão de milissegundos. Se o UUID não for um UUID válido da versão 7, retorna `1970-01-01 00:00:00.000`. [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)

**Exemplos**

**Exemplo de uso**

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

**Com fuso horário**

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

Introduzido em: v21.10.0

<Warning>
  Esta função está obsoleta e só pode ser usada se a configuração [`allow_deprecated_snowflake_conversion_functions`](/pt-BR/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) estiver habilitada.
  A função será removida futuramente.

  Use a função [dateTime64ToSnowflakeID](#dateTime64ToSnowflakeID) em vez dela.
</Warning>

Converte um [DateTime64](/pt-BR/reference/data-types/datetime64) no primeiro [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) correspondente ao instante informado.

**Sintaxe**

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

**Argumentos**

* `value` — Data e hora. [`DateTime64`](/pt-BR/reference/data-types/datetime64)

**Valor retornado**

Retorna o valor de entrada convertido para o primeiro Snowflake ID naquele momento. [`Int64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

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

Introduzido em: v24.6.0

Converte um valor [DateTime64](/pt-BR/reference/data-types/datetime64) no primeiro [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) no instante informado.

**Sintaxe**

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

**Argumentos**

* `value` — Data e hora. [`DateTime64`](/pt-BR/reference/data-types/datetime64)
* `epoch` — epoch do Snowflake ID em milissegundos desde 1970-01-01. O padrão é 0 (1970-01-01). Para o epoch do Twitter/X (2015-01-01), forneça 1288834974657. [`UInt*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Valor de entrada convertido para [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**simples**

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

Introduzido em: v21.10.0

<Warning>
  Esta função está obsoleta e só pode ser usada se a configuração [`allow_deprecated_snowflake_conversion_functions`](/pt-BR/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) estiver habilitada.
  A função será removida em algum momento no futuro.

  Use a função [dateTimeToSnowflakeID](#dateTimeToSnowflakeID) em vez dela.
</Warning>

Converte um valor [DateTime](/pt-BR/reference/data-types/datetime) no primeiro [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) no momento especificado.

**Sintaxe**

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

**Argumentos**

* `value` — Data e hora. [`DateTime`](/pt-BR/reference/data-types/datetime)

**Valor retornado**

Retorna o valor de entrada como o primeiro Snowflake ID correspondente àquele momento. [`Int64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

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

Introduzido na versão: v24.6.0

Converte um valor [DateTime](/pt-BR/reference/data-types/datetime) no primeiro [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) para o momento especificado.

**Sintaxe**

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

**Argumentos**

* `value` — Data e hora. [`DateTime`](/pt-BR/reference/data-types/datetime)
* `epoch` — epoch do Snowflake ID em milissegundos a partir de 1970-01-01. O padrão é 0 (1970-01-01). Para o epoch do Twitter/X (2015-01-01), forneça 1288834974657. [`UInt*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Valor de entrada convertido em [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**simples**

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

Introduzido em: v25.8.0

Converte um valor [DateTime](/pt-BR/reference/data-types/datetime) em um [UUIDv7](https://en.wikipedia.org/wiki/UUID#Version_7) no instante especificado.

Consulte a seção ["Geração de UUIDv7"](#uuidv7-generation) para obter detalhes sobre a estrutura do UUID, o gerenciamento do contador e as garantias de concorrência.

<Note>
  Em setembro de 2025, os UUIDs versão 7 ainda estão em fase de rascunho, e seu layout pode mudar no futuro.
</Note>

**Sintaxe**

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

**Argumentos**

* `value` — Data com horário. [`DateTime`](/pt-BR/reference/data-types/datetime)

**Valor retornado**

Retorna um UUIDv7. [`UUID`](/pt-BR/reference/data-types/uuid)

**Exemplos**

**Exemplo de uso**

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

**vários UUIDs para o mesmo 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 │
└──────────────────────────────────────┘
```

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

Introduzido em: v24.6.0

Gera um [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID).

A função `generateSnowflakeID` garante que o campo contador em um timestamp seja incrementado monotonicamente em todas as invocações da função, mesmo em threads e consultas executadas concorrentemente.

Consulte a seção ["geração de Snowflake ID"](#snowflake-id-generation) para obter detalhes de implementação.

**Sintaxe**

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

**Argumentos**

* `expr` — Uma [expressão](/pt-BR/reference/syntax#expressions) arbitrária usada para contornar a [eliminação de subexpressões comuns](/pt-BR/reference/functions/regular-functions/overview#common-subexpression-elimination) caso a função seja chamada várias vezes em uma consulta. O valor da expressão não afeta o Snowflake ID retornado. Opcional. - `machine_id` — Um ID de máquina; os 10 bits menos significativos são usados. [Int64](/pt-BR/reference/data-types/int-uint). Opcional.

**Valor retornado**

Retorna o Snowflake ID. [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

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

**Vários IDs Snowflake gerados por linha**

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

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

**Com uma expressão e um ID de máquina**

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

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

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

Introduzido em: v1.1.0

Gera um [UUID](/pt-BR/reference/data-types/uuid) [da versão 4](https://tools.ietf.org/html/rfc4122#section-4.4).

**Sintaxe**

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

**Argumentos**

* `expr` — Opcional. Uma expressão arbitrária usada para contornar a [eliminação de subexpressões comuns](/pt-BR/reference/functions/regular-functions/overview#common-subexpression-elimination) caso a função seja chamada várias vezes em uma consulta. O valor da expressão não afeta o UUID retornado.

**Valor retornado**

Retorna um UUIDv4. [`UUID`](/pt-BR/reference/data-types/uuid)

**Exemplos**

**Exemplo de uso**

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

**Eliminação de subexpressões comuns**

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

Introduzido em: v24.5.0

Gera um [UUID](/pt-BR/reference/data-types/uuid) [versão 7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04).

Consulte a seção ["geração de UUIDv7"](#uuidv7-generation) para ver detalhes sobre a estrutura do UUID, o gerenciamento do contador e as garantias de concorrência.

<Note>
  Em setembro de 2025, os UUIDs versão 7 ainda estão em status de rascunho, e seu layout poderá mudar no futuro.
</Note>

**Sintaxe**

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

**Argumentos**

* `expr` — Opcional. Uma expressão arbitrária usada para evitar a [eliminação de subexpressões comuns](/pt-BR/reference/functions/regular-functions/overview#common-subexpression-elimination) se a função for chamada várias vezes em uma consulta. O valor da expressão não tem efeito no UUID retornado. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna um UUIDv7. [`UUID`](/pt-BR/reference/data-types/uuid)

**Exemplos**

**Exemplo de uso**

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

**Eliminação de subexpressões comuns**

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

Introduzido em: v24.6.0

Retorna o componente de timestamp de um [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) como um valor do tipo [DateTime](/pt-BR/reference/data-types/datetime).

**Sintaxe**

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

**Argumentos**

* `value` — Snowflake ID. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `epoch` — Opcional. Epoch do Snowflake ID em milissegundos desde 1970-01-01. O padrão é 0 (1970-01-01). Para a epoch do Twitter/X (2015-01-01), informe 1288834974657. [`UInt*`](/pt-BR/reference/data-types/int-uint)
* `time_zone` — Opcional. [Fuso horário](/pt-BR/reference/settings/server-settings/settings#timezone). A função interpreta `time_string` de acordo com o fuso horário. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna o componente de timestamp de `value`. [`DateTime`](/pt-BR/reference/data-types/datetime)

**Exemplos**

**Exemplo de uso**

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

Introduzido em: v24.6.0

Retorna o componente de timestamp de um [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) como valor do tipo [DateTime64](/pt-BR/reference/data-types/datetime64).

**Sintaxe**

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

**Argumentos**

* `value` — Snowflake ID. [`UInt64`](/pt-BR/reference/data-types/int-uint)
* `epoch` — Opcional. Epoch do Snowflake ID em milissegundos desde 1970-01-01. O padrão é 0 (1970-01-01). Para a epoch do Twitter/X (2015-01-01), informe 1288834974657. [`UInt*`](/pt-BR/reference/data-types/int-uint)
* `time_zone` — Opcional. [Timezone](/pt-BR/reference/settings/server-settings/settings#timezone). A função interpreta `time_string` de acordo com o fuso horário. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna o componente de timestamp de `value` como um `DateTime64` com escala = 3, ou seja, precisão de milissegundos. [`DateTime64`](/pt-BR/reference/data-types/datetime64)

**Exemplos**

**Exemplo de uso**

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

Introduzido em: v21.10.0

<Warning>
  Esta função foi descontinuada e só pode ser usada se a configuração [`allow_deprecated_snowflake_conversion_functions`](/pt-BR/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) estiver habilitada.
  A função será removida futuramente.

  Use a função [`snowflakeIDToDateTime`](#snowflakeIDToDateTime).
</Warning>

Extrai o componente de timestamp de um [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) no formato [DateTime](/pt-BR/reference/data-types/datetime).

**Sintaxe**

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

**Argumentos**

* `value` — Snowflake ID. [`Int64`](/pt-BR/reference/data-types/int-uint)
* `time_zone` — Opcional. [Fuso horário](/pt-BR/reference/settings/server-settings/settings#timezone). A função interpreta `time_string` de acordo com o fuso horário. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna o timestamp de `value`. [`DateTime`](/pt-BR/reference/data-types/datetime)

**Exemplos**

**Exemplo de uso**

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

Introduzido em: v21.10.0

<Warning>
  Esta função está obsoleta e só pode ser usada se a configuração [`allow_deprecated_snowflake_conversion_functions`](/pt-BR/reference/settings/session-settings#allow_deprecated_snowflake_conversion_functions) estiver habilitada.
  A função será removida futuramente.

  Use a função [`snowflakeIDToDateTime64`](#snowflakeIDToDateTime64).
</Warning>

Extrai o componente de timestamp de um [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) no formato [DateTime64](/pt-BR/reference/data-types/datetime64).

**Sintaxe**

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

**Argumentos**

* `value` — Snowflake ID. [`Int64`](/pt-BR/reference/data-types/int-uint)
* `time_zone` — Opcional. [Fuso horário](/pt-BR/reference/settings/server-settings/settings#timezone). A função interpreta `time_string` de acordo com o fuso horário. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna o componente de timestamp de `value`. [`DateTime64(3)`](/pt-BR/reference/data-types/datetime64)

**Exemplos**

**Exemplo de uso**

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

Introduzido em: v21.1.0

Converte um valor String para o tipo UUID. Se a conversão falhar, retorna um valor UUID padrão em vez de gerar um erro.

Esta função tenta interpretar uma string de 36 caracteres no formato UUID padrão (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Se a string não puder ser convertida em um UUID válido, a função retornará o valor UUID padrão fornecido.

**Sintaxe**

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

**Argumentos**

* `string` — String de 36 caracteres ou FixedString(36) a ser convertida em UUID. - `default` — valor UUID a ser retornado se o primeiro argumento não puder ser convertido para o tipo UUID.

**Valor retornado**

Retorna o UUID convertido em caso de sucesso ou o UUID padrão se a conversão falhar. [`UUID`](/pt-BR/reference/data-types/uuid)

**Exemplos**

**A conversão bem-sucedida retorna o UUID interpretado**

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

**Em caso de falha na conversão, retorna o UUID padrão**

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

Introduzido em: v20.12.0

Converte um valor de entrada em um valor do tipo `UUID`, mas retorna `NULL` em caso de erro.

Como [`toUUID`](/pt-BR/reference/functions/regular-functions/type-conversion-functions#toUUID), mas retorna `NULL` em vez de lançar uma exceção em erros de conversão.

Argumentos compatíveis:

* Representações de UUID em string no formato padrão (8-4-4-4-12 dígitos hexadecimais).
* Representações de UUID em string sem hífens (32 dígitos hexadecimais).

Argumentos não compatíveis (retornam `NULL`):

* Formatos de string inválidos.
* Tipos não string.
* UUIDs malformados.

**Sintaxe**

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

**Argumentos**

* `x` — Uma representação textual de um UUID. [`String`](/pt-BR/reference/data-types/string)

**Valor retornado**

Retorna um valor UUID em caso de sucesso; caso contrário, `NULL`. [`UUID`](/pt-BR/reference/data-types/uuid) ou [`NULL`](/pt-BR/reference/syntax#null)

**Exemplos**

**Exemplos de uso**

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