Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Fonctions de manipulation des UUIDs

View as MarkdownEdit this pageReport an issueSet up docs MCP

Génération des UUIDv7

L’UUID généré contient un horodatage de 48 bits en millisecondes Unix, suivi de la version "7" (4 bits), d’un compteur (42 bits) permettant de distinguer les UUID au sein d’une même milliseconde (y compris un champ de variante "2", 2 bits) et d’un champ aléatoire (32 bits). Pour un horodatage donné (unix_ts_ms), le compteur démarre à une valeur aléatoire et est incrémenté de 1 pour chaque nouvel UUID jusqu’à ce que l’horodatage change. En cas de débordement du compteur, le champ d’horodatage est incrémenté de 1 et le compteur est réinitialisé à une nouvelle valeur de départ aléatoire. Les fonctions de génération d’UUID garantissent que le champ de compteur, pour un horodatage donné, s’incrémente de façon monotone sur l’ensemble des appels de fonction effectués dans des threads et des requêtes exécutés de manière 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                             |
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Génération des Snowflake IDs

Le Snowflake ID généré contient l’horodatage Unix actuel en millisecondes (41 + 1 bits de poids fort à zéro), suivi d’un identifiant de machine (10 bits) et d’un compteur (12 bits) pour distinguer les identifiants au sein d’une même milliseconde. Pour un horodatage donné (unix_ts_ms), le compteur commence à 0 et est incrémenté de 1 pour chaque nouveau Snowflake ID, jusqu’à ce que l’horodatage change. En cas de dépassement de capacité du compteur, le champ d’horodatage est incrémenté de 1 et le compteur est réinitialisé à 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

Introduit dans : v1.1.0

Prend la représentation binaire d’un UUID, dont le format peut être indiqué de manière facultative par variant (Big-endian par défaut), et renvoie une chaîne de 36 caractères au format texte.

Syntaxe

UUIDNumToString(binary[, variant])

Arguments

  • binary — Représentation binaire d’un UUID. FixedString(16)
  • variant — Variante telle que définie par la RFC4122. 1 = Big-endian (par défaut), 2 = Microsoft. (U)Int*

Valeur renvoyée

Renvoyer l’UUID sous forme de chaîne. String

Exemples

Exemple d’utilisation

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

Variante 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

Introduite dans : v1.1.0

Accepte une chaîne de 36 caractères au format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx et renvoie un FixedString(16) sous sa représentation binaire, dont le format peut être spécifié via variant (Big-endian par défaut).

Syntaxe

UUIDStringToNum(string[, variant = 1])

Arguments

  • string — Une chaîne de caractères ou une chaîne de longueur fixe de 36 caractères) String ou FixedString(36)
  • variant — Variante telle que spécifiée par la RFC4122. 1 = Big-endian (par défaut), 2 = Microsoft. (U)Int*

Valeur renvoyée

Renvoie la représentation binaire de string. FixedString(16)

Exemples

Exemple d'utilisation

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

Variante 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

Introduit dans : v24.5.0

Accepte un UUID et renvoie sa représentation binaire sous la forme d’un FixedString(16), dont le format peut être spécifié via variant (Big-endian par défaut). Cette fonction remplace les appels combinés aux deux fonctions UUIDStringToNum(toString(uuid)), de sorte qu’aucune conversion intermédiaire de l’UUID en chaîne n’est nécessaire pour extraire les octets d’un UUID.

Syntaxe

UUIDToNum(uuid[, variant = 1])

Arguments

Valeur renvoyée

Renvoie une représentation binaire de l'UUID. FixedString(16)

Exemples

Exemple d'utilisation

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

Variante 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

Introduit dans : v24.5.0

Renvoie le composant d’horodatage d’un UUID version 7.

Syntaxe

UUIDv7ToDateTime(uuid[, timezone])

Arguments

Valeur renvoyée

Renvoie un horodatage avec une précision à la milliseconde. Si l'UUID n'est pas un UUID version 7 valide, renvoie 1970-01-01 00:00:00.000. DateTime64(3)

Exemples

Exemple d'utilisation

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

Avec fuseau horaire

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

Introduit dans : v24.6.0

Convertit une valeur DateTime64 en Snowflake ID initial à l’instant donné.

Syntaxe

dateTime64ToSnowflakeID(value[, epoch])

Arguments

  • value — Date et heure. DateTime64
  • epoch — époque du Snowflake ID, en millisecondes depuis 1970-01-01. La valeur par défaut est 0 (1970-01-01). Pour l’epoch Twitter/X (2015-01-01), utilisez 1288834974657. UInt*

Valeur renvoyée

Valeur d’entrée convertie en UInt64

Exemples

simple

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

dateTimeToSnowflakeID

Introduit dans : v24.6.0

Convertit une valeur DateTime en premier Snowflake ID pour l’instant donné.

Syntaxe

dateTimeToSnowflakeID(value[, epoch])

Arguments

  • value — Date avec heure. DateTime
  • epoch — Époque du Snowflake ID, en millisecondes depuis 1970-01-01. La valeur par défaut est 0 (1970-01-01). Pour l’époque Twitter/X (2015-01-01), indiquez 1288834974657. UInt*

Valeur renvoyée

Valeur d’entrée convertie en UInt64

Exemples

simple

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

dateTimeToUUIDv7

Introduit dans : v25.8.0

Convertit une valeur DateTime en UUIDv7 pour l’instant donné, tel que défini par la RFC 9562.

Voir la section "Génération des UUIDv7" pour plus de détails sur la structure des UUID, la gestion du compteur et les garanties de concurrence.

Syntaxe

dateTimeToUUIDv7(value)

Arguments

Valeur renvoyée

Renvoie un UUIDv7. UUID

Exemples

Exemple d’utilisation

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

plusieurs UUID pour un même horodatage

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

Introduit dans : v24.6.0

Génère un Snowflake ID.

La fonction generateSnowflakeID garantit que le champ compteur d’un horodatage s’incrémente de manière monotone sur l’ensemble des invocations de la fonction dans des threads et des requêtes exécutés de manière concurrente.

Voir la section "Génération des Snowflake IDs" pour plus de détails sur l’implémentation.

Syntaxe

generateSnowflakeID([expr, [machine_id]])

Arguments

  • expr — Une expression arbitraire utilisée pour contourner l’élimination des sous-expressions communes si la fonction est appelée plusieurs fois dans une requête. La valeur de l’expression n’a aucun effet sur le Snowflake ID renvoyé. Facultatif. - machine_id — Un identifiant de machine ; les 10 bits de poids faible sont utilisés. Int64. Facultatif.

Valeur renvoyée

Renvoie le Snowflake ID. UInt64

Exemples

Exemple d’utilisation

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

INSERT INTO tab SELECT generateSnowflakeID();

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

Plusieurs Snowflake ID générés par ligne

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

Avec une expression et un identifiant de machine

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

generateUUIDv4

Introduite dans : v1.1.0

Génère un UUID de version 4.

Syntaxe

generateUUIDv4([expr])

Arguments

  • expr — Facultatif. Expression arbitraire utilisée pour contourner l’élimination des sous-expressions communes si la fonction est appelée plusieurs fois dans une requête. La valeur de l’expression n’a aucun effet sur l’UUID renvoyé.

Valeur renvoyée

Renvoie un UUIDv4. UUID

Exemples

Exemple d’utilisation

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

Élimination des sous-expressions communes

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

generateUUIDv7

Introduit dans : v24.5.0

Génère un UUID de version 7 tel que défini par la RFC 9562.

Voir la section "Génération des UUIDv7" pour plus de détails sur la structure des UUID, la gestion du compteur et la garantie de concurrence.

Syntaxe

generateUUIDv7([expr])

Arguments

  • expr — Facultatif. Expression arbitraire utilisée pour contourner l'élimination des sous-expressions communes si la fonction est appelée plusieurs fois dans une requête. La valeur de l'expression n'a aucun effet sur l'UUID renvoyé. Any

Valeur renvoyée

Renvoie un UUIDv7. UUID

Exemples

Exemple d'utilisation

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

Élimination des sous-expressions communes

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

snowflakeIDToDateTime

Introduite dans : v24.6.0

Renvoie le composant d’horodatage d’un Snowflake ID sous la forme d’une valeur de type DateTime.

Syntaxe

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

Arguments

  • value — Snowflake ID. UInt64
  • epoch — Facultatif. Époque du Snowflake ID, en millisecondes depuis 1970-01-01. La valeur par défaut est 0 (1970-01-01). Pour l'époque de Twitter/X (2015-01-01), indiquez 1288834974657. UInt*
  • time_zone — Facultatif. Fuseau horaire. La fonction interprète time_string selon le fuseau horaire. String

Valeur renvoyée

Renvoie le composant d'horodatage de value. DateTime

Exemples

Exemple d'utilisation

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

snowflakeIDToDateTime64

Introduit dans : v24.6.0

Renvoie le composant d’horodatage d’un Snowflake ID sous forme d’une valeur de type DateTime64.

Syntaxe

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

Arguments

  • value — Snowflake ID. UInt64
  • epoch — Facultatif. Époque du Snowflake ID en millisecondes depuis le 1970-01-01. La valeur par défaut est 0 (1970-01-01). Pour l’époque Twitter/X (2015-01-01), indiquez 1288834974657. UInt*
  • time_zone — Facultatif. Fuseau horaire. La fonction interprète time_string selon le fuseau horaire. String

Valeur renvoyée

Renvoie le composant d’horodatage de value sous la forme d’un DateTime64 avec scale = 3, c’est-à-dire une précision à la milliseconde. DateTime64

Exemples

Exemple d’utilisation

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

toUUIDOrDefault

Introduit dans : v21.1.0

Convertit une valeur String en UUID. Si la conversion échoue, renvoie une valeur UUID par défaut au lieu de générer une erreur.

Cette fonction tente d’analyser une chaîne de 36 caractères au format UUID standard (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Si la chaîne ne peut pas être convertie en UUID valide, la fonction renvoie la valeur UUID par défaut fournie.

Syntaxe

toUUIDOrDefault(string, default)

Arguments

  • string — Chaîne de 36 caractères ou FixedString(36) à convertir en UUID. - default — valeur UUID à renvoyer si le premier argument ne peut pas être converti en UUID.

Valeur renvoyée

Renvoie l’UUID converti si la conversion réussit, ou l’UUID par défaut en cas d’échec. UUID

Exemples

Une conversion réussie renvoie l’UUID obtenu

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

En cas d’échec de conversion, renvoie l’UUID par défaut

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

Introduit dans : v20.12.0

Convertit une valeur d’entrée en valeur de type UUID, mais renvoie NULL en cas d’erreur.

Comme toUUID, mais renvoie NULL au lieu de lever une exception en cas d’erreur de conversion.

Arguments pris en charge :

  • Représentations sous forme de chaîne d’UUID au format standard (8-4-4-4-12 chiffres hexadécimaux).
  • Représentations sous forme de chaîne d’UUID sans traits d’union (32 chiffres hexadécimaux).

Arguments non pris en charge (renvoient NULL) :

  • Formats de chaîne non valides.
  • Types non chaîne.
  • UUID mal formés.

Syntaxe

toUUIDOrNull(x)

Arguments

  • x — Une représentation sous forme de chaîne d’un UUID. String

Valeur renvoyée

Renvoie une valeur UUID en cas de réussite, sinon NULL. UUID ou NULL

Exemples

Exemples d’utilisation

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