Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funciones para trabajar con UUIDs

View as MarkdownEdit this pageReport an issueSet up docs MCP

Generación de UUIDv7

El UUID generado contiene una marca temporal de 48 bits en milisegundos Unix, seguida de la versión "7" (4 bits), un contador (42 bits) para distinguir los UUID dentro de un milisegundo (incluido un campo de variante "2", 2 bits) y un campo aleatorio (32 bits). Para una marca temporal dada (unix_ts_ms), el contador comienza con un valor aleatorio y se incrementa en 1 por cada UUID nuevo hasta que la marca temporal cambia. En caso de desbordamiento del contador, el campo de marca temporal se incrementa en 1 y el contador se restablece a un nuevo valor inicial aleatorio. Las funciones de generación de UUID garantizan que el campo del contador dentro de una marca temporal se incremente de forma monótona en todas las invocaciones de la función realizadas por hilos y consultas que se ejecutan de forma concurrente.

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

Generación de ID de Snowflake

El ID de Snowflake generado contiene la marca de tiempo Unix actual en milisegundos (41 bits más 1 bit superior en cero), seguida de un id de máquina (10 bits) y un contador (12 bits) para distinguir los ID dentro de un mismo milisegundo. Para cualquier marca temporal dada (unix_ts_ms), el contador empieza en 0 y se incrementa en 1 para cada nuevo ID de Snowflake hasta que cambia la marca temporal. Si el contador se desborda, el campo de marca temporal se incrementa en 1 y el contador se reinicia a 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

Introducido en: v1.1.0

Toma una representación binaria de un UUID, cuyo formato puede especificarse opcionalmente mediante variant (Big-endian de forma predeterminada), y devuelve una cadena de 36 caracteres en formato de texto.

Sintaxis

UUIDNumToString(binary[, variant])

Argumentos

  • binary — Representación binaria de un UUID. FixedString(16)
  • variant — Variante según lo especificado en RFC4122. 1 = Big-endian (por defecto), 2 = Microsoft. (U)Int*

Valor devuelto

Devuelve el UUID como una cadena. String

Ejemplos

Ejemplo 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 de 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

Introducido en: v1.1.0

Acepta una cadena de 36 caracteres con el formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx y devuelve un FixedString(16) como representación binaria, cuyo formato puede especificarse opcionalmente mediante variant (Big-endian de forma predeterminada).

Sintaxis

UUIDStringToNum(string[, variant = 1])

Argumentos

  • string — Una cadena o una cadena de longitud fija de 36 caracteres String o FixedString(36)
  • variant — Variante según lo especificado en RFC4122. 1 = Big-endian (predeterminado), 2 = Microsoft. (U)Int*

Valor devuelto

Devuelve la representación binaria de string. FixedString(16)

Ejemplos

Ejemplo 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 de 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

Introducido en: v24.5.0

Acepta un UUID y devuelve su representación binaria como un FixedString(16), con el formato especificado opcionalmente mediante variant (Big-endian de forma predeterminada). Esta función reemplaza la llamada combinada a dos funciones, UUIDStringToNum(toString(uuid)), por lo que no se requiere una conversión intermedia de UUID a cadena para extraer los bytes de un UUID.

Sintaxis

UUIDToNum(uuid[, variant = 1])

Argumentos

Valor devuelto

Devuelve una representación binaria del UUID. FixedString(16)

Ejemplos

Ejemplo 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 de 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

Introducido en: v24.5.0

Devuelve el componente de marca temporal de un UUID de versión 7.

Sintaxis

UUIDv7ToDateTime(uuid[, timezone])

Argumentos

Valor devuelto

Devuelve una marca temporal con precisión de milisegundos. Si el UUID no es un UUID válido de versión 7, devuelve 1970-01-01 00:00:00.000. DateTime64(3)

Ejemplos

Ejemplo de uso

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

Con zona horaria

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

Introducido en: v24.6.0

Convierte un valor de DateTime64 en el primer ID de Snowflake correspondiente al instante dado.

Sintaxis

dateTime64ToSnowflakeID(value[, epoch])

Argumentos

  • value — Fecha con hora. DateTime64
  • epoch — Época del ID de Snowflake, en milisegundos desde 1970-01-01. El valor predeterminado es 0 (1970-01-01). Para la época de Twitter/X (2015-01-01), proporcione 1288834974657. UInt*

Valor devuelto

Valor de entrada convertido a UInt64

Ejemplos

simple

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

dateTimeToSnowflakeID

Introducido en: v24.6.0

Convierte un valor de DateTime en el primer Snowflake ID correspondiente al momento dado.

Sintaxis

dateTimeToSnowflakeID(value[, epoch])

Argumentos

  • value — Fecha con hora. DateTime
  • epoch — Epoch del Snowflake ID en milisegundos desde 1970-01-01. El valor predeterminado es 0 (1970-01-01). Para el epoch de Twitter/X (2015-01-01), proporcione 1288834974657. UInt*

Valor devuelto

Valor de entrada convertido a UInt64

Ejemplos

simple

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

dateTimeToUUIDv7

Introducido en: v25.8.0

Convierte un valor de DateTime en un UUIDv7 para el instante indicado, según se define en la RFC 9562.

Consulta la sección "Generación de UUIDv7" para obtener detalles sobre la estructura del UUID, la gestión del contador y las garantías de concurrencia.

Sintaxis

dateTimeToUUIDv7(value)

Argumentos

Valor devuelto

Devuelve un UUIDv7. UUID

Ejemplos

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

varios UUID para la misma marca temporal

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

Introducido en: v24.6.0

Genera un ID de Snowflake.

La función generateSnowflakeID garantiza que el campo contador dentro de una marca de tiempo se incremente de forma monotónica en todas las invocaciones de la función, incluso en subprocesos y consultas que se ejecutan de forma concurrente.

Consulte la sección "Generación de ID de Snowflake" para obtener detalles de implementación.

Sintaxis

generateSnowflakeID([expr, [machine_id]])

Argumentos

  • expr — Una expresión arbitraria que se utiliza para sortear la eliminación de subexpresiones comunes si la función se invoca varias veces en una consulta. El valor de la expresión no influye en el ID de Snowflake devuelto. Opcional. - machine_id — Un ID de máquina; se utilizan los 10 bits menos significativos. Int64. Opcional.

Valor devuelto

Devuelve el ID de Snowflake. UInt64

Ejemplos

Ejemplo de uso

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

INSERT INTO tab SELECT generateSnowflakeID();

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

Varios ID de Snowflake generados por fila

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

Con una expresión y un ID de máquina

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

generateUUIDv4

Introducida en: v1.1.0

Genera un UUID de versión 4.

Sintaxis

generateUUIDv4([expr])

Argumentos

  • expr — Opcional. Una expresión arbitraria utilizada para eludir la eliminación de subexpresiones comunes si se llama a la función varias veces en una consulta. El valor de la expresión no afecta al UUID devuelto.

Valor devuelto

Devuelve un UUIDv4. UUID

Ejemplos

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

Eliminación de subexpresiones comunes

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

generateUUIDv7

Introducido en: v24.5.0

Genera un UUID de versión 7 tal como se define en RFC 9562.

Consulta la sección "Generación de UUIDv7" para obtener más información sobre la estructura del UUID, la gestión del contador y las garantías de concurrencia.

Sintaxis

generateUUIDv7([expr])

Argumentos

Valor devuelto

Devuelve un UUIDv7. UUID

Ejemplos

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

Eludir la eliminación de subexpresiones comunes

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

snowflakeIDToDateTime

Introducido en: v24.6.0

Devuelve el componente de marca temporal de un ID de Snowflake como un valor de tipo DateTime.

Sintaxis

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

Argumentos

  • value — ID de Snowflake. UInt64
  • epoch — Opcional. Época del ID de Snowflake en milisegundos desde 1970-01-01. El valor predeterminado es 0 (1970-01-01). Para la época de Twitter/X (2015-01-01), proporcione 1288834974657. UInt*
  • time_zone — Opcional. Zona horaria. La función analiza time_string de acuerdo con la zona horaria. String

Valor devuelto

Devuelve el componente de marca temporal de value. DateTime

Ejemplos

Ejemplo de uso

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

snowflakeIDToDateTime64

Introducido en: v24.6.0

Devuelve el componente de marca temporal de un ID de Snowflake como un valor del tipo DateTime64.

Sintaxis

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

Argumentos

  • value — ID de Snowflake. UInt64
  • epoch — Opcional. Época del ID de Snowflake en milisegundos desde 1970-01-01. El valor predeterminado es 0 (1970-01-01). Para la época de Twitter/X (2015-01-01), proporcione 1288834974657. UInt*
  • time_zone — Opcional. Zona horaria. La función interpreta time_string según la zona horaria. String

Valor devuelto

Devuelve el componente de marca temporal de value como un DateTime64 con escala = 3, es decir, precisión de milisegundos. DateTime64

Ejemplos

Ejemplo de uso

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

toUUIDOrDefault

Introducido en: v21.1.0

Convierte un valor String al tipo UUID. Si la conversión falla, devuelve un valor UUID predeterminado en lugar de producir un error.

Esta función intenta analizar una cadena de 36 caracteres en el formato UUID estándar (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Si la cadena no puede convertirse en un UUID válido, la función devuelve el valor UUID predeterminado proporcionado.

Sintaxis

toUUIDOrDefault(string, default)

Argumentos

  • string — Cadena de 36 caracteres o FixedString(36) que se convertirá a UUID. - default — valor UUID que se devolverá si el primer argumento no puede convertirse al tipo UUID.

Valor devuelto

Devuelve el UUID convertido si la operación se realiza correctamente, o el UUID predeterminado si la conversión falla. UUID

Ejemplos

Una conversión correcta devuelve el UUID analizado

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

Si la conversión falla, devuelve el UUID predeterminado

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

Introducido en: v20.12.0

Convierte un valor de entrada en un valor de tipo UUID, pero devuelve NULL en caso de error.

Como toUUID, pero devuelve NULL en lugar de lanzar una excepción cuando se producen errores de conversión.

Argumentos admitidos:

  • Representaciones en cadena de UUID en formato estándar (8-4-4-4-12 dígitos hexadecimales).
  • Representaciones en cadena de UUID sin guiones (32 dígitos hexadecimales).

Argumentos no admitidos (devuelven NULL):

  • Formatos de cadena no válidos.
  • Tipos que no son de cadena.
  • UUID mal formados.

Sintaxis

toUUIDOrNull(x)

Argumentos

  • x — Una representación en forma de cadena de un UUID. String

Valor devuelto

Devuelve un valor UUID si la operación se realiza correctamente; de lo contrario, NULL. UUID o NULL

Ejemplos

Ejemplos 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