Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funções para trabalhar com UUIDs

View as MarkdownEdit this pageReport an issueSet up docs MCP

Geração de UUIDv7

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.

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

Geração de Snowflake ID

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.

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

UUIDNumToString

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

UUIDNumToString(binary[, variant])

Argumentos

  • binary — Representação binária de um UUID. FixedString(16)
  • variant — Variante conforme especificado na RFC4122. 1 = Big-endian (padrão), 2 = Microsoft. (U)Int*

Valor retornado

Retorna o UUID como uma string. String

Exemplos

Exemplo de uso

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

Variante da Microsoft

SELECT
    '@</a;]~!p{jTj={)' AS bytes,
    UUIDNumToString(toFixedString(bytes, 16), 2) AS uuid
┌─bytes────────────┬─uuid─────────────────────────────────┐
│ @</a;]~!p{jTj={) │ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │
└──────────────────┴──────────────────────────────────────┘

UUIDStringToNum

Introduzido em: v1.1.0

Aceita uma string contendo 36 caracteres no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx e retorna uma FixedString(16) como sua representação binária, com o formato opcionalmente especificado por variant (Big-endian por padrão).

Sintaxe

UUIDStringToNum(string[, variant = 1])

Argumentos

  • string — Uma string ou string de tamanho fixo com 36 caracteres) String ou FixedString(36)
  • variant — Variante conforme especificado pela RFC4122. 1 = Big-endian (padrão), 2 = Microsoft. (U)Int*

Valor retornado

Retorna a representação binária de string. FixedString(16)

Exemplos

Exemplo de uso

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

variante da Microsoft

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

UUIDToNum

Introduzido em: v24.5.0

Aceita um UUID e retorna sua representação binária como FixedString(16), 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

UUIDToNum(uuid[, variant = 1])

Argumentos

Valor retornado

Retorna uma representação binária do UUID. FixedString(16)

Exemplos

Exemplo de uso

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

variante da Microsoft

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

UUIDv7ToDateTime

Introduzido em: v24.5.0

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

Sintaxe

UUIDv7ToDateTime(uuid[, timezone])

Argumentos

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)

Exemplos

Exemplo de uso

SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'))─┐
│                                          2024-04-22 12:30:29.048 │
└──────────────────────────────────────────────────────────────────┘

Com fuso horário

SELECT UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')
┌─UUIDv7ToDateTime(toUUID('018f05c9-4ab8-7b86-b64e-c9f03fbd45d1'), 'America/New_York')─┐
│                                                              2024-04-22 08:30:29.048 │
└──────────────────────────────────────────────────────────────────────────────────────┘

dateTime64ToSnowflakeID

Introduzido em: v24.6.0

Converte um valor DateTime64 no primeiro Snowflake ID no instante informado.

Sintaxe

dateTime64ToSnowflakeID(value[, epoch])

Argumentos

  • value — Data e hora. 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*

Valor retornado

Valor de entrada convertido para UInt64

Exemplos

simples

SELECT dateTime64ToSnowflakeID(toDateTime64('2021-08-15 18:57:56', 3, 'Asia/Shanghai'))
6832626392367104000

dateTimeToSnowflakeID

Introduzido na versão: v24.6.0

Converte um valor DateTime no primeiro Snowflake ID para o momento especificado.

Sintaxe

dateTimeToSnowflakeID(value[, epoch])

Argumentos

  • value — Data e hora. 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*

Valor retornado

Valor de entrada convertido em UInt64

Exemplos

simples

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

dateTimeToUUIDv7

Introduzido em: v25.8.0

Converte um valor DateTime em um UUIDv7 no instante especificado, conforme definido pela RFC 9562.

Consulte a seção "Geração de UUIDv7" para obter detalhes sobre a estrutura do UUID, o gerenciamento do contador e as garantias de concorrência.

Sintaxe

dateTimeToUUIDv7(value)

Argumentos

Valor retornado

Retorna um UUIDv7. UUID

Exemplos

Exemplo de uso

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

vários UUIDs para o mesmo timestamp

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

generateSnowflakeID

Introduzido em: v24.6.0

Gera um 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" para obter detalhes de implementação.

Sintaxe

generateSnowflakeID([expr, [machine_id]])

Argumentos

  • expr — Uma expressão arbitrária usada para contornar a eliminação de subexpressões comuns 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. Opcional.

Valor retornado

Retorna o Snowflake ID. UInt64

Exemplos

Exemplo de uso

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

INSERT INTO tab SELECT generateSnowflakeID();

SELECT * FROM tab;
┌──────────────────id─┐
│ 7199081390080409600 │
└─────────────────────┘

Vários IDs Snowflake gerados por linha

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

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

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

generateUUIDv4

Introduzido em: v1.1.0

Gera um UUID da versão 4.

Sintaxe

generateUUIDv4([expr])

Argumentos

  • expr — Opcional. Uma expressão arbitrária usada para contornar a eliminação de subexpressões comuns 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

Exemplos

Exemplo de uso

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

Eliminação de subexpressões comuns

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

generateUUIDv7

Introduzido em: v24.5.0

Gera um UUID versão 7, conforme definido pela RFC 9562.

Consulte a seção "geração de UUIDv7" para ver detalhes sobre a estrutura do UUID, o gerenciamento do contador e as garantias de concorrência.

Sintaxe

generateUUIDv7([expr])

Argumentos

  • expr — Opcional. Uma expressão arbitrária usada para evitar a eliminação de subexpressões comuns 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

Valor retornado

Retorna um UUIDv7. UUID

Exemplos

Exemplo de uso

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

Eliminação de subexpressões comuns

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

snowflakeIDToDateTime

Introduzido em: v24.6.0

Retorna o componente de timestamp de um Snowflake ID como um valor do tipo DateTime.

Sintaxe

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

Argumentos

  • value — Snowflake ID. UInt64
  • 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*
  • time_zone — Opcional. Fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna o componente de timestamp de value. DateTime

Exemplos

Exemplo de uso

SELECT snowflakeIDToDateTime(7204436857747984384) AS res
┌─────────────────res─┐
│ 2024-06-06 10:59:58 │
└─────────────────────┘

snowflakeIDToDateTime64

Introduzido em: v24.6.0

Retorna o componente de timestamp de um Snowflake ID como valor do tipo DateTime64.

Sintaxe

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

Argumentos

  • value — Snowflake ID. UInt64
  • 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*
  • time_zone — Opcional. fuso horário. A função interpreta time_string de acordo com o fuso horário. String

Valor retornado

Retorna o componente de timestamp de value como um DateTime64 com escala = 3, ou seja, precisão de milissegundos. DateTime64

Exemplos

Exemplo de uso

SELECT snowflakeIDToDateTime64(7204436857747984384) AS res
┌─────────────────────res─┐
│ 2024-06-06 10:59:58.851 │
└─────────────────────────┘

toUUIDOrDefault

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

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

Exemplos

A conversão bem-sucedida retorna o UUID interpretado

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

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

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

toUUIDOrNull

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

toUUIDOrNull(x)

Argumentos

  • x — Uma representação textual de um UUID. String

Valor retornado

Retorna um valor UUID em caso de sucesso; caso contrário, NULL. UUID ou NULL

Exemplos

Exemplos de uso

SELECT
    toUUIDOrNull('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrNull('invalid-uuid') AS invalid_uuid
┌─valid_uuid───────────────────────────┬─invalid_uuid─┐
│ 550e8400-e29b-41d4-a716-446655440000 │ ᴺᵁᴸᴸ         │
└──────────────────────────────────────┴──────────────┘
Navigation