Autres fonctions

Introduit dans : v20.1.0

Renvoie le nom de domaine pleinement qualifié du serveur ClickHouse.

Syntaxe

FQDN()

Alias : fullHostName

Arguments

• Aucun.

Valeur renvoyée

Renvoie le nom de domaine pleinement qualifié du serveur ClickHouse. String

Exemples

Exemple d'utilisation

SELECT fqdn()

┌─FQDN()────────────────────────┐
│ clickhouse.us-east-2.internal │
└───────────────────────────────┘

Introduite dans : v1.1.0

Interprète un nombre UInt64 comme une adresse MAC au format big-endian. Renvoie l’adresse MAC correspondante au format AA:BB:CC:DD:EE:FF (nombres hexadécimaux séparés par des deux-points) sous forme de chaîne.

Syntaxe

MACNumToString(num)

Arguments

• num — nombre de type UInt64. UInt64

Valeur renvoyée

Renvoie une adresse MAC au format AA:BB:CC:DD:EE:FF. String

Exemples

Exemple d'utilisation

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:40:3A:91:07:C4 │
└───────────────────┘

Introduite dans : v1.1.0

MACStringToNum est la fonction inverse de MACNumToString. Si l'adresse MAC a un format invalide, elle renvoie 0.

Syntaxe

MACStringToNum(s)

Arguments

• s — Chaîne d’adresse MAC. String

Valeur renvoyée

Renvoie un nombre UInt64. UInt64

Exemples

Exemple d’utilisation

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

1108152157446

Introduit dans : v1.1.0

Étant donné une adresse MAC au format AA:BB:CC:DD:EE:FF (nombres hexadécimaux séparés par des deux-points), renvoie les trois premiers octets sous la forme d’un nombre UInt64. Si l’adresse MAC n’a pas un format valide, renvoie 0.

Syntaxe

MACStringToOUI(s)

Arguments

• s — adresse MAC sous forme de chaîne. String

Valeur renvoyée

Les trois premiers octets, sous forme de nombre UInt64. UInt64

Exemples

Exemple d’utilisation

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

20566

Introduite dans : v25.11.0

Si l’utilisateur de la session a été remplacé à l’aide de la commande EXECUTE AS, cette fonction renvoie le nom de l’utilisateur d’origine ayant servi à l’authentification et à la création de la session. Alias : authUser()

Syntaxe

authenticatedUser()

Alias : authUser

Arguments

• Aucun.

Valeur renvoyée

Le nom de l’utilisateur authentifié. String

Exemples

Exemple d’utilisation

CREATE USER u1;
EXECUTE AS u1 SELECT currentUser(), authenticatedUser();
DROP USER u1;

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

Introduit dans : v1.1.0

Génère un graphique en barres. Dessine une bande dont la largeur est proportionnelle à (x - min) et égale à width caractères lorsque x = max. La bande est dessinée avec une précision d’un huitième de caractère.

Syntaxe

bar(x, min, max[, width])

Arguments

• x — Taille à afficher. (U)Int* ou Float* ou Decimal
• min — La valeur minimale. (U)Int* ou Float* ou Decimal
• max — La valeur maximale. (U)Int* ou Float* ou Decimal
• width — Facultatif. Largeur de la barre en caractères. La valeur par défaut est 80. const (U)Int* ou const Float* ou const Decimal

Valeur renvoyée

Chaîne de caractères représentant une barre en art Unicode. String

Exemples

Exemple d'utilisation

CREATE TABLE hits (EventTime DateTime('UTC')) ENGINE = Memory;

-- One row per page view, spread over the hours of a day.
INSERT INTO hits
SELECT toDateTime('2026-01-01 00:00:00', 'UTC') + toIntervalHour(hour)
FROM (
    SELECT
        number AS hour,
        [293, 181, 115, 85, 69, 78, 113, 171, 278, 391, 458, 494, 510, 523, 540, 528, 539, 524, 506, 521, 522, 542, 494, 400][number + 1] AS count
    FROM numbers(24)
)
ARRAY JOIN range(count);

SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600, 20) AS bar
FROM hits
GROUP BY h
ORDER BY h ASC

┌──h─┬───c─┬─bar────────────────┐
│  0 │ 293 │ █████████▊         │
│  1 │ 181 │ ██████             │
│  2 │ 115 │ ███▊               │
│  3 │  85 │ ██▊                │
│  4 │  69 │ ██▎                │
│  5 │  78 │ ██▌                │
│  6 │ 113 │ ███▊               │
│  7 │ 171 │ █████▋             │
│  8 │ 278 │ █████████▎         │
│  9 │ 391 │ █████████████      │
│ 10 │ 458 │ ███████████████▎   │
│ 11 │ 494 │ ████████████████▍  │
│ 12 │ 510 │ █████████████████  │
│ 13 │ 523 │ █████████████████▍ │
│ 14 │ 540 │ ██████████████████ │
│ 15 │ 528 │ █████████████████▌ │
│ 16 │ 539 │ █████████████████▉ │
│ 17 │ 524 │ █████████████████▍ │
│ 18 │ 506 │ ████████████████▊  │
│ 19 │ 521 │ █████████████████▎ │
│ 20 │ 522 │ █████████████████▍ │
│ 21 │ 542 │ ██████████████████ │
│ 22 │ 494 │ ████████████████▍  │
│ 23 │ 400 │ █████████████▎     │
└────┴─────┴────────────────────┘

Introduit dans : v1.1.0

Renvoie un numéro de séquence monotone croissant du bloc contenant la ligne. Le numéro de bloc renvoyé est mis à jour au mieux, c’est-à-dire qu’il peut ne pas être parfaitement exact.

Syntaxe

blockNumber()

Arguments

• Aucun.

Valeur renvoyée

Numéro de séquence du bloc de données dans lequel se trouve la ligne. UInt64

Exemples

Utilisation de base

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

┌─blockNumber()─┐
│             6 │
│             6 │
│             7 │
│             7 │
│             8 │
│             8 │
│             9 │
│             9 │
│            10 │
│            10 │
└───────────────┘

Introduit dans : v20.3.0

Renvoie la taille non compressée en octets d’un bloc de valeurs sur disque.

Syntaxe

blockSerializedSize(x1[, x2[, ...]])

Arguments

• x1[, x2, ...] — Nombre quelconque de valeurs dont on souhaite obtenir la taille non compressée du bloc. Any

Valeur renvoyée

Renvoie le nombre d’octets qui seront écrits sur le disque pour un bloc de valeurs sans compression. UInt64

Exemples

Exemple d’utilisation

SELECT blockSerializedSize(maxState(1)) AS x;

┌─x─┐
│ 2 │
└───┘

Introduit dans : v1.1.0

Dans ClickHouse, les requêtes sont traitées par blocs (fragments). Cette fonction renvoie la taille (nombre de lignes) du bloc sur lequel elle est appelée.

Syntaxe

blockSize()

Arguments

• Aucun.

Valeur renvoyée

Renvoyer le nombre de lignes du bloc actuel. UInt64

Exemples

Exemple d'utilisation

SELECT blockSize()
FROM system.numbers LIMIT 5

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

Introduit dans : v20.5.0

Renvoie l’ID de build généré par un compilateur pour le binaire du serveur ClickHouse en cours d’exécution. Si elle est exécutée dans le contexte d’une table distribuée, cette fonction génère une colonne ordinaire avec des valeurs propres à chaque shard. Sinon, elle renvoie une valeur constante.

Syntaxe

buildId()

Arguments

• Aucun.

Valeur renvoyée

Renvoie l’ID de build. String

Exemples

Exemple d’utilisation

SELECT buildId()

┌─buildId()────────────────────────────────┐
│ B49BA4BC500E5E850F832BEC918885516B22FC0E │
└──────────────────────────────────────────┘

Introduit dans : v21.1.0

Renvoie une estimation de la taille en octets non compressée de ses arguments en mémoire. Pour les arguments String, la fonction renvoie la longueur de la chaîne + 8 (longueur). Si la fonction comporte plusieurs arguments, elle additionne leurs tailles en octets.

Syntaxe

byteSize(arg1[, arg2, ...])

Arguments

• arg1[, arg2, ...] — Valeurs de n’importe quel type de données dont il faut estimer la taille non compressée, en octets. Any

Valeur renvoyée

Renvoie une estimation de la taille en octets des arguments en mémoire. UInt64

Exemples

Exemple d’utilisation

SELECT byteSize('string')

┌─byteSize('string')─┐
│                 14 │
└────────────────────┘

Arguments multiples

SELECT byteSize(NULL, 1, 0.3, '')

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         18 │
└────────────────────────────┘

Introduit dans : v22.9.0

Évalue un modèle CatBoost externe. CatBoost est une bibliothèque open-source de gradient boosting développée par Yandex pour le machine learning. Accepte un chemin vers un modèle CatBoost et des arguments du modèle (features).

Prérequis

1. Compiler la bibliothèque d’évaluation CatBoost

Avant d’évaluer des modèles CatBoost, la bibliothèque libcatboostmodel.<so|dylib> doit être accessible. Consultez la documentation CatBoost pour savoir comment la compiler.

Ensuite, indiquez le chemin vers libcatboostmodel.<so|dylib> dans la configuration de ClickHouse :

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

Pour des raisons de sécurité et d'isolation, l'évaluation du modèle ne s'exécute pas dans le processus serveur, mais dans le processus clickhouse-library-bridge. Lors de la première exécution de catboostEvaluate(), le serveur démarre le processus clickhouse-library-bridge s'il n'est pas déjà en cours d'exécution. Les deux processus communiquent via une interface HTTP. Par défaut, le port 9012 est utilisé. Un autre port peut être spécifié comme suit - cela est utile si le port 9012 est déjà attribué à un autre service.

<library_bridge>
    <port>9019</port>
</library_bridge>

2. Entraîner un modèle CatBoost avec libcatboost

Consultez Training and applying models pour savoir comment entraîner des modèles CatBoost à partir d’un jeu de données d’entraînement.

Le fichier du modèle doit se trouver dans le répertoire user_files, comme pour la fonction file.

Syntaxe

catboostEvaluate(path_to_model, feature_1[, feature_2, ..., feature_n])

Arguments

• path_to_model — Chemin vers le modèle CatBoost, situé dans le répertoire user_files. const String
• feature — Une ou plusieurs caractéristiques/arguments du modèle. Float*

Valeur renvoyée

Renvoie le résultat de l’évaluation du modèle. Float64

Exemples

catboostEvaluate

SELECT catboostEvaluate('/var/lib/clickhouse/user_files/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

4.695691092573497

Introduit dans : v26.2.0

Convertit une couleur de l’espace colorimétrique perceptuel OKLab vers l’espace colorimétrique sRGB.

La couleur d’entrée est spécifiée dans l’espace colorimétrique OKLab. Si les valeurs d’entrée sont en dehors des plages OKLab habituelles, le résultat est défini par l’implémentation.

OKLab utilise trois composantes :

• L : luminosité perceptuelle (généralement dans l’intervalle [0..1])
• a : axe d’opposition vert-rouge
• b : axe d’opposition bleu-jaune

Les composantes a et b ne sont théoriquement pas bornées, mais en pratique elles se situent entre -0.4 et 0.4. OKLab est conçu pour être perceptuellement uniforme tout en restant peu coûteux à calculer.

La conversion est conçue pour être l’inverse de colorSRGBToOKLAB et se compose des étapes suivantes :

1. Conversion d’OKLab vers sRGB linéaire.
2. Conversion de sRGB linéaire vers sRGB encodé avec gamma.

L’argument gamma facultatif spécifie l’exposant utilisé lors de la conversion de sRGB linéaire vers des valeurs RGB encodées avec gamma. S’il n’est pas spécifié, une valeur gamma par défaut est utilisée pour garantir la cohérence avec colorSRGBToOKLAB.

Pour plus d’informations sur l’espace colorimétrique OKLab et sa relation avec sRGB, consultez https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab .

Syntaxe

colorOKLABToSRGB(tuple [, gamma])

Arguments

• tuple — Un tuple de trois valeurs numériques L, a, b, où L est compris dans l’intervalle [0...1]. Tuple(Float64, Float64, Float64)
• gamma — Facultatif. L’exposant utilisé pour reconvertir le sRGB linéaire en sRGB en appliquant (x ^ (1 / gamma)) * 255 à chaque canal x. La valeur par défaut est 2.2. Float64

Valeur renvoyée

Renvoie un tuple (R, G, B) représentant des valeurs de couleur sRGB. Tuple(Float64, Float64, Float64)

Exemples

Convertir OKLAB en sRGB (Float)

SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;

┌─rgb──────────────────────┐
│ (198.07056923258935,0,0) │
└──────────────────────────┘

Convertir OKLAB en sRGB (UInt8)

WITH colorOKLABToSRGB((0.7, 0.1, 0.54)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB───────┐
│ (255,0,0) │
└───────────┘

Introduit dans : v25.7.0

Convertit une couleur de l’espace colorimétrique perceptuellement uniforme OKLCH vers l’espace colorimétrique sRGB familier.

Si L est hors de la plage [0...1], si C est négatif, ou si H est hors de la plage [0...360], le résultat est défini par l’implémentation.

La conversion est l’inverse de colorSRGBToOKLCH :

1. D’OKLCH vers OKLab.
2. D’OKLab vers sRGB linéaire
3. De sRGB linéaire vers sRGB

Le second argument gamma est utilisé à la dernière étape.

Pour voir des références de couleurs dans l’espace OKLCH ainsi que leur correspondance avec les couleurs sRGB, consultez https://oklch.com/.

Syntaxe

colorOKLCHToSRGB(tuple [, gamma])

Arguments

• tuple — Un tuple de trois valeurs numériques L, C, H, où L est dans l'intervalle [0...1], C >= 0 et H est dans l'intervalle [0...360]. Tuple(Float64, Float64, Float64)
• gamma — Facultatif. L'exposant utilisé pour reconvertir le sRGB linéaire en sRGB en appliquant (x ^ (1 / gamma)) * 255 à chaque canal x. La valeur par défaut est 2.2. Float64

Valeur renvoyée

Renvoie un tuple (R, G, B) représentant des valeurs de couleur sRGB. Tuple(Float64, Float64, Float64)

Exemples

Convertir OKLCH en sRGB

SELECT colorOKLCHToSRGB((0.6, 0.12, 40)) AS rgb;

┌─rgb───────────────────────────────────────────────────────┐
│ (186.02058688365264,100.68677189684993,71.67819977081575) │
└───────────────────────────────────────────────────────────┘

Convertir OKLCH en sRGB (UInt8)

WITH colorOKLCHToSRGB((0.6, 0.12, 40)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB──────────┐
│ (186,100,71) │
└──────────────┘

Introduit dans : v26.2.0

Convertit une couleur codée dans l’espace colorimétrique sRGB en espace colorimétrique OKLAB, perceptuellement uniforme.

Si un canal d’entrée est en dehors de [0...255] ou si la valeur de gamma n’est pas positive, le comportement est défini par l’implémentation.

La conversion se déroule en deux étapes :

1. sRGB vers sRGB linéaire
2. sRGB linéaire vers OKLab

Syntaxe

colorSRGBToOKLAB(tuple[, gamma])

Arguments

• tuple — Tuple de trois valeurs R, G, B comprises dans l’intervalle [0...255]. Tuple(UInt8, UInt8, UInt8)
• gamma — Facultatif. Exposant utilisé pour linéariser sRGB en appliquant (x / 255)^gamma à chaque canal x. La valeur par défaut est 2.2. Float64

Valeur renvoyée

Renvoie un tuple (L, a, b) représentant les valeurs de l’espace colorimétrique OKLAB. Tuple(Float64, Float64, Float64)

Exemples

Convertir sRGB en OKLAB

SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;

┌─lab──────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.07266246769242975,0.07500108778529994) │
└──────────────────────────────────────────────────────────────┘

Introduit dans : v25.7.0

Convertit une couleur encodée dans l’espace colorimétrique sRGB en espace colorimétrique OKLCH, perceptuellement uniforme.

Si un canal d’entrée est hors de [0...255] ou si la valeur de gamma n’est pas positive, le comportement est défini par l’implémentation.

La conversion se déroule en trois étapes :

1. sRGB vers sRGB linéaire
2. sRGB linéaire vers OKLab
3. OKLab vers OKLCH.

Pour obtenir des références de couleurs dans l’espace OKLCH et voir leur correspondance avec les couleurs sRGB, veuillez consulter https://OKLCH.com/.

Syntaxe

colorSRGBToOKLCH(tuple[, gamma])

Arguments

• tuple — Tuple de trois valeurs R, G, B comprises dans l’intervalle [0...255]. Tuple(UInt8, UInt8, UInt8)
• gamma — Facultatif. Exposant utilisé pour linéariser sRGB en appliquant (x / 255)^gamma à chaque canal x. La valeur par défaut est 2.2. Float64

Valeur renvoyée

Renvoie un tuple (L, C, H) représentant les valeurs dans l’espace colorimétrique OKLCH. Tuple(Float64, Float64, Float64)

Exemples

Convertir sRGB en OKLCH

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;

┌─lch───────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.1044269954567863,45.90734548193018) │
└───────────────────────────────────────────────────────────┘

Introduit dans : v21.3.0

Renvoie l’identifiant de la connexion du client qui a soumis la requête en cours. Cette fonction est particulièrement utile dans les scénarios de débogage. Elle a été créée pour assurer la compatibilité avec la fonction CONNECTION_ID de MySQL. Elle n’est généralement pas utilisée dans les requêtes de production.

Syntaxe

connectionId()

Arguments

• Aucun.

Valeur renvoyée

Renvoie l’ID de connexion du client courant. UInt64

Exemples

Exemple d’utilisation

SELECT connectionId();

┌─connectionId()─┐
│              0 │
└────────────────┘

Introduit dans : v20.8.0

Renvoyer le nombre de chiffres décimaux nécessaires pour représenter une valeur.

Syntaxe

countDigits(x)

Arguments

• x — Une valeur entière ou décimale. (U)Int* ou Decimal

Valeur renvoyée

Renvoie le nombre de chiffres nécessaires pour représenter x. UInt8

Exemples

Exemple d’utilisation

SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
       countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
       countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));

┌─countDigits(toDecimal32(1, 9))─┬─countDigits(toDecimal32(-1, 9))─┬─countDigits(toDecimal64(1, 18))─┬─countDigits(toDecimal64(-1, 18))─┬─countDigits(toDecimal128(1, 38))─┬─countDigits(toDecimal128(-1, 38))─┐
│                             10 │                              10 │                              19 │                               19 │                               39 │                                39 │
└────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

Introduit dans : v1.1.0

Renvoie le nom de la base de données courante. Utile dans les paramètres de moteur de table des requêtes CREATE TABLE, lorsque vous devez spécifier la base de données.

Voir aussi l’instruction SET.

Syntaxe

currentDatabase()

Alias : current_database, DATABASE, SCHEMA

Arguments

• Aucun.

Valeur renvoyée

Renvoie le nom de la base de données courante. String

Exemples

Exemple d'utilisation

SELECT currentDatabase()

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

Syntaxe SQL standard sans parenthèses

SELECT CURRENT_DATABASE

┌─CURRENT_DATABASE─┐
│ default          │
└──────────────────┘

Introduite dans : v26.6.0

Renvoie le nom du gestionnaire HTTP défini en SQL (créé avec CREATE HANDLER) qui a appelé la requête. Renvoie une chaîne vide si la requête n’a pas été appelée par un tel gestionnaire.

Permet de personnaliser le comportement d’une requête selon le gestionnaire qui l’a appelée.

Syntaxe

currentHandler()

Arguments

• Aucun.

Valeur renvoyée

Renvoie le nom du gestionnaire actuel. String

Exemples

Exemple d'utilisation

SELECT currentHandler()

Introduit dans : v21.9.0

Renvoie un tableau des profils de paramètres de l’utilisateur courant.

Syntaxe

currentProfiles()

Arguments

• Aucun.

Valeur renvoyée

Renvoie un tableau de profils de paramètres pour l’utilisateur courant. Array(String)

Exemples

Exemple d’utilisation

SELECT currentProfiles();

┌─currentProfiles()─┐
│ ['default']       │
└───────────────────┘

Introduit dans : v25.2.0

Renvoie l’ID de la requête en cours.

Syntaxe

currentQueryID()

Alias : current_query_id

Arguments

• Aucun argument.

Valeur renvoyée

Exemples

Exemple

SELECT currentQueryID();

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

Introduite dans : v26.6.0

Renvoie l’URL de la requête HTTP (chemin et chaîne de requête) ayant déclenché la requête. Renvoie une chaîne vide si la requête n’a pas été effectuée via HTTP.

Utile, en combinaison avec les gestionnaires HTTP définis en SQL (CREATE HANDLER), pour extraire les paramètres intégrés au chemin de la requête.

Syntaxe

currentRequestURL()

Arguments

• Aucun.

Valeur renvoyée

Renvoie l’URL de la requête HTTP actuelle. String

Exemples

Exemple d’utilisation

SELECT currentRequestURL()

Introduit dans : v21.9.0

Renvoie un tableau contenant les rôles attribués à l’utilisateur courant.

Syntaxe

currentRoles()

Arguments

• Aucun.

Valeur renvoyée

Renvoie un tableau contenant les rôles attribués à l'utilisateur courant. Array(String)

Exemples

Exemple d'utilisation

SELECT currentRoles();

┌─currentRoles()─┐
│ []             │
└────────────────┘

Introduit dans : v23.7.0

Identique à la fonction currentDatabase mais

• accepte un argument booléen qui est ignoré
• renvoie le nom de la base de données dans un tableau ne contenant qu’une seule valeur.

La fonction currentSchemas n’existe que pour assurer la compatibilité avec PostgreSQL. Utilisez plutôt currentDatabase.

Voir aussi l’instruction SET.

Syntaxe

currentSchemas(bool)

Alias : current_schemas

Arguments

• bool — Une valeur booléenne, qui est ignorée. Bool

Valeur renvoyée

Renvoie un tableau à un seul élément contenant le nom de la base de données courante. Array(String)

Exemples

Exemple d'utilisation

SELECT currentSchemas(true)

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

Introduit dans : v20.1.0

Renvoie le nom de l’utilisateur courant. Dans le cas d’une requête distribuée, le nom de l’utilisateur qui a initié la requête est renvoyé.

Syntaxe

currentUser()

Alias : session_user, current_user, user

Arguments

• Aucun.

Valeur renvoyée

Renvoie le nom de l’utilisateur courant ou, à défaut, l’identifiant de l’utilisateur qui a lancé la requête. String

Exemples

Exemple d’utilisation

SELECT currentUser()

┌─currentUser()─┐
│ default       │
└───────────────┘

Syntaxe SQL standard sans parenthèses

SELECT CURRENT_USER

┌─CURRENT_USER─┐
│ default      │
└──────────────┘

Introduit dans : v21.9.0

Renvoie un tableau contenant les noms des profils de paramètres par défaut de l’utilisateur courant.

Syntaxe

defaultProfiles()

Arguments

• Aucun.

Valeur renvoyée

Renvoie un tableau contenant les noms des profils de paramètres par défaut de l’utilisateur courant. Array(String)

Exemples

Exemple d'utilisation

SELECT defaultProfiles();

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

Introduit dans : v21.9.0

Renvoie un tableau des rôles par défaut de l’utilisateur courant.

Syntaxe

defaultRoles()

Arguments

• Aucun.

Valeur renvoyée

Renvoie un tableau des rôles par défaut de l’utilisateur courant. Array(String)

Exemples

Exemple d’utilisation

SELECT defaultRoles();

┌─defaultRoles()─┐
│ []             │
└────────────────┘

Introduit dans : v1.1.0

Renvoie la valeur par défaut d’un type de données donné. N’inclut pas les valeurs par défaut des colonnes personnalisées définies par l’utilisateur.

Syntaxe

defaultValueOfArgumentType(expression)

Arguments

• expression — Valeur de type arbitraire ou expression produisant une valeur de type arbitraire. Any

Valeur renvoyée

Renvoie 0 pour les nombres, une chaîne vide pour les chaînes de caractères ou NULL pour les types Nullable. UInt8 ou String ou NULL

Exemples

Exemple d'utilisation

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

Exemple avec Nullable

SELECT defaultValueOfArgumentType(CAST(1 AS Nullable(Int8)));

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

Introduit dans : v1.1.0

Renvoie la valeur par défaut du nom de type donné.

Syntaxe

defaultValueOfTypeName(type)

Arguments

• type — Une chaîne représentant un nom de type. String

Valeur renvoyée

Renvoie la valeur par défaut pour le nom de type donné : 0 pour les nombres, une chaîne vide pour les chaînes, ou NULL pour UInt8 Nullable, String ou NULL

Exemples

Exemple d'utilisation

SELECT defaultValueOfTypeName('Int8');

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

Exemple de Nullable

SELECT defaultValueOfTypeName('Nullable(Int8)');

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

Introduit dans : v26.7.0

Renvoyer les chiffres d’un nombre n à partir de l’index offset spécifié. Le comptage commence à 1 selon la logique suivante :

• Si offset vaut 0, une exception est levée, car offset est indexé à partir de 1.
• Si offset est négatif, le comptage commence à offset chiffres de la fin du nombre, plutôt que du début.
• Si offset est supérieur au nombre de chiffres de n, 0 est renvoyé.

Un argument facultatif length suit la logique suivante :

• Si length est positif, il indique le nombre de chiffres à prendre à partir de l’offset
• Si length est négatif, il indique le nombre de chiffres à exclure depuis la droite du nombre

Voir également la fonction substring, qui effectue l’opération analogue sur des chaînes de caractères.

Syntaxe

digits(n, offset[, length])

Arguments

• n — Le nombre dont extraire les chiffres. (U)Int8 or (U)Int16 or (U)Int32 or (U)Int64
• offset — La position de départ des chiffres dans n. (U)Int8 or (U)Int16 or (U)Int32 or (U)Int64
• length — Facultatif. Le nombre maximal de chiffres. (U)Int8 or (U)Int16 or (U)Int32 or (U)Int64

Valeur renvoyée

Les chiffres sélectionnés dans n, interprétés comme un UInt64. Renvoie 0 si la plage sélectionnée est vide. Les zéros initiaux ne sont pas conservés. UInt64

Exemples

Décalage positif

SELECT digits(1234567890, 7)

7890

Décalage et longueur positifs

SELECT digits(1234567890, 7, 2)

78

Un décalage négatif se compte à partir de la droite

SELECT digits(1234567890, -3)

890

Une longueur négative exclut des chiffres en partant de la droite

SELECT digits(1234567890, 3, -2)

345678

Un décalage au-delà de la fin renvoie 0

SELECT digits(1234567890, 11)

0

Introduit dans : v22.11.0

Renvoie la valeur de display_name dans config ou, si elle n’est pas définie, le nom de domaine pleinement qualifié (FQDN) du serveur.

Syntaxe

displayName()

Arguments

• Aucun.

Valeur renvoyée

Renvoie la valeur de display_name dans la config ou, si elle n’est pas définie, le FQDN du serveur. String

Exemples

Exemple d’utilisation

SELECT displayName();

┌─displayName()─┐
│ production    │
└───────────────┘

Introduit dans : v1.1.0

Affiche une description détaillée de la structure interne d’une colonne et de son type de données.

Syntaxe

dumpColumnStructure(x)

Arguments

• x — Valeur dont il faut obtenir la description. Any

Valeur renvoyée

Renvoie une description de la structure de colonne servant à représenter la valeur. String

Exemples

Exemple d'utilisation

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'));

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

Introduit dans : v21.9.0

Renvoie un tableau contenant les noms des profils de paramètres activés pour l’utilisateur courant.

Syntaxe

enabledProfiles()

Arguments

• Aucun.

Valeur renvoyée

Renvoie un tableau contenant les noms des profils de paramètres activés pour l’utilisateur courant. Array(String)

Exemples

Exemple d’utilisation

SELECT enabledProfiles();

┌─enabledProfiles()─┐
│ ['default']       │
└───────────────────┘

Introduit dans : v21.9.0

Renvoie un tableau des rôles activés pour l’utilisateur courant.

Syntaxe

enabledRoles()

Arguments

• Aucun.

Valeur renvoyée

Renvoie un tableau contenant les noms des rôles activés pour l’utilisateur courant. Array(String)

Exemples

Exemple d’utilisation

SELECT enabledRoles();

┌─enabledRoles()─┐
│ []             │
└────────────────┘

Introduit dans : v20.12.0

Renvoyer le nom textuel d’un code d’erreur numérique ClickHouse. La correspondance entre les codes d’erreur numériques et les noms d’erreur est disponible ici.

Syntaxe

errorCodeToName(error_code)

Arguments

• error_code — Code d’erreur ClickHouse. (U)Int* ou Float* ou Decimal

Valeur renvoyée

Renvoie le nom textuel de error_code. String

Exemples

Exemple d’utilisation

SELECT errorCodeToName(252);

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

Introduit dans : v21.3.0

Lit un fichier sous forme de chaîne de caractères et charge les données dans la colonne spécifiée. Le contenu du fichier n'est pas interprété.

Voir aussi la fonction de table file.

Syntaxe

file(path[, default])

Arguments

• path — Le chemin du fichier par rapport à user_files_path. Prend en charge les caractères génériques *, **, ?, {abc,def} et {N..M}, où N et M sont des nombres et 'abc', 'def' des chaînes. String
• default — La valeur renvoyée si le fichier n'existe pas ou n'est pas accessible. String ou NULL

Valeur renvoyée

Renvoie le contenu du fichier sous forme de chaîne de caractères. String

Exemples

Insérer des fichiers dans une table

INSERT INTO FUNCTION file('a.txt', 'RawBLOB') SELECT 'Hello' SETTINGS engine_file_truncate_on_insert = 1;
INSERT INTO FUNCTION file('b.txt', 'RawBLOB') SELECT 'World!' SETTINGS engine_file_truncate_on_insert = 1;

CREATE TABLE data (a String, b String) ENGINE = Memory;
INSERT INTO data SELECT file('a.txt'), file('b.txt');

SELECT * FROM data;

┌─a─────┬─b──────┐
│ Hello │ World! │
└───────┴────────┘

Introduit dans : v20.1.0

Renvoie la quantité d’espace libre dans le système de fichiers qui héberge le stockage persistant de la base de données. La valeur renvoyée est toujours inférieure à l’espace libre total (filesystemUnreserved), car une partie de cet espace est réservée au système d’exploitation.

Syntaxe

filesystemAvailable([disk_name])

Arguments

• disk_name — Facultatif. Nom du disque dont il faut déterminer l’espace libre. S’il est omis, le disque par défaut est utilisé. String ou FixedString

Valeur renvoyée

Renvoie l’espace libre restant en octets. UInt64

Exemples

Exemple d’utilisation

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

Introduit dans : v20.1.0

Renvoie la capacité du système de fichiers en octets. Nécessite que le path vers le répertoire de données soit configuré.

Syntaxe

filesystemCapacity([disk_name])

Arguments

• disk_name — Facultatif. Nom du disque dont il faut obtenir la capacité. S'il est omis, le disque par défaut est utilisé. String ou FixedString

Valeur renvoyée

Renvoie la capacité du système de fichiers en octets. UInt64

Exemples

Exemple d'utilisation

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

Introduit dans : v22.12.0

Renvoie la quantité totale d’espace libre sur le système de fichiers qui héberge le stockage persistant de la base de données (anciennement filesystemFree). Voir aussi filesystemAvailable.

Syntaxe

filesystemUnreserved([disk_name])

Arguments

• disk_name — Facultatif. Nom du disque pour lequel trouver la quantité totale d’espace libre. S’il est omis, le disque par défaut est utilisé. String ou FixedString

Valeur renvoyée

Renvoie la quantité d’espace libre en octets. UInt64

Exemples

Exemple d’utilisation

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

Introduit dans : v1.1.0

À partir d’un état d’agrégation, cette fonction renvoie le résultat de l’agrégation (ou l’état finalisé lorsqu’un combinateur -State est utilisé).

Syntaxe

finalizeAggregation(state)

Arguments

• state — État de l’agrégation. AggregateFunction

Valeur renvoyée

Renvoie le résultat final de l’agrégation. Any

Exemples

Exemple d’utilisation

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

┌─finalizeAggregation(arrayReduce('maxState', [1, 2, 3]))─┐
│                                                       3 │
└─────────────────────────────────────────────────────────┘

Combiné à initializeAggregation

SET allow_deprecated_error_prone_window_functions = 1;
WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

Introduite dans : v25.11.0

Inverse les coordonnées x et y des objets géométriques. Cette opération permute la latitude et la longitude, ce qui est utile pour passer d’un système de coordonnées à un autre ou corriger l’ordre des coordonnées.

Pour un Point, elle permute les coordonnées x et y. Pour les géométries complexes (MultiPoint, LineString, Polygon, MultiPolygon, Ring, MultiLineString), elle applique récursivement la transformation à chaque paire de coordonnées.

La fonction prend en charge à la fois les types géométriques individuels (Point, MultiPoint, Ring, Polygon, MultiPolygon, LineString, MultiLineString) et le type Variant Geometry.

Syntaxe

flipCoordinates(geometry)

Arguments

• geometry — Géométrie à transformer. Types pris en charge : Point (Tuple(Float64, Float64)), MultiPoint (Array(Point)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)) ou Geometry (un variant contenant l’un de ces types).

Valeur renvoyée

La géométrie dont les coordonnées sont permutées. Le type de retour correspond au type d’entrée. Point ou MultiPoint ou Ring ou Polygon ou MultiPolygon ou LineString ou MultiLineString ou Geometry

Exemples

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2,1)

Ring

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

[(2,1),(4,3)]

Polygon

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

[[(2,1),(4,3)],[(6,5),(8,7)]]

geometry_wkt

SELECT flipCoordinates(readWkt('POINT(10 20)'));

(20,10)

geometry_polygon_wkt

SELECT flipCoordinates(readWkt('POLYGON((0 0, 5 0, 5 5, 0 5, 0 0))'));

[[(0,0),(0,5),(5,5),(5,0),(0,0)]]

Introduit dans : v23.10.0

Renvoie une version formatée, éventuellement sur plusieurs lignes, de la requête SQL fournie. Déclenche une erreur en cas d’erreur d’analyse syntaxique. [example:multiline]

Syntaxe

formatQuery(query)

Arguments

• query — La requête SQL à formater. String

Valeur renvoyée

La requête formatée String

Exemples

multiligne

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

Introduite dans : v26.8.0

Prend une représentation JSON d’un AST SQL (tel que produit par parseQueryToJSON) et la reformate en une chaîne de requête SQL.

Avec un argument, produit du SQL au format canonique. Avec deux arguments (json, original_query), préserve au mieux les commentaires, les espaces et l’indentation de la requête d’origine.

L’AST désérialisé est limité par les paramètres max_ast_depth et max_ast_elements de la session en cours. Associée à parseQueryToJSON, cette fonction permet d’inspecter et de transformer des requêtes par programmation via leur représentation sous forme d’AST JSON.

Syntaxe

formatQueryFromJSON(json[, original_query])

Arguments

• json — Chaîne JSON représentant un AST SQL. String
• original_query — Facultatif. Requête SQL d’origine dont la mise en forme doit être préservée. String

Valeur renvoyée

Chaîne de requête SQL. String

Exemples

Aller-retour

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'));

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'))─┐
│ SELECT a, b FROM t WHERE x > 1                                          │
└─────────────────────────────────────────────────────────────────────────┘

Préserver le formatage

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t');

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t')─┐
│ SELECT /* comment */ a FROM t                                                             │
└───────────────────────────────────────────────────────────────────────────────────────────┘

Introduit dans : v23.11.0

Renvoie une version formatée, éventuellement sur plusieurs lignes, de la requête SQL fournie. Renvoie NULL en cas d'erreur d’analyse syntaxique. [example:multiline]

Syntaxe

formatQueryOrNull(query)

Arguments

• query — La requête SQL à formater. String

Valeur renvoyée

La requête formatée String

Exemples

multiligne

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

Introduit dans : v23.10.0

Comme formatQuery(), mais la chaîne formatée renvoyée ne contient aucun saut de ligne. Lève une exception en cas d'erreur d’analyse syntaxique. [example:multiline]

Syntaxe

formatQuerySingleLine(query)

Arguments

• query — La requête SQL à formater. String

Valeur renvoyée

La requête formatée String

Exemples

multiligne

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

Introduit dans : v23.11.0

Comme formatQuery(), mais la chaîne formatée renvoyée ne contient aucun saut de ligne. Renvoie NULL en cas d’erreur d’analyse syntaxique. [example:multiline]

Syntaxe

formatQuerySingleLineOrNull(query)

Arguments

• query — La requête SQL à formater. String

Valeur renvoyée

La requête formatée String

Exemples

multiligne

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

Introduit dans : v22.11.0

À partir d’une taille (nombre d’octets), cette fonction renvoie une taille lisible et arrondie avec un suffixe (KB, MB, etc.), sous forme de chaîne.

Les opérations inverses de cette fonction sont parseReadableSize.

Syntaxe

formatReadableDecimalSize(value[, precision])

Arguments

• value — Taille en octets. Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• precision — Facultatif. Nombre de chiffres après la virgule. La valeur par défaut est 2. const UInt8

Valeur renvoyée

Renvoie une taille lisible et arrondie avec un suffixe, sous forme de chaîne. String

Exemples

Formater les tailles de fichier

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize──┐
│              1 │ 1.00 B    │
│           1024 │ 1.02 KB   │
│        1048576 │ 1.05 MB   │
│      192851925 │ 192.85 MB │
└────────────────┴───────────┘

Avec une précision explicite

SELECT
    formatReadableDecimalSize(192851925, 0) AS no_decimals,
    formatReadableDecimalSize(192851925, 4) AS four_decimals

┌─no_decimals─┬─four_decimals─┐
│ 193 MB      │ 192.8519 MB   │
└─────────────┴───────────────┘

Introduit dans : v20.10.0

Étant donné un nombre, cette fonction renvoie une valeur arrondie avec un suffixe (mille, million, milliard, etc.) sous forme de chaîne.

Cette fonction accepte en entrée n’importe quel type numérique, mais le convertit en interne en Float64. Les résultats peuvent être moins précis pour les grandes valeurs.

Syntaxe

formatReadableQuantity(value[, precision])

Arguments

• value — Un nombre à formater. Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• precision — Facultatif. Nombre de chiffres après le séparateur décimal. Valeur par défaut : 2. const UInt8

Valeur renvoyée

Renvoie un nombre arrondi avec un suffixe, sous forme de chaîne. String

Exemples

Formater des nombres avec des suffixes

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

Avec une précision explicite

SELECT
    formatReadableQuantity(98765432101234, 0) AS no_decimals,
    formatReadableQuantity(98765432101234, 4) AS four_decimals

┌─no_decimals─┬─four_decimals────┐
│ 99 trillion │ 98.7654 trillion │
└─────────────┴──────────────────┘

Introduit dans : v1.1.0

À partir d’une taille (nombre d’octets), cette fonction renvoie une taille lisible et arrondie avec un suffixe (KiB, MiB, etc.) sous forme de chaîne.

Les opérations inverses de cette fonction sont parseReadableSize, parseReadableSizeOrZero et parseReadableSizeOrNull. Cette fonction accepte en entrée n’importe quel type numérique, mais les convertit en interne en Float64. Les résultats peuvent être moins précis avec de grandes valeurs.

Syntaxe

formatReadableSize(value[, precision])

Alias : FORMAT_BYTES

Arguments

• value — Taille en octets. Int8 ou Int16 ou Int32 ou Int64 ou UInt8 ou UInt16 ou UInt32 ou UInt64 ou Float32 ou Float64 ou Decimal
• precision — Facultatif. Nombre de chiffres après la virgule. La valeur par défaut est 2. const UInt8

Valeur renvoyée

Renvoie une taille lisible et arrondie avec suffixe, sous forme de chaîne. String

Exemples

Formater les tailles de fichiers

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

Avec une précision explicite

SELECT
    formatReadableSize(192851925, 0) AS no_decimals,
    formatReadableSize(192851925, 4) AS four_decimals

┌─no_decimals─┬─four_decimals─┐
│ 184 MiB     │ 183.9179 MiB  │
└─────────────┴───────────────┘

Introduit dans : v20.12.0

Étant donné un intervalle de temps (delta) en secondes ou une expression INTERVAL, cette fonction renvoie un delta temporel sous forme de chaîne, avec année/mois/jour/heure/minute/seconde/milliseconde/microseconde/nanoseconde.

Cette fonction accepte n'importe quel type numérique en entrée, mais les convertit en interne en Float64. Les résultats peuvent être moins précis avec des valeurs élevées.

Lorsqu'une expression INTERVAL est transmise, sa valeur est convertie en secondes. Les unités d'intervalle MONTH et supérieures (MONTH, QUARTER, YEAR) ne sont pas prises en charge, car elles ne représentent pas un intervalle de durée fixe en secondes.

Syntaxe

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

Arguments

• column — Une colonne contenant un écart de temps numérique, ou une expression INTERVAL. Les unités d’intervalle MONTH et supérieures ne sont pas prises en charge. Float64 ou Interval
• maximum_unit — Facultatif. Unité maximale à afficher. Valeurs acceptables : nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Valeur par défaut : years. const String
• minimum_unit — Facultatif. Unité minimale à afficher. Toutes les unités plus petites sont tronquées. Valeurs acceptables : nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. Si la valeur explicitement spécifiée est supérieure à maximum_unit, une exception est levée. Valeur par défaut : seconds si maximum_unit vaut seconds ou une unité supérieure, nanoseconds sinon. const String

Valeur renvoyée

Renvoie un écart de temps sous forme de chaîne. String

Exemples

Exemple d’utilisation

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

┌───elapsed─┬─time_delta──────────────────────────────────────────────────────┐
│       100 │ 1 minute and 40 seconds                                         │
│     12345 │ 3 hours, 25 minutes and 45 seconds                              │
│ 432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds │
└───────────┴─────────────────────────────────────────────────────────────────┘

Avec l’unité maximale

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

┌───elapsed─┬─time_delta─────────────────────┐
│       100 │ 1 minute and 40 seconds        │
│     12345 │ 205 minutes and 45 seconds     │
│ 432546534 │ 7209108 minutes and 54 seconds │
└───────────┴────────────────────────────────┘

Avec l’expression INTERVAL

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

┌─time_delta─────────────────────────┐
│ 3 hours, 25 minutes and 45 seconds │
└────────────────────────────────────┘

Introduite dans : v26.2.0

Analyse la chaîne de requête fournie et lui applique des mutations aléatoires de l’AST (fuzzing). Renvoie la requête modifiée sous forme de chaîne de caractères. Non déterministe : chaque appel peut produire un résultat différent. Nécessite allow_fuzz_query_functions = 1.

Syntaxe

fuzzQuery(query)

Arguments

• query — La requête SQL à soumettre au fuzzing. String

Valeur renvoyée

La chaîne de requête fuzzée String

Exemples

simple

SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');

Introduit dans : v23.5.0

Génère une structure de table aléatoire au format column1_name column1_type, column2_name column2_type, ....

Syntaxe

generateRandomStructure([number_of_columns, seed])

Arguments

• number_of_columns — Le nombre souhaité de colonnes dans la structure de table générée. S'il est défini sur 0 ou Null, le nombre de colonnes sera choisi aléatoirement entre 1 et 128. Valeur par défaut : Null. UInt64
• seed — Graine aléatoire utilisée pour produire des résultats stables. Si la graine n'est pas spécifiée ou si elle est définie sur Null, elle est générée aléatoirement. UInt64

Valeur renvoyée

Structure de table générée aléatoirement. String

Exemples

Exemple d'utilisation

SELECT generateRandomStructure()

c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime

avec le nombre de colonnes indiqué

SELECT generateRandomStructure(1)

c1 Map(UInt256, UInt16)

avec la graine spécifiée

SELECT generateRandomStructure(NULL, 33)

c1 DateTime, c2 Enum8(\'c2V0\' = -123, \'c2V1\' = 94, \'c2V2\' = -105, \'c2V3\' = 67), c3 Nullable(UInt8), c4 String, c5 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(71))), c6 UInt32, c7 Bool, c8 Float64

Introduit dans : v25.1.0

Génère et renvoie des nombres séquentiels à partir de la valeur précédente du compteur. Cette fonction prend un argument de type String — un identifiant de série — ainsi qu’une valeur initiale facultative. Le serveur doit être configuré avec Keeper. Les séries sont stockées dans des nœuds Keeper sous le chemin, qui peut être configuré via series_keeper_path dans la configuration du serveur.

Syntaxe

generateSerialID(series_identifier[, start_value])

Arguments

• series_identifier — Identifiant de série const String
• start_value — Facultatif. Valeur initiale du compteur. La valeur par défaut est 0. Remarque : cette valeur n’est utilisée que lors de la création d’une nouvelle série et est ignorée si la série existe déjà UInt*

Valeur renvoyée

Renvoie des nombres séquentiels à partir de la valeur précédente du compteur. UInt64

Exemples

premier appel

SELECT generateSerialID('id1')

┌─generateSerialID('id1')─┐
│                       0 │
└─────────────────────────┘

deuxième appel

SELECT generateSerialID('id1')

┌─generateSerialID('id1')─┐
│                       1 │
└─────────────────────────┘

appel de la colonne

CREATE TABLE test_table (CounterID UInt32, UserID UInt32, ver UInt32) ENGINE = Memory;
INSERT INTO test_table VALUES (1, 3, 3), (1, 1, 1), (1, 2, 2), (1, 5, 5), (1, 4, 4);

SELECT *, generateSerialID('id1') FROM test_table

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')─┐
│         1 │      3 │   3 │                       2 │
│         1 │      1 │   1 │                       3 │
│         1 │      2 │   2 │                       4 │
│         1 │      5 │   5 │                       5 │
│         1 │      4 │   4 │                       6 │
└───────────┴────────┴─────┴─────────────────────────┘

avec une valeur initiale

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)─┐
│                          100 │
└──────────────────────────────┘

avec valeur initiale, deuxième appel

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)─┐
│                          101 │
└──────────────────────────────┘

Introduit dans : v24.5.0

Renvoie la valeur d'un en-tête HTTP. S'il n'existe pas d'en-tête de ce type ou si la requête en cours n'est pas effectuée via l'interface HTTP, la fonction renvoie une chaîne vide. Certains en-têtes HTTP (par ex., Authorization, Authentication et X-ClickHouse-*) sont soumis à des restrictions.

Les en-têtes HTTP sont insensibles à la casse conformément à la RFC 9110. Si la fonction est utilisée dans le contexte d'une requête distribuée, elle ne renvoie un résultat non vide que sur le nœud initiateur.

getClientHTTPHeader lit les en-têtes de la requête en cours ; elle ne renvoie donc une valeur non vide que lorsque la requête est envoyée via l'interface HTTP. Par exemple, fournissez l'en-tête dans la requête et relisez-le via HTTP :

echo "SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1" | \
    curl 'http://localhost:8123/' --data-binary @- -H 'Content-Type: application/x-www-form-urlencoded'

La commande ci-dessus renvoie application/x-www-form-urlencoded.

Syntaxe

getClientHTTPHeader(name)

Arguments

• name — Le nom de l’en-tête HTTP. String

Valeur renvoyée

Renvoie la valeur de l’en-tête. String

Exemples

Exemple d’utilisation

-- Over a non-HTTP interface (such as `clickhouse-client` or `clickhouse-local`) there are
-- no request headers, so the function returns an empty string. See the description above
-- for an HTTP example that returns the actual header value.
SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1

Introduit dans : v20.1.0

Renvoie la valeur d’une macro du fichier de configuration du serveur. Les macros sont définies dans la section <macros> du fichier de configuration et peuvent être utilisées pour distinguer les serveurs à l’aide de noms explicites, même si leurs noms d’hôte sont complexes. Si la fonction est exécutée dans le contexte d’une table distribuée, elle génère une colonne normale avec des valeurs correspondant à chaque fragment.

Syntaxe

getMacro(name)

Arguments

• name — Le nom de la macro à récupérer. const String

Valeur renvoyée

Renvoie la valeur de la macro spécifiée. String

Exemples

Utilisation de base

SELECT getMacro('test');

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

Introduit dans : v25.1.0

Renvoie la longueur maximale d’un nom de table dans une base de données donnée.

Syntaxe

getMaxTableNameLengthForDatabase(database_name)

Arguments

• database_name — Nom de la base de données spécifiée. String

Valeur renvoyée

Renvoie la longueur maximale d’un nom de table, sous forme d’entier

Exemples

type

SELECT getMaxTableNameLengthForDatabase('default');

┌─getMaxTableNameLengthForDatabase('default')─┐
│                                         206 │
└─────────────────────────────────────────────┘

Introduit dans : v25.6.0

Renvoie la valeur actuelle d’un paramètre MergeTree.

Syntaxe

getMergeTreeSetting(setting_name)

Arguments

• setting_name — Nom du paramètre. String

Valeur renvoyée

Renvoie la valeur actuelle du paramètre MergeTree.

Exemples

Exemple d’utilisation

SELECT getMergeTreeSetting('index_granularity');

┌─getMergeTreeSetting('index_granularity')─┐
│                                     8192 │
└──────────────────────────────────────────┘

Introduit dans : v21.11.0

Renvoie une chaîne de caractères contenant la version du noyau du système d’exploitation.

Syntaxe

getOSKernelVersion()

Arguments

• Aucun.

Valeur renvoyée

Renvoie la version actuelle du noyau du système d’exploitation. String

Exemples

Exemple d’utilisation

SELECT getOSKernelVersion();

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

Introduit dans : v21.10.0

Renvoie le numéro de port du serveur pour un protocole donné.

Syntaxe

getServerPort(port_name)

Arguments

• port_name — Le nom du port. String

Valeur renvoyée

Renvoie le numéro de port du serveur. UInt16

Exemples

Exemple d'utilisation

SELECT getServerPort('tcp_port');

┌─getServerPort('tcp_port')─┐
│                      9000 │
└───────────────────────────┘

Introduit dans : v25.6.0

Renvoie la valeur actuellement définie pour le paramètre serveur indiqué.

Syntaxe

getServerSetting(setting_name')

Arguments

• setting_name — Le nom du paramètre du serveur. String

Valeur renvoyée

Renvoie la valeur actuelle du paramètre du serveur. Any

Exemples

Exemple d'utilisation

SELECT getServerSetting('allow_use_jemalloc_memory');

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

Introduit dans : v20.7.0

Renvoie la valeur actuelle d’un paramètre.

Syntaxe

getSetting(setting_name)

Arguments

• setting_Name — Le nom du paramètre. const String

Valeur renvoyée

Renvoie la valeur actuelle du paramètre. Any

Exemples

Exemple d'utilisation

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

┌─getSetting('enable_analyzer')─┐
│ true                          │
└───────────────────────────────┘
┌─getSetting('enable_analyzer')─┐
│ false                         │
└───────────────────────────────┘

Introduit dans : v24.10.0

Renvoie la valeur actuelle d’un paramètre, ou la valeur par défaut spécifiée dans le deuxième argument si le paramètre n’est pas défini dans le profil actuel.

Syntaxe

getSettingOrDefault(setting_name, default_value)

Arguments

• setting_name — Le nom du paramètre. String
• default_value — Valeur à renvoyer si custom_setting n’est pas défini. La valeur peut être de n’importe quel type de données ou de NULL.

Valeur renvoyée

Renvoie la valeur actuelle du paramètre spécifié ou default_value si le paramètre n’est pas défini.

Exemples

Exemple d’utilisation

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

my_value
100
\N

Introduit dans : v1.1.0

Renvoie le nombre de champs de l’Enum donné.

Syntaxe

getSizeOfEnumType(x)

Arguments

• x — Valeur de type Enum. Enum

Valeur renvoyée

Renvoie le nombre de champs dont les valeurs d’entrée sont de type Enum. UInt8/16

Exemples

Exemple d’utilisation

SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;

┌─x─┐
│ 2 │
└───┘

Introduit dans : v23.3.0

Reçoit l’expression ou l’identifiant, ainsi qu’une chaîne constante contenant le nom de la sous-colonne.

Renvoie la sous-colonne demandée extraite de l’expression.

Syntaxe

getSubcolumn(nested_value, subcolumn_name)

Arguments

• Aucun.

Valeur renvoyée

Exemples

getSubcolumn

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')
FROM values('array_col Array(UInt32), tuple_col Tuple(elem_name String)', ([1, 2, 3], tuple('abc')));

┌─getSubcolumn(array_col, 'size0')─┬─getSubcolumn(tuple_col, 'elem_name')─┐
│                                3 │ abc                                  │
└──────────────────────────────────┴──────────────────────────────────────┘

Introduit dans : v22.6.0

Répertorie les chemins des flux de sérialisation d’un type de données. Cette fonction est destinée à un usage de développement.

Syntaxe

getTypeSerializationStreams(col)

Arguments

• col — Colonne ou représentation sous forme de chaîne d’un type de données à partir de laquelle le type de données sera détecté. Any

Valeur renvoyée

Renvoie un tableau contenant tous les chemins des sous-flux de sérialisation. Array(String)

Exemples

tuple

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))

['{TupleElement(1), InlinedStringSizes()}','{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), InlinedStringSizes()}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

map

SELECT getTypeSerializationStreams('Map(String, Int64)')

['{ArraySizes}','{ArrayElements, TupleElement(keys), InlinedStringSizes()}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

Introduit dans : v20.5.0

Prend un argument String constant et renvoie la valeur de la variable globale portant ce nom. Cette fonction est destinée à assurer la compatibilité avec MySQL et n'est ni nécessaire ni utile au fonctionnement normal de ClickHouse. Seules quelques variables globales factices sont définies.

Syntaxe

globalVariable(name)

Arguments

• name — Nom de variable globale. String

Valeur renvoyée

Renvoie la valeur de la variable name. Any

Exemples

globalVariable

SELECT globalVariable('max_allowed_packet')

67108864

Introduit dans : v1.1.0

Vérifie si une colonne spécifique existe dans une table d’une base de données. Pour les éléments d’une structure de données imbriquée, la fonction vérifie l’existence d’une colonne. Pour la structure de données imbriquée elle-même, la fonction renvoie 0.

Syntaxe

hasColumnInTable(database, table, column)

Arguments

• database — Nom de la base de données. const String
• table — Nom de la table. const String
• column — Nom de la colonne. const String

Valeur renvoyée

Renvoie 1 si la colonne indiquée existe, 0 sinon. UInt8

Exemples

Vérifier l'existence d'une colonne

SELECT hasColumnInTable('system','metrics','metric')

1

Vérifier une colonne qui n’existe pas

SELECT hasColumnInTable('system','metrics','non-existing_column')

0

Introduit dans : v20.6.0

Indique si le thread fuzzer est activé. Cette fonction n’est utile que pour les tests et le débogage.

Syntaxe

hasThreadFuzzer()

Arguments

• Aucun.

Valeur renvoyée

Indique si le Thread Fuzzer est actif. UInt8

Exemples

Vérifier le statut du Thread Fuzzer

SELECT hasThreadFuzzer()

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

Introduit dans : v26.5.0

Analyse une chaîne de requête SQL ClickHouse et renvoie un tableau de plages mises en surbrillance pour la coloration syntaxique. Chaque plage est un tuple nommé contenant la position de début (en octets), la position de fin et le type de surbrillance. Les types de surbrillance décrivent le rôle syntaxique du fragment (mot-clé, identifiant, fonction, etc.) et peuvent être utilisés pour attribuer des couleurs dans une UI. Dans les motifs de chaîne LIKE et REGEXP, les métacaractères et les caractères d’échappement sont mis en surbrillance séparément.

Syntaxe

highlightQuery(query)

Arguments

• query — Une chaîne de requête SQL ClickHouse. String.

Valeur renvoyée

Un tableau de tuples nommés (begin UInt64, end UInt64, type Enum8(...)) représentant des plages mises en évidence. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

Exemples

simple

SELECT highlightQuery('SELECT 1')

[(0,6,'keyword'),(7,8,'number')]

Introduit dans : v20.5.0

Renvoie le nom de l’hôte sur lequel cette fonction a été exécutée. Si la fonction s’exécute sur un serveur distant (traitement distribué), le nom du serveur distant est renvoyé. Si la fonction s’exécute dans le contexte d’une table distribuée, elle génère une colonne normale avec des valeurs correspondant à chaque shard. Sinon, elle produit une valeur constante.

Syntaxe

hostName()

Alias : hostname

Arguments

• Aucun.

Valeur renvoyée

Renvoie le nom d’hôte. String

Exemples

Exemple d’utilisation

SELECT hostName()

┌─hostName()─┐
│ clickhouse │
└────────────┘

Introduit dans : v25.5.0

Implémente la logique de la transformation bucket d’Iceberg

Syntaxe

icebergBucket(N, value)

Arguments

• N — Le nombre de buckets (modulo). const (U)Int*
• value — La valeur source à transformer. (U)Int* ou Bool ou Decimal ou Float* ou String ou FixedString ou UUID ou Date ou Time ou DateTime

Valeur renvoyée

Renvoie un hachage de 32 bits de la valeur source. Int32

Exemples

Exemple

SELECT icebergBucket(5, 1.0 :: Float32)

4

Introduit dans : v25.3.0

Implémente la logique de la transformation TRUNCATE d’Iceberg : https://iceberg.apache.org/spec/#truncate-transform-details.

Syntaxe

icebergTruncate(N, value)

Arguments

• value — La valeur à convertir. String ou (U)Int* ou Decimal

Valeur renvoyée

Le même type que l’argument

Exemples

Exemple

SELECT icebergTruncate(3, 'iceberg')

ice

Introduit dans : v1.1.0

Cette fonction renvoie l’argument que vous lui passez, ce qui est utile pour le débogage et les tests. Elle vous permet de contourner l’utilisation des index afin d’observer à la place les performances d’un parcours complet. L’analyseur de requêtes ignore tout ce qui se trouve à l’intérieur des fonctions identity lorsqu’il recherche les index à utiliser, et désactive également le constant folding.

Syntaxe

identity(x)

Arguments

• x — Valeur d’entrée. Any

Valeur renvoyée

Renvoie la valeur d’entrée inchangée. Any

Exemples

Exemple d’utilisation

SELECT identity(42)

42

Introduit dans : v1.1.0

Accepte n’importe quels arguments et renvoie toujours 0.

Syntaxe

ignore(x)

Arguments

• x — Une valeur d’entrée non utilisée, transmise uniquement pour éviter une erreur de syntaxe. Any

Valeur renvoyée

Renvoie toujours 0. UInt8

Exemples

Exemple d’utilisation

SELECT ignore(0, 'ClickHouse', NULL)

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

Introduit dans : v1.1.0

Cette fonction est destinée au débogage et à l’introspection. Elle ignore son argument et renvoie toujours 1. Les arguments ne sont pas évalués.

Lors de l’analyse de l’index, on suppose que l’argument de cette fonction n’est pas encapsulé dans indexHint. Cela vous permet de sélectionner des données dans des plages d’index à l’aide de la condition correspondante, mais sans filtrage supplémentaire sur cette condition. L’index de ClickHouse est sparse, et l’utilisation de indexHint renverra plus de données que si vous spécifiez directement la même condition.

SELECT * FROM test WHERE key = 123;

SELECT * FROM test WHERE indexHint(key = 123);

Remarque : il n’est pas possible d’optimiser une requête avec la fonction indexHint. La fonction indexHint n’optimise pas la requête, car elle ne fournit aucune information supplémentaire pour l’analyse de la requête. Mettre une expression à l’intérieur de la fonction indexHint n’est en aucun cas préférable à ne pas utiliser la fonction indexHint. La fonction indexHint ne peut être utilisée qu’à des fins d’introspection et de débogage, et n’améliore pas les performances. Si vous voyez indexHint utilisé par quelqu’un d’autre que les contributeurs de ClickHouse, il s’agit probablement d’une erreur et vous devriez le supprimer.

Syntaxe

indexHint(expression)

Arguments

• expression — Toute expression utilisée pour la sélection de plages d’index. Expression

Valeur renvoyée

Renvoie 1 dans tous les cas. UInt8

Exemples

Exemple d’utilisation avec filtrage sur la date

-- `index_granularity` is lowered to 8 here only to keep the example small enough to follow.
-- Do not change it in production: the default of 8192 is what makes the index sparse and cheap,
-- and a small value makes the index large and slows queries down.
CREATE TABLE ontime (FlightDate Date, Carrier String)
ENGINE = MergeTree ORDER BY FlightDate
SETTINGS index_granularity = 8;

-- Ten flights on each of four days, so a granule of eight rows spans more than one day.
INSERT INTO ontime SELECT toDate('2025-09-14') + intDiv(number, 10), 'AA' FROM numbers(40);

-- The granules that hold the rows of 2025-09-15 also hold rows of the neighbouring days,
-- and `indexHint` returns all of them.
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

┌──────────k─┬─count()─┐
│ 2025-09-14 │       2 │
│ 2025-09-15 │      10 │
│ 2025-09-16 │       4 │
└────────────┴─────────┘

Introduit dans : v1.1.0

Renvoie l’ID de la requête initiale en cours. D’autres paramètres d’une requête peuvent être extraits du champ initial_query_id de system.query_log.

Contrairement à la fonction queryID, initialQueryID renvoie les mêmes résultats sur différents shards.

Syntaxe

initialQueryID()

Alias : initial_query_id

Arguments

• Aucun.

Valeur renvoyée

Renvoie l’ID de la requête initiale. String

Exemples

Exemple d’utilisation

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

Introduit dans : v25.4.0

Renvoie l’heure de début de la requête initiale en cours. initialQueryStartTime renvoie les mêmes résultats sur différents shards.

Syntaxe

initialQueryStartTime()

Alias : initial_query_start_time

Arguments

• Aucun.

Valeur renvoyée

Renvoie l’heure de début de la requête initiale en cours. DateTime

Exemples

Exemple d'utilisation

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

Introduit dans : v20.6.0

Calcule le résultat d’une fonction d’agrégation à partir d’une valeur unique. Cette fonction peut être utilisée pour initialiser des fonctions d’agrégation avec le combinateur -State. Vous pouvez créer des états de fonctions d’agrégation et les insérer dans des colonnes de type AggregateFunction, ou utiliser des agrégats initialisés comme valeurs par défaut.

Syntaxe

initializeAggregation(aggregate_function, arg1[, arg2, ...])

Arguments

• aggregate_function — Nom de la fonction d’agrégation à initialiser. String
• arg1[, arg2, ...] — Arguments de la fonction d’agrégation. Any

Valeur renvoyée

Renvoie le résultat de l’agrégation pour chaque ligne transmise à la fonction. Le type de retour est le même que celui de la fonction dont initializeAggregation prend le premier argument. Any

Exemples

Utilisation de base avec uniqState

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

Utilisation de sumState et de finalizeAggregation

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

Introduit dans : v20.3.0

Indique si l’argument est une expression constante. Une expression constante est une expression dont le résultat est connu lors de l’analyse de la requête, c’est-à-dire avant l’exécution. Par exemple, les expressions construites à partir de littéraux sont des expressions constantes. Cette fonction est principalement destinée au développement, au débogage et à la démonstration.

Syntaxe

isConstant(x)

Arguments

• x — Une expression à vérifier. Any

Valeur renvoyée

Renvoie 1 si x est constante, 0 si x ne l'est pas. UInt8

Exemples

Expression constante

SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

Constante avec une fonction

WITH 3.14 AS pi
SELECT isConstant(cos(pi))

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

Expression non constante

SELECT isConstant(number)
FROM numbers(1)

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

Comportement de la fonction now()

SELECT isConstant(now())

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

Introduit dans : v20.8.0

Vérifie si un nombre décimal comporte trop de chiffres pour être correctement représenté dans un type de données Decimal avec la précision donnée.

Syntaxe

isDecimalOverflow(value[, precision])

Arguments

• value — Valeur Decimal à vérifier. Decimal
• precision — Facultatif. Précision du type Decimal. Si elle est omise, la précision initiale du premier argument est utilisée. UInt8

Valeur renvoyée

Renvoie 1 si la valeur décimale comporte plus de chiffres que n’en autorise sa précision, 0 si la valeur décimale respecte la précision spécifiée. UInt8

Exemples

Exemple d'utilisation

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

Introduit dans : v18.16.0

Permet d’extraire des données d’une table de la même manière que depuis un dictionnaire. Récupère des données à partir de tables Join à l’aide de la clé de jointure spécifiée.

Syntaxe

joinGet(join_storage_table_name, value_column, join_keys)

Arguments

• join_storage_table_name — Un identifiant qui indique où rechercher. L’identifiant est recherché dans la base de données default (voir le paramètre default_database dans le fichier de configuration). Pour remplacer la base de données par défaut, utilisez la requête USE database_name ou précisez la base de données et la table en les séparant par un point, comme database_name.table_name. String
• value_column — Le nom de la colonne de la table qui contient les données requises. const String
• join_keys — Une liste de clés de jointure. Any

Valeur renvoyée

Renvoie une liste de valeurs correspondant à la liste des clés. Any

Exemples

Exemple d’utilisation

CREATE TABLE id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGet(id_val, 'val', toUInt32(1));

┌─joinGet('id_val', 'val', toUInt32(1))─┐
│                                    11 │
└───────────────────────────────────────┘

Utilisation avec une table de la base de données courante

SELECT joinGet(id_val, 'val', toUInt32(2));

┌─joinGet('id_val', 'val', toUInt32(2))─┐
│                                    12 │
└───────────────────────────────────────┘

Utiliser des tableaux comme clés de jointure

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', toUInt32(1), toUInt32(11));

┌─joinGet('some_table', 'name', toUInt32(1), toUInt32(11))─┐
│ a                                                        │
└──────────────────────────────────────────────────────────┘

Introduit dans : v20.4.0

Permet d’extraire des données d’une table de la même manière que depuis un dictionnaire. Récupère des données depuis des tables Join à l’aide de la clé de jointure spécifiée. Contrairement à joinGet, renvoie NULL lorsque la clé est absente.

Syntaxe

joinGetOrNull(join_storage_table_name, value_column, join_keys)

Arguments

• join_storage_table_name — Un identifiant qui indique où effectuer la recherche. L’identifiant est recherché dans la base de données default (voir le paramètre default_database dans le fichier de configuration). Pour remplacer la base de données par défaut, utilisez la requête USE database_name ou indiquez la base de données et la table en les séparant par un point, comme database_name.table_name. String
• value_column — Le nom de la colonne de la table qui contient les données requises. const String
• join_keys — Une liste de clés de jointure. Any

Valeur renvoyée

Renvoie une liste de valeurs correspondant à la liste des clés, ou NULL si une clé est introuvable. Any

Exemples

Exemple d’utilisation

CREATE TABLE id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGetOrNull(id_val, 'val', toUInt32(1)), joinGetOrNull(id_val, 'val', toUInt32(999));

┌─joinGetOrNull('id_val', 'val', toUInt32(1))─┬─joinGetOrNull('id_val', 'val', toUInt32(999))─┐
│                                          11 │                                          ᴺᵁᴸᴸ │
└─────────────────────────────────────────────┴───────────────────────────────────────────────┘

Introduit dans : v18.12.0

Renvoie la position d’une valeur dans le dictionnaire d’une colonne LowCardinality. Les positions commencent à 1. Comme LowCardinality utilise des dictionnaires propres à chaque part, cette fonction peut renvoyer des positions différentes pour une même valeur selon les parts.

Syntaxe

lowCardinalityIndices(col)

Arguments

• col — Une colonne à faible cardinalité. LowCardinality

Valeur renvoyée

La position de la valeur dans le dictionnaire de la part actuelle. UInt64

Exemples

Exemples d'utilisation

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

-- the order the blocks are read in is not defined, so sort the result to make it reproducible:

SELECT s, lowCardinalityIndices(s) AS index FROM test ORDER BY s, index;

┌─s──┬─index─┐
│ ab │     1 │
│ ab │     1 │
│ ab │     1 │
│ ab │     3 │
│ cd │     2 │
│ cd │     2 │
│ cd │     2 │
│ df │     3 │
│ ef │     1 │
│ ef │     1 │
└────┴───────┘

Introduit dans : v18.12.0

Renvoyer les valeurs du dictionnaire d’une colonne LowCardinality. Si le bloc est plus petit ou plus grand que la taille du dictionnaire, le résultat sera tronqué ou complété avec des valeurs par défaut. Comme LowCardinality utilise des dictionnaires par part, cette fonction peut renvoyer des valeurs de dictionnaire différentes d’une part à l’autre.

Syntaxe

lowCardinalityKeys(col)

Arguments

• col — Une colonne à faible cardinalité. LowCardinality

Valeur renvoyée

Renvoie les clés du dictionnaire. UInt64

Exemples

lowCardinalityKeys

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

Introduit dans : v1.1.0

Transforme une constante en une colonne complète contenant une seule valeur. Les colonnes complètes et les constantes sont représentées différemment en mémoire. Les fonctions exécutent généralement un code différent pour les arguments normaux et constants, même si le résultat devrait en principe être le même. Cette fonction peut être utilisée pour déboguer ce comportement.

Syntaxe

materialize(x)

Arguments

• x — Une constante. Any

Valeur renvoyée

Renvoie une colonne complète contenant la valeur constante. Any

Exemples

Exemple d’utilisation

-- In the example below the `countMatches` function expects a constant second argument.
-- This behaviour can be debugged by using the `materialize` function to turn a constant into a full column,
-- verifying that the function throws an error for a non-constant argument.

SELECT countMatches('foobarfoo', 'foo');

2

Transformer une constante en colonne complète

SELECT countMatches('foobarfoo', materialize('foo'));

Received exception:
Code: 44. DB::Exception: A value of illegal type was provided as 2nd argument 'pattern' to function 'countMatches'. Expected: constant String, got: String. (ILLEGAL_COLUMN)

Introduit dans : v23.10.0

Calcule la taille d’échantillon minimale requise pour un test A/B comparant les moyennes d’une métrique continue dans deux échantillons.

Utilise la formule décrite dans cet article. Suppose des tailles égales pour les groupes de traitement et témoin. Renvoie la taille d’échantillon requise pour un groupe (c’est-à-dire que la taille d’échantillon requise pour l’ensemble de l’expérience est égale à deux fois la valeur renvoyée). Suppose également une variance égale de la métrique testée dans les groupes de traitement et témoin.

Syntaxe

minSampleSizeContinuous(baseline, sigma, mde, power, alpha)

Alias : minSampleSizeContinous

Arguments

• baseline — Valeur de référence d'une métrique. (U)Int* ou Float*
• sigma — Écart type de référence d'une métrique. (U)Int* ou Float*
• mde — Effet minimal détectable (MDE) en pourcentage de la valeur de référence (par ex. pour une valeur de référence de 112.25, un MDE de 0.03 correspond à une variation attendue de 112.25 ± 112.25*0.03). (U)Int* ou Float*
• power — Puissance statistique requise d'un test (1 - probabilité d'une erreur de type II). (U)Int* ou Float*
• alpha — Niveau de signification requis d'un test (probabilité d'une erreur de type I). (U)Int* ou Float*

Valeur renvoyée

Renvoie un Tuple nommé avec 3 éléments : minimum_sample_size, detect_range_lower et detect_range_upper. Il s'agit respectivement de la taille d'échantillon requise, de la borne inférieure de la plage de valeurs non détectables avec la taille d'échantillon requise renvoyée, calculée comme baseline * (1 - mde), et de la borne supérieure de la plage de valeurs non détectables avec la taille d'échantillon requise renvoyée, calculée comme baseline * (1 + mde) (Float64). Tuple(Float64, Float64, Float64)

Exemples

minSampleSizeContinuous

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

(616.2931945826209,108.8825,115.6175)

Introduit dans : v22.6.0

Calcule la taille d’échantillon minimale requise pour un test A/B comparant les conversions (proportions) entre deux échantillons.

Utilise la formule décrite dans cet article. Suppose des tailles égales pour les groupes de traitement et témoin. Renvoie la taille d’échantillon requise pour un groupe (c.-à-d. que la taille d’échantillon requise pour l’ensemble de l’expérience est le double de la valeur renvoyée).

Syntaxe

minSampleSizeConversion(baseline, mde, power, alpha)

Arguments

• baseline — Conversion de référence. Float*
• mde — Effet minimal détectable (MDE), exprimé en points de pourcentage (par ex., pour une conversion de référence de 0.25, un MDE de 0.03 correspond à une variation attendue vers 0.25 ± 0.03). Float*
• power — Puissance statistique requise pour un test (1 - probabilité d’erreur de type II). Float*
• alpha — Niveau de signification requis pour un test (probabilité d’erreur de type I). Float*

Valeur renvoyée

Renvoie un Tuple nommé avec 3 éléments : minimum_sample_size, detect_range_lower, detect_range_upper. Il s’agit, respectivement, de la taille d’échantillon requise, de la borne inférieure de la plage de valeurs non détectables avec la taille d’échantillon requise renvoyée, calculée comme baseline - mde, et de la borne supérieure de la plage de valeurs non détectables avec la taille d’échantillon requise renvoyée, calculée comme baseline + mde. Tuple(Float64, Float64, Float64)

Exemples

minSampleSizeConversion

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size

(3396.077603219163,0.22,0.28)

Introduit dans : v20.1.0

Renvoie une valeur d’une colonne à l’offset spécifié par rapport à la ligne courante. Cette fonction est déconseillée et sujette aux erreurs, car elle s’appuie sur l’ordre physique des blocs de données, qui peut ne pas correspondre à l’ordre logique attendu par les utilisateurs. Envisagez plutôt d’utiliser de véritables fonctions de fenêtre.

La fonction peut être activée en définissant allow_deprecated_error_prone_window_functions = 1.

Syntaxe

neighbor(column, offset[, default_value])

Arguments

• column — La colonne source. Any
• offset — Le décalage par rapport à la ligne actuelle. Les valeurs positives portent vers l’avant, les valeurs négatives vers l’arrière. Integer
• default_value — Facultatif. Valeur à renvoyer si le décalage dépasse les limites des données. Si elle n’est pas spécifiée, la valeur par défaut du type de colonne est utilisée. Any

Valeur renvoyée

Renvoie une valeur au décalage spécifié, ou la valeur par défaut si elle est hors limites. Any

Exemples

Exemple d’utilisation

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

Avec une valeur par défaut

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2, 999)─┐
│      0 │                        2 │
│      1 │                        3 │
│      2 │                        4 │
│      3 │                        5 │
│      4 │                        6 │
│      5 │                        7 │
│      6 │                        8 │
│      7 │                        9 │
│      8 │                      999 │
│      9 │                      999 │
└────────┴──────────────────────────┘

Introduit dans : v20.8.0

Remplace les littéraux, les suites de littéraux et les alias complexes (contenant des espaces, plus de deux chiffres ou d’au moins 36 octets, comme les UUID) par le caractère de substitution ?.

Syntaxe

normalizeQuery(x)

Arguments

• x — Séquence de caractères. String

Valeur renvoyée

Renvoie la séquence de caractères donnée avec des placeholders. String

Exemples

Exemple d'utilisation

SELECT normalizeQuery('[1, 2, 3, x]') AS query

┌─query────┐
│ [?.., x] │
└──────────┘

Introduit dans : v21.2.0

Remplace les littéraux et les séquences de littéraux par le caractère de substitution ?, mais ne remplace pas les alias complexes (contenant des espaces, plus de deux chiffres ou d’une longueur d’au moins 36 octets, comme les UUIDs). Cela permet de mieux analyser les journaux de requêtes complexes.

Syntaxe

normalizeQueryKeepNames(x)

Arguments

• x — Séquence de caractères. String

Valeur renvoyée

Renvoie la séquence de caractères donnée avec des marqueurs de substitution. String

Exemples

Exemple d'utilisation

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

Introduit dans : v20.8.0

Renvoie des valeurs de hachage 64 bits identiques, sans les valeurs des littéraux, pour des requêtes similaires. Peut être utile pour l’analyse des journaux de requêtes.

Syntaxe

normalizedQueryHash(x)

Arguments

• x — Suite de caractères. String

Valeur renvoyée

Renvoie une valeur de hachage sur 64 bits. UInt64

Exemples

Exemple d’utilisation

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res

┌─res─┐
│   1 │
└─────┘

Introduit dans : v21.2.0

Comme normalizedQueryHash, elle renvoie des valeurs de hachage 64 bits identiques pour des requêtes similaires, sans les valeurs des littéraux, mais ne remplace pas les alias complexes (contenant des espaces, plus de deux chiffres ou d’une longueur d’au moins 36 octets, comme les UUID) par un caractère de substitution avant le hachage. Peut être utile pour analyser les journaux de requêtes.

Syntaxe

normalizedQueryHashKeepNames(x)

Arguments

• x — Séquence de caractères. String

Valeur renvoyée

Renvoie une valeur de hachage sur 64 bits. UInt64

Exemples

Exemple d'utilisation

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

Introduit dans : v26.4.0

Obfusque une requête SQL en remplaçant les identifiants par des mots aléatoires et les littéraux par des valeurs aléatoires, tout en préservant la structure de la requête.

Cette fonction est utile pour anonymiser les requêtes avant de les consigner dans les logs ou de les partager à des fins de débogage. Des lignes différentes produiront des résultats masqués différents, même pour la même requête en entrée, ce qui aide à préserver la confidentialité lors du traitement de plusieurs requêtes.

Le paramètre facultatif tag empêche l’élimination des sous-expressions communes lorsque le même appel de fonction est utilisé plusieurs fois dans une requête. Cela garantit que chaque appel produit un résultat masqué différent.

Fonctionnalités :

• Remplace les noms de table, les noms de colonnes et les alias par des mots aléatoires
• Remplace les littéraux numériques et textuels par des valeurs aléatoires
• Préserve la structure globale de la requête et la syntaxe SQL
• Produit des résultats différents pour des lignes différentes

Syntaxe

obfuscateQuery(query[, tag])

Arguments

• query — La requête SQL à obfusquer. String
• tag — Facultatif. Une valeur permettant d’éviter l’élimination des sous-expressions communes lorsque le même appel de fonction est utilisé plusieurs fois.

Valeur renvoyée

La requête obfusquée, dans laquelle les identifiants et les littéraux sont remplacés tout en préservant la structure d’origine de la requête. String

Exemples

Utilisation de base

SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')

SELECT fruit, number FROM table WHERE number > 12

Avec un tag pour éviter l'élimination des sous-expressions communes

SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)

SELECT a FROM b, SELECT c FROM d

Des lignes différentes donnent des résultats différents

SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b

SELECT 1	SELECT 1

Introduite dans : v26.4.0

Obfusque une requête SQL à l’aide d’une seed spécifiée afin d’obtenir des résultats déterministes.

Contrairement à obfuscateQuery(), cette fonction produit des résultats déterministes lorsqu’elle reçoit la même seed. Cela est utile lorsque vous avez besoin d’une obfuscation constante sur plusieurs exécutions, ou lorsque vous souhaitez reproduire la même requête obfusquée à des fins de test ou de débogage.

Fonctionnalités :

• Obfuscation déterministe basée sur la seed fournie
• La même seed produit toujours le même résultat obfusqué
• Des seeds différentes produisent des résultats différents
• Préserve la structure de la requête, comme obfuscateQuery()

Cas d’utilisation :

• Cas de test reproductibles
• Anonymisation constante sur plusieurs exécutions
• Débogage avec des requêtes obfusquées cohérentes

Syntaxe

obfuscateQueryWithSeed(query, seed)

Arguments

• query — La requête SQL à obfusquer. String
• seed — La seed pour l'obfuscation. La même seed produit des résultats déterministes. Integer ou String

Valeur renvoyée

La requête obfusquée, générée de manière déterministe à partir de la seed fournie. String

Exemples

Obfuscation déterministe avec une seed entière

SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)

SELECT name FROM users

Obfuscation déterministe avec une seed de type chaîne

SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')

SELECT id, value FROM data

Même seed, même résultat

SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)

1

Introduite dans : v26.8.0

Analyse une chaîne de requête SQL en AST (arbre syntaxique abstrait) et renvoie une représentation JSON de cet arbre. Le JSON obtenu peut être transmis à formatQueryFromJSON pour reconstruire la requête SQL, ou envoyé directement au serveur à l’aide de la valeur clickhouse_json du paramètre dialect (contrôlée par enable_json_ast_dialect).

Cette fonction est utile aux outils qui souhaitent inspecter ou transformer des requêtes par programmation sans passer par la grammaire SQL.

Toutes les requêtes SQL ne possèdent pas de représentation JSON fidèle. Les requêtes contenant des données que le format JSON ne peut pas reproduire (par exemple, des données intégrées INSERT ... VALUES / INSERT ... FORMAT) ainsi que les types de nœuds AST qui n’implémentent pas encore la sérialisation JSON sont rejetés avec BAD_ARGUMENTS, plutôt que de produire du JSON que formatQueryFromJSON ne pourrait pas relire.

Les limites d’analyse (max_query_size, max_parser_depth, max_parser_backtracks) sont déterminées par les paramètres de la session actuelle.

Syntaxe

parseQueryToJSON(sql)

Arguments

• sql — Chaîne de requête SQL à analyser. String

Valeur renvoyée

Chaîne JSON représentant l'AST. String

Exemples

SELECT simple

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT 1'));

┌─formatQueryFromJSON(parseQueryToJSON('SELECT 1'))─┐
│ SELECT 1                                          │
└───────────────────────────────────────────────────┘

Introduit dans : v24.6.0

À partir d’une chaîne contenant une taille en octets et B, KiB, KB, MiB, MB, etc. comme unité (c.-à-d. ISO/IEC 80000-13 ou unité décimale d’octets), cette fonction renvoie le nombre d’octets correspondant. Si la fonction ne parvient pas à analyser la valeur d’entrée, elle lève une exception.

Les opérations inverses de cette fonction sont formatReadableSize et formatReadableDecimalSize.

Syntaxe

parseReadableSize(x)

Arguments

• x — Taille dans un format lisible avec ISO/IEC 80000-13 ou une unité décimale d’octets. String

Valeur renvoyée

Renvoyer le nombre d’octets, arrondi à l’entier supérieur le plus proche. UInt64

Exemples

Exemple d’utilisation

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

Introduit dans : v24.6.0

Étant donnée une chaîne contenant une taille en octets et B, KiB, KB, MiB, MB, etc. comme unité (c.-à-d. ISO/IEC 80000-13 ou une unité d’octets décimale), cette fonction renvoie le nombre d’octets correspondant. Si la fonction ne parvient pas à analyser la valeur d’entrée, elle renvoie NULL.

Les opérations inverses de cette fonction sont formatReadableSize et formatReadableDecimalSize.

Syntaxe

parseReadableSizeOrNull(x)

Arguments

• x — Taille en format lisible avec ISO/IEC 80000-13 ou une unité d’octets décimale. String

Valeur renvoyée

Renvoie le nombre d’octets, arrondi à l’entier supérieur, ou NULL si l’entrée ne peut pas être interprétée Nullable(UInt64)

Exemples

Exemple d’utilisation

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

Introduit dans : v24.6.0

Étant donnée une chaîne contenant une taille en octets avec B, KiB, KB, MiB, MB, etc. comme unité (c.-à-d. ISO/IEC 80000-13 ou unité d’octets décimale), cette fonction renvoie le nombre d’octets correspondant. Si la fonction ne parvient pas à analyser la valeur d’entrée, elle renvoie 0.

Les opérations inverses de cette fonction sont formatReadableSize et formatReadableDecimalSize.

Syntaxe

parseReadableSizeOrZero(x)

Arguments

• x — Taille lisible avec une unité de taille ISO/IEC 80000-13 ou une unité de taille décimale. String

Valeur renvoyée

Renvoie le nombre d’octets, arrondi à l’entier supérieur le plus proche, ou 0 s’il est impossible d’analyser l’entrée. UInt64

Exemples

Exemple d’utilisation

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

Introduit dans : v22.7.0

Analyse une suite de nombres suivie d’un élément ressemblant à une unité de temps.

La chaîne de décalage temporel utilise les spécifications d’unité de temps suivantes :

• years, year, yr, y
• months, month, mo
• weeks, week, w
• days, day, d
• hours, hour, hr, h
• minutes, minute, min, m
• seconds, second, sec, s
• milliseconds, millisecond, millisec, ms
• microseconds, microsecond, microsec, μs, µs, us
• nanoseconds, nanosecond, nanosec, ns

Plusieurs unités de temps peuvent être combinées à l’aide de séparateurs (espace, ;, -, +, ,, :).

La durée des années et des mois est approximative : une année correspond à 365 jours et un mois à 30,5 jours.

Syntaxe

parseTimeDelta(timestr)

Arguments

• timestr — Une suite de nombres suivie d’un élément ressemblant à une unité de temps. String

Valeur renvoyée

Le nombre de secondes. Float64

Exemples

Exemple d’utilisation

SELECT parseTimeDelta('11s+22min')

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

Unités temporelles complexes

SELECT parseTimeDelta('1yr2mo')

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

Introduit dans : v21.4.0

Calcule l’identifiant de partition.

Syntaxe

partitionId(column1[, column2, ...])

Alias : partitionID

Arguments

• column1, column2, ... — Colonne pour laquelle l'identifiant de partition doit être renvoyé.

Valeur renvoyée

Renvoie l'identifiant de partition de la ligne. String

Exemples

Exemple d'utilisation

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;

┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

Introduite dans : v26.8.0

Fonction de compatibilité avec le protocole filaire PostgreSQL, analogue à pg_catalog.pg_get_userbyid. Les clients PostgreSQL (par exemple, la commande \d dans psql) l'utilisent pour afficher le propriétaire d'une table. ClickHouse ne gère pas la propriété des tables ; la fonction ignore donc l'argument et renvoie le nom de l'utilisateur courant.

Syntaxe

pgGetUserById(oid)

Alias : pg_get_userbyid

Arguments

• oid — Identifiant d'objet du rôle. La valeur est ignorée. UInt32

Valeur renvoyée

Renvoie le nom de l'utilisateur courant. String

Exemples

Exemple d'utilisation

SELECT pg_get_userbyid(10)

┌─pg_get_userbyid(10)─┐
│ default             │
└─────────────────────┘

Introduite dans : v26.8.0

Fonction de compatibilité avec le protocole filaire PostgreSQL, équivalente à pg_catalog.pg_table_is_visible. Les clients PostgreSQL (par exemple, la commande \d dans psql) l’utilisent pour filtrer les tables visibles dans le chemin de recherche. Comme la vue pg_class émulée par ClickHouse n’expose que les tables de la base de données courante, qui sont toutes visibles, la fonction renvoie toujours 1.

Syntaxe

pgTableIsVisible(oid)

Alias : pg_table_is_visible

Arguments

• oid — Identifiant d’objet de la table, tel qu’exposé par la vue pg_class émulée. La valeur est ignorée. UInt32

Valeur renvoyée

Renvoie toujours 1. UInt8

Exemples

Exemple d’utilisation

SELECT pg_table_is_visible(0)

┌─pg_table_is_visible(0)─┐
│                      1 │
└────────────────────────┘

Introduit dans : v21.9.0

Renvoie l’ID de la requête en cours. Les autres paramètres d’une requête peuvent être extraits du champ query_id de la table system.query_log.

Contrairement à la fonction initialQueryID, queryID peut renvoyer des résultats différents selon les shards.

Syntaxe

queryID()

Alias : query_id

Arguments

• Aucun.

Valeur renvoyée

Renvoie l’identifiant de la requête en cours. String

Exemples

Exemple d’utilisation

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─countDistinct(t)─┐
│                3 │
└──────────────────┘

Introduit dans : v22.7.0

Renvoie la révision actuelle du serveur ClickHouse.

Syntaxe

revision()

Arguments

• Aucun.

Valeur renvoyée

Renvoie la révision actuelle du serveur ClickHouse. UInt32

Exemples

Exemple d'utilisation

SELECT revision()

┌─revision()─┐
│      54485 │
└────────────┘

Introduit dans : v1.1.0

Renvoie un numéro de ligne unique pour chaque ligne traitée.

Syntaxe

rowNumberInAllBlocks()

Arguments

• Aucun.

Valeur renvoyée

Renvoie le numéro ordinal de la ligne dans le bloc de données, à partir de 0. UInt64

Exemples

Exemple d'utilisation

-- The data is processed in blocks of two rows: rowNumberInBlock restarts from 0 in every block,
-- while rowNumberInAllBlocks keeps counting across them.
SELECT
    number,
    rowNumberInBlock(),
    rowNumberInAllBlocks()
FROM system.numbers
LIMIT 6
SETTINGS max_block_size = 2

┌─number─┬─rowNumberInBlock()─┬─rowNumberInAllBlocks()─┐
│      0 │                  0 │                      0 │
│      1 │                  1 │                      1 │
│      2 │                  0 │                      2 │
│      3 │                  1 │                      3 │
│      4 │                  0 │                      4 │
│      5 │                  1 │                      5 │
└────────┴────────────────────┴────────────────────────┘

Introduit dans : v1.1.0

Pour chaque bloc traité par rowNumberInBlock, renvoie le numéro de la ligne courante.

Le numéro renvoyé commence à 0 pour chaque bloc.

Syntaxe

rowNumberInBlock()

Arguments

• Aucun.

Valeur renvoyée

Renvoie le numéro ordinal de la ligne dans le bloc de données, à partir de 0. UInt64

Exemples

Exemple d'utilisation

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
└────────────────────┘

Introduit dans : v1.1.0

Accumule les états d'une fonction d'agrégation pour chaque ligne d'un bloc de données.

Syntaxe

runningAccumulate(agg_state[, grouping])

Arguments

• agg_state — État de la fonction d’agrégation. AggregateFunction
• grouping — Facultatif. Clé de regroupement. L’état de la fonction est réinitialisé si la valeur de grouping change. Il peut s’agir de n’importe quel type de données pris en charge pour lequel l’opérateur d’égalité est défini. Any

Valeur renvoyée

Renvoie le résultat accumulé pour chaque ligne. Any

Exemples

Exemple d’utilisation avec initializeAggregation

SET allow_deprecated_error_prone_window_functions = 1;
WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

Introduite dans : v21.3.0

Calcule le nombre d’événements simultanés. Chaque événement possède une heure de début et une heure de fin. L’heure de début est incluse dans l’événement, tandis que l’heure de fin ne l’est pas. Les colonnes contenant l’heure de début et l’heure de fin doivent être du même type de données. La fonction calcule le nombre total d’événements actifs (simultanés) pour chaque heure de début d’événement.

Syntaxe

runningConcurrency(start, end)

Arguments

• start — Colonne contenant l'horodatage de début des événements. Date ou DateTime ou DateTime64
• end — Colonne contenant l'horodatage de fin des événements. Date ou DateTime ou DateTime64

Valeur renvoyée

Renvoie le nombre d'événements simultanés pour chaque horodatage de début d'événement. UInt32

Exemples

Exemple d'utilisation

CREATE TABLE example_table (start Date, end Date) ENGINE = Memory;
INSERT INTO example_table VALUES ('2025-03-03', '2025-03-11'), ('2025-03-06', '2025-03-08'), ('2025-03-07', '2025-03-09'), ('2025-03-11', '2025-03-12');

SELECT start, runningConcurrency(start, end) FROM example_table;

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │                              1 │
│ 2025-03-06 │                              2 │
│ 2025-03-07 │                              3 │
│ 2025-03-11 │                              1 │
└────────────┴────────────────────────────────┘

Introduit dans : v1.1.0

Calcule la différence entre les valeurs de deux lignes consécutives dans le bloc de données. Renvoie 0 pour la première ligne, puis, pour les lignes suivantes, la différence par rapport à la ligne précédente.

Le résultat de la fonction dépend des blocs de données concernés et de l’ordre des données dans le bloc. L’ordre des lignes lors du calcul de runningDifference() peut différer de l’ordre des lignes renvoyées à l’utilisateur. Pour éviter cela, vous pouvez créer une sous-requête avec ORDER BY et appeler la fonction en dehors de la sous-requête. Veuillez noter que la taille du bloc influe sur le résultat. L’état interne de runningDifference est réinitialisé pour chaque nouveau bloc.

Syntaxe

runningDifference(x)

Arguments

• x — Colonne pour laquelle calculer la différence entre valeurs consécutives. Any

Valeur renvoyée

Renvoie la différence entre des valeurs consécutives, avec 0 pour la première ligne.

Exemples

Exemple d'utilisation

SET allow_deprecated_error_prone_window_functions = 1;

CREATE TABLE events
(
    EventID UInt32,
    EventDate Date,
    EventTime DateTime
)
ENGINE = Memory;

INSERT INTO events VALUES
    (1106, '2025-11-24', '2025-11-24 00:00:04'),
    (1107, '2025-11-24', '2025-11-24 00:00:05'),
    (1108, '2025-11-24', '2025-11-24 00:00:05'),
    (1109, '2025-11-24', '2025-11-24 00:00:09'),
    (1110, '2025-11-24', '2025-11-24 00:00:10');

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2025-11-24'
    ORDER BY EventTime ASC, EventID ASC
    LIMIT 5
);

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2025-11-24 00:00:04 │     0 │
│    1107 │ 2025-11-24 00:00:05 │     1 │
│    1108 │ 2025-11-24 00:00:05 │     0 │
│    1109 │ 2025-11-24 00:00:09 │     4 │
│    1110 │ 2025-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

Exemple d’impact de la taille des blocs

SET allow_deprecated_error_prone_window_functions = 1;
SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;