Fonctions de travail avec les dictionnaires

Pour les dictionnaires créés avec des requêtes DDL, le paramètre dict_name doit être entièrement qualifié, sous la forme <database>.<dict_name>. Sinon, la base de données actuelle est utilisée.

Pour plus d’informations sur la connexion et la configuration des dictionnaires, consultez Dictionnaires.

Exemples de dictionnaires

Les exemples de cette section s’appuient sur les dictionnaires suivants. Vous pouvez les créer dans ClickHouse pour exécuter les exemples des fonctions décrites ci-dessous.

Exemple de dictionnaire pour les fonctions dictGet<T> et dictGet<T>OrDefault

-- Créer une table avec tous les types de données requis
CREATE TABLE all_types_test (
    `id` UInt32,
    
    -- Type String
    `String_value` String,
    
    -- Types d'entiers non signés
    `UInt8_value` UInt8,
    `UInt16_value` UInt16,
    `UInt32_value` UInt32,
    `UInt64_value` UInt64,
    
    -- Types d'entiers signés
    `Int8_value` Int8,
    `Int16_value` Int16,
    `Int32_value` Int32,
    `Int64_value` Int64,
    
    -- Types à virgule flottante
    `Float32_value` Float32,
    `Float64_value` Float64,
    
    -- Types date/heure
    `Date_value` Date,
    `DateTime_value` DateTime,
    
    -- Types réseau
    `IPv4_value` IPv4,
    `IPv6_value` IPv6,
    
    -- Type UUID
    `UUID_value` UUID
) ENGINE = MergeTree() 
ORDER BY id;

-- Insérer des données de test
INSERT INTO all_types_test VALUES
(
    1,                              -- id
    'ClickHouse',                   -- String
    100,                            -- UInt8
    5000,                           -- UInt16
    1000000,                        -- UInt32
    9223372036854775807,            -- UInt64
    -100,                           -- Int8
    -5000,                          -- Int16
    -1000000,                       -- Int32
    -9223372036854775808,           -- Int64
    123.45,                         -- Float32
    987654.123456,                  -- Float64
    '2024-01-15',                   -- Date
    '2024-01-15 10:30:00',          -- DateTime
    '192.168.1.1',                  -- IPv4
    '2001:db8::1',                  -- IPv6
    '550e8400-e29b-41d4-a716-446655440000' -- UUID
)

-- Créer le dictionnaire
CREATE DICTIONARY all_types_dict
(
    id UInt32,
    String_value String,
    UInt8_value UInt8,
    UInt16_value UInt16,
    UInt32_value UInt32,
    UInt64_value UInt64,
    Int8_value Int8,
    Int16_value Int16,
    Int32_value Int32,
    Int64_value Int64,
    Float32_value Float32,
    Float64_value Float64,
    Date_value Date,
    DateTime_value DateTime,
    IPv4_value IPv4,
    IPv6_value IPv6,
    UUID_value UUID
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'all_types_test' DB 'default'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 600);

Exemple de dictionnaire pour dictGetAll

Créez une table pour stocker les données du dictionnaire regexp tree :

CREATE TABLE regexp_os(
    id UInt64,
    parent_id UInt64,
    regexp String,
    keys Array(String),
    values Array(String)
)
ENGINE = Memory;

Insérez des données dans cette table :

INSERT INTO regexp_os 
SELECT *
FROM s3(
    'https://datasets-documentation.s3.eu-west-3.amazonaws.com/' ||
    'user_agent_regex/regexp_os.csv'
);

Créez le dictionnaire regexp tree :

CREATE DICTIONARY regexp_tree
(
    regexp String,
    os_replacement String DEFAULT 'Other',
    os_v1_replacement String DEFAULT '0',
    os_v2_replacement String DEFAULT '0',
    os_v3_replacement String DEFAULT '0',
    os_v4_replacement String DEFAULT '0'
)
PRIMARY KEY regexp
SOURCE(CLICKHOUSE(TABLE 'regexp_os'))
LIFETIME(MIN 0 MAX 0)
LAYOUT(REGEXP_TREE);

Exemple de dictionnaire à clé d’intervalle

Créez la table d’entrée :

CREATE TABLE range_key_dictionary_source_table
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
ENGINE = TinyLog();

Insérez les données dans la table d’entrée :

INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');

Créez le dictionnaire :

CREATE DICTIONARY range_key_dictionary
(
    key UInt64,
    start_date Date,
    end_date Date,
    value String,
    value_nullable Nullable(String)
)
PRIMARY KEY key
SOURCE(CLICKHOUSE(HOST 'localhost' PORT tcpPort() TABLE 'range_key_dictionary_source_table'))
LIFETIME(MIN 1 MAX 1000)
LAYOUT(RANGE_HASHED())
RANGE(MIN start_date MAX end_date);

Exemple de dictionnaire à clé composite

Créez la table source :

CREATE TABLE dict_mult_source
(
id UInt32,
c1 UInt32,
c2 String
) ENGINE = Memory;

Insérez les données dans la table source :

INSERT INTO dict_mult_source VALUES
(1, 1, '1'),
(2, 2, '2'),
(3, 3, '3');

Créez le dictionnaire :

CREATE DICTIONARY ext_dict_mult
(
    id UInt32,
    c1 UInt32,
    c2 String
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'dict_mult_source' DB 'default'))
LAYOUT(FLAT())
LIFETIME(MIN 0 MAX 0);

Exemple de dictionnaire hiérarchique

Créez la table source :

CREATE TABLE hierarchy_source
(
  id UInt64,
  parent_id UInt64,
  name String
) ENGINE = Memory;

Insérez les données dans la table source :

INSERT INTO hierarchy_source VALUES
(0, 0, 'Root'),
(1, 0, 'Level 1 - Node 1'),
(2, 1, 'Level 2 - Node 2'),
(3, 1, 'Level 2 - Node 3'),
(4, 2, 'Level 3 - Node 4'),
(5, 2, 'Level 3 - Node 5'),
(6, 3, 'Level 3 - Node 6');

-- 0 (Racine)
-- └── 1 (Niveau 1 - Nœud 1)
--     ├── 2 (Niveau 2 - Nœud 2)
--     │   ├── 4 (Niveau 3 - Nœud 4)
--     │   └── 5 (Niveau 3 - Nœud 5)
--     └── 3 (Niveau 2 - Nœud 3)
--         └── 6 (Niveau 3 - Nœud 6)

Créez le dictionnaire :

CREATE DICTIONARY hierarchical_dictionary
(
    id UInt64,
    parent_id UInt64 HIERARCHICAL,
    name String
)
PRIMARY KEY id
SOURCE(CLICKHOUSE(HOST 'localhost' PORT 9000 USER 'default' TABLE 'hierarchy_source' DB 'default'))
LAYOUT(HASHED())
LIFETIME(MIN 300 MAX 600);

Passage des clés aux fonctions de dictionnaire

L’argument de clé (id_expr) de fonctions telles que dictGet, dictGetOrDefault, dictGetOrNull et dictHas dépend du type de clé du dictionnaire :

Pour un dictionnaire avec une clé simple (UInt64), passez directement la valeur de la clé :

SELECT dictGet('simple_key_dictionary', 'attr_name', toUInt64(1));

Pour un dictionnaire avec une clé composite (complexe) de plus d’un attribut, indiquez les valeurs de la clé sous forme de tuple :

SELECT dictGet('complex_key_dictionary', 'attr_name', ('value_for_field1', 42));

Lorsque la clé composite ne comporte qu’un seul attribut, la valeur de la clé peut être transmise directement, sans l’encapsuler dans tuple. Les deux formes suivantes sont valides et équivalentes :

SELECT dictGet('complex_key_dictionary', 'attr_name', 'key');
SELECT dictGet('complex_key_dictionary', 'attr_name', tuple('key'));

Cela s’applique également aux dictionnaires ip_trie, dont la clé est constituée d’un seul attribut. L’adresse IP à rechercher peut être transmise directement :

SELECT dictGet('ip_trie_dictionary', 'attr_name', toIPv4('202.79.32.10'));

dictGet

Introduit dans : v18.16.0 Récupère des valeurs dans un dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGet('dict_name', attr_names, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_names — Nom de la colonne du dictionnaire, ou tuple de noms de colonnes. String ou Tuple(String)
id_expr — Valeur de la clé. Pour un dictionnaire avec une clé simple, expression renvoyant une valeur UInt64. Pour un dictionnaire avec une clé composite (complexe), expression renvoyant un tuple de valeurs de clé. Si la clé composite se compose d’un seul attribut, sa valeur peut être transmise directement, sans être encapsulée dans tuple. UInt64 ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr si la clé est trouvée. Si la clé n’est pas trouvée, renvoie le contenu de l’élément <null_value> spécifié pour l’attribut dans la configuration du dictionnaire. Exemples Récupérer un seul attribut

Query

CREATE TABLE ext_dict_test_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO ext_dict_test_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_test (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'ext_dict_test_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGet('ext_dict_test', 'c1', toUInt64(1)) AS val

Response

Attributs multiples

Query

CREATE TABLE dict_mult_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO dict_mult_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_mult (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT
    dictGet('ext_dict_mult', ('c1','c2'), number + 1) AS val,
    toTypeName(val) AS type
FROM system.numbers
LIMIT 3;

Response

┌─val─────┬─type───────────┐
├─c1─┬─c2─┼────────────────┤
│  1 │ 1  │ Tuple(        ↴│
│    │    │↳    c1 UInt32,↴│
│    │    │↳    c2 String) │
│  2 │ 2  │ Tuple(        ↴│
│    │    │↳    c1 UInt32,↴│
│    │    │↳    c2 String) │
│  3 │ 3  │ Tuple(        ↴│
│    │    │↳    c1 UInt32,↴│
│    │    │↳    c2 String) │
└────┴────┴────────────────┘

dictGetAll

Introduit dans : v23.5.0 Récupère les valeurs d’attribut de tous les nœuds correspondant à chaque clé dans un dictionnaire en arbre d’expressions régulières. Hormis le fait qu’elle renvoie des valeurs de type Array(T) au lieu de T, cette fonction se comporte comme dictGet.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetAll(dict_name, attr_names, id_expr[, limit])

Arguments

dict_name — Nom du dictionnaire. String
attr_names — Nom de la colonne du dictionnaire, ou tuple de noms de colonnes. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
limit — Facultatif. Longueur maximale de chaque tableau de valeurs renvoyé. En cas de troncature, les nœuds enfants ont priorité sur les nœuds parents ; sinon, l’ordre de liste défini pour le dictionnaire regexp tree est respecté. S’il n’est pas spécifié, la longueur du tableau est illimitée. UInt*

Valeur renvoyée Renvoie un tableau des valeurs d’attribut du dictionnaire correspondant à id_expr pour chaque attribut spécifié par attr_names. S’il n’existe aucune clé correspondant à id_expr dans le dictionnaire, un tableau vide est renvoyé.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Array(T) Exemples Exemple d’utilisation

Query

CREATE TABLE regexp_os (id UInt64, parent_id UInt64, regexp String, keys Array(String), values Array(String)) ENGINE = Memory;
INSERT INTO regexp_os VALUES
    (1, 0, 'Linux',      ['os_replacement'], ['Linux']),
    (2, 1, 'Android',    ['os_replacement'], ['Android']),
    (3, 2, 'Android 1',  ['os_replacement'], ['Android']),
    (4, 3, 'Android 12', ['os_replacement'], ['Android']);
CREATE DICTIONARY regexp_tree (regexp String, os_replacement String DEFAULT 'Other') PRIMARY KEY regexp SOURCE(CLICKHOUSE(TABLE 'regexp_os' DB currentDatabase())) LIFETIME(MIN 0 MAX 0) LAYOUT(REGEXP_TREE);
SELECT
    'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36' AS user_agent,

    -- This will match ALL applicable patterns
    dictGetAll('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS all_matches,

    -- This returns only the first match
    dictGet('regexp_tree', 'os_replacement', 'Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36') AS first_match;

Response

┌─user_agent─────────────────────────────────────────────────────┬─all_matches─────────────────────────────┬─first_match─┐
│ Mozilla/5.0 (Linux; Android 12; SM-G998B) Mobile Safari/537.36 │ ['Android','Android','Android','Linux'] │ Android     │
└────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴─────────────┘

dictGetChildren

Introduit dans : v21.4.0 Renvoie les enfants du premier niveau sous forme de tableau d’indices. Il s’agit de la transformation inverse de dictGetHierarchy.

Cette fonction n’est pas déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetChildren(dict_name, key)

Arguments

dict_name — Nom du dictionnaire. String
key — Clé à vérifier. const String

Valeur renvoyée Renvoie les enfants de premier niveau de la clé. Array(UInt64) Exemples Récupérer les enfants de premier niveau d’un dictionnaire

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetChildren('hierarchical_dictionary', 2);

Response

┌─dictGetChildren('hierarchical_dictionary', 2)─┐
│ [4,5]                                         │
└───────────────────────────────────────────────┘

dictGetDate

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données Date, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetDate(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon renvoie le contenu de l’élément <null_value> spécifié pour l’attribut dans la configuration du dictionnaire.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Date_value Date) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2020-01-01');
CREATE DICTIONARY all_types_dict (id UInt32, Date_value Date) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDate('all_types_dict', 'Date_value', 1)

Response

┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2020-01-01 │
└────────────────────────────────────────────────┘

dictGetDateOrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Date, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetDateOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur passée dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Date_value Date) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15');
CREATE DICTIONARY all_types_dict (id UInt32, Date_value Date) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetDate('all_types_dict', 'Date_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'));

Response

┌─dictGetDate('all_types_dict', 'Date_value', 1)─┐
│                                     2024-01-15 │
└────────────────────────────────────────────────┘
┌─dictGetDateOrDefault('all_types_dict', 'Date_value', 999, toDate('1970-01-01'))─┐
│                                                                      1970-01-01 │
└─────────────────────────────────────────────────────────────────────────────────┘

dictGetDateTime

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données DateTime, quelle que soit la configuration du dictionnaire.

Cette fonction n’est pas déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetDateTime(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr ; sinon, renvoie le contenu de l’élément <null_value> spécifié pour l’attribut dans la configuration du dictionnaire.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1)

Response

┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘

dictGetDateTimeOrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données DateTime, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé n’est pas trouvée.

Cette fonction n’est pas déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetDateTimeOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de la clé du dictionnaire ou une valeur tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient aucune ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, DateTime_value DateTime) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2024-01-15 10:30:00');
CREATE DICTIONARY all_types_dict (id UInt32, DateTime_value DateTime) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetDateTime('all_types_dict', 'DateTime_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'));

Response

┌─dictGetDateTime('all_types_dict', 'DateTime_value', 1)─┐
│                                    2024-01-15 10:30:00 │
└────────────────────────────────────────────────────────┘
┌─dictGetDateTimeOrDefault('all_types_dict', 'DateTime_value', 999, toDateTime('1970-01-01 00:00:00'))─┐
│                                                                                  1970-01-01 00:00:00 │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictGetDescendants

Introduit dans : v21.4.0 Renvoie tous les descendants comme si la fonction dictGetChildren était appliquée récursivement level fois.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetDescendants(dict_name, key, level)

Arguments

dict_name — Nom du dictionnaire. String
key — Clé à vérifier. const String
level — Clé à vérifier. Niveau hiérarchique. Si level = 0, renvoie tous les descendants. UInt8

Valeur renvoyée Renvoie les descendants de la clé. Array(UInt64) Exemples Obtenir les enfants du premier niveau d’un dictionnaire

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
--     ├── 2 (Level 2 - Node 2)
--     │   ├── 4 (Level 3 - Node 4)
--     │   └── 5 (Level 3 - Node 5)
--     └── 3 (Level 2 - Node 3)
--         └── 6 (Level 3 - Node 6)

SELECT dictGetDescendants('hierarchical_dictionary', 0, 2)

Response

┌─dictGetDescendants('hierarchical_dictionary', 0, 2)─┐
│ [3,2]                                               │
└─────────────────────────────────────────────────────┘

dictGetFloat32

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Float32, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetFloat32(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1)

Response

┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                             -123.123 │
└──────────────────────────────────────────────────────┘

dictGetFloat32OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Float32, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé n’est pas trouvée.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetFloat32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur transmise via le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Float32_value Float32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 123.45);
CREATE DICTIONARY all_types_dict (id UInt32, Float32_value Float32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetFloat32('all_types_dict', 'Float32_value', 1);

-- for key which does not exist, returns the provided default value (-1.0)
SELECT dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.0);

Response

┌─dictGetFloat32('all_types_dict', 'Float32_value', 1)─┐
│                                               123.45 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat32OrDefault('all_types_dict', 'Float32_value', 999, -1.)─┐
│                                                                   -1 │
└──────────────────────────────────────────────────────────────────────┘

dictGetFloat64

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Float64, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetFloat64(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de la clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne parvient pas à analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -123.123);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1)

Response

┌─dictGetFloat64('all_types_dict', 'Float64_value', 1)─┐
│                                             -123.123 │
└──────────────────────────────────────────────────────┘

dictGetFloat64OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Float64, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetFloat64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon renvoie la valeur transmise via le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Float64_value Float64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 987654.123456);
CREATE DICTIONARY all_types_dict (id UInt32, Float64_value Float64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetFloat64('all_types_dict', 'Float64_value', 1);

-- for key which does not exist, returns the provided default value (nan)
SELECT dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan);

Response

┌─dictGetFloat64('all_types_dict', 'Float64_value', 1)─┐
│                                        987654.123456 │
└──────────────────────────────────────────────────────┘
┌─dictGetFloat64OrDefault('all_types_dict', 'Float64_value', 999, nan)─┐
│                                                                  nan │
└──────────────────────────────────────────────────────────────────────┘

dictGetHierarchy

Introduit dans : v1.1.0 Crée un tableau contenant tous les parents d’une clé dans le dictionnaire hiérarchique.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetHierarchy(dict_name, key)

Arguments

dict_name — Nom du dictionnaire. String
key — Valeur de la clé. const String

Valeur renvoyée Renvoie les parents associés à la clé. Array(UInt64) Exemples Obtenir la hiérarchie d’une clé

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetHierarchy('hierarchical_dictionary', 5)

Response

┌─dictGetHierarchy('hierarchical_dictionary', 5)─┐
│ [5,2,1]                                        │
└────────────────────────────────────────────────┘

dictGetIPv4

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données IPv4, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetIPv4(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1)

Response

┌─dictGetIPv4('all_types_dict', 'IPv4_value', 1)─┐
│ 192.168.0.1                                    │
└────────────────────────────────────────────────┘

dictGetIPv4OrDefault

Introduit dans : v23.1.0 Convertit une valeur d’attribut de dictionnaire en type de données IPv4, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé n’est pas trouvée.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetIPv4OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon renvoie la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, IPv4_value IPv4) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '192.168.0.1');
CREATE DICTIONARY all_types_dict (id UInt32, IPv4_value IPv4) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetIPv4('all_types_dict', 'IPv4_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'));

Response

┌─dictGetIPv4('all_types_dict', 'IPv4_value', 1)─┐
│ 192.168.0.1                                    │
└────────────────────────────────────────────────┘
┌─dictGetIPv4OrDefault('all_types_dict', 'IPv4_value', 999, toIPv4('0.0.0.0'))─┐
│ 0.0.0.0                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘

dictGetIPv6

Introduit dans : v23.1.0 Convertit une valeur d’attribut de dictionnaire en type de données IPv6, indépendamment de la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetIPv6(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne parvient pas à analyser la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1)

Response

┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334                   │
└────────────────────────────────────────────────┘

dictGetIPv6OrDefault

Introduit dans : v23.1.0 Convertit une valeur d’attribut de dictionnaire en type de données IPv6, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé n’est pas trouvée.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetIPv6OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient aucune ligne correspondant à la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon renvoie la valeur passée via le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, IPv6_value IPv6) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '2001:db8:85a3::8a2e:370:7334');
CREATE DICTIONARY all_types_dict (id UInt32, IPv6_value IPv6) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetIPv6('all_types_dict', 'IPv6_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, '::1'::IPv6);

Response

┌─dictGetIPv6('all_types_dict', 'IPv6_value', 1)─┐
│ 2001:db8:85a3::8a2e:370:7334                   │
└────────────────────────────────────────────────┘
┌─dictGetIPv6OrDefault('all_types_dict', 'IPv6_value', 999, CAST('::1', 'IPv6'))─┐
│ ::1                                                                            │
└────────────────────────────────────────────────────────────────────────────────┘

dictGetInt16

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Int16, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt16(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon, renvoie le contenu de l’élément <null_value> spécifié pour cet attribut dans la configuration du dictionnaire.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1)

Response

┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘

dictGetInt16OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Int16, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient aucune ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int16_value Int16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -5000);
CREATE DICTIONARY all_types_dict (id UInt32, Int16_value Int16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt16('all_types_dict', 'Int16_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1);

Response

┌─dictGetInt16('all_types_dict', 'Int16_value', 1)─┐
│                                            -5000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt16OrDefault('all_types_dict', 'Int16_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt32

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Int32, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt32(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon, renvoie le contenu de l’élément <null_value> spécifié pour l’attribut dans la configuration du dictionnaire.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1)

Response

┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘

dictGetInt32OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Int32, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur transmise via le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int32_value Int32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -1000000);
CREATE DICTIONARY all_types_dict (id UInt32, Int32_value Int32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt32('all_types_dict', 'Int32_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1);

Response

┌─dictGetInt32('all_types_dict', 'Int32_value', 1)─┐
│                                         -1000000 │
└──────────────────────────────────────────────────┘
┌─dictGetInt32OrDefault('all_types_dict', 'Int32_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt64

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données Int64, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt64(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1)

Response

┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775807 │
└──────────────────────────────────────────────────┘

dictGetInt64OrDefault

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données Int64, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de la clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr ; sinon, renvoie la valeur transmise via le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int64_value Int64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -9223372036854775808);
CREATE DICTIONARY all_types_dict (id UInt32, Int64_value Int64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt64('all_types_dict', 'Int64_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1);

Response

┌─dictGetInt64('all_types_dict', 'Int64_value', 1)─┐
│                             -9223372036854775808 │
└──────────────────────────────────────────────────┘
┌─dictGetInt64OrDefault('all_types_dict', 'Int64_value', 999, -1)─┐
│                                                              -1 │
└─────────────────────────────────────────────────────────────────┘

dictGetInt8

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Int8, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt8(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1)

Response

┌─dictGetInt8('all_types_dict', 'Int8_value', 1)─┐
│                                           -100 │
└────────────────────────────────────────────────┘

dictGetInt8OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données Int8, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne correspondant à la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, Int8_value Int8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, -100);
CREATE DICTIONARY all_types_dict (id UInt32, Int8_value Int8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetInt8('all_types_dict', 'Int8_value', 1);

-- for key which does not exist, returns the provided default value (-1)
SELECT dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1);

Response

┌─dictGetInt8('all_types_dict', 'Int8_value', 1)─┐
│                                           -100 │
└────────────────────────────────────────────────┘
┌─dictGetInt8OrDefault('all_types_dict', 'Int8_value', 999, -1)─┐
│                                                            -1 │
└───────────────────────────────────────────────────────────────┘

dictGetKeys

Introduit dans : v25.12.0 Renvoie la ou les clés du dictionnaire dont l’attribut correspond à la valeur spécifiée. Il s’agit de l’inverse de la fonction dictGet sur un attribut unique. Utilisez le paramètre max_reverse_dictionary_lookup_cache_size_bytes pour limiter la taille du cache de recherche inverse par requête utilisé par dictGetKeys. Le cache stocke des tuples de clés sérialisés pour chaque valeur d’attribut afin d’éviter de parcourir à nouveau le dictionnaire au cours de la même requête. Le cache n’est pas conservé d’une requête à l’autre. Lorsque la limite est atteinte, les entrées sont supprimées selon la politique LRU. Ce mécanisme est particulièrement efficace avec de grands dictionnaires lorsque l’entrée présente une faible cardinalité et que l’ensemble de travail tient dans le cache. Définissez cette valeur sur 0 pour désactiver la mise en cache.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetKeys('dict_name', 'attr_name', value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Attribut à comparer. String
value_expr — Valeur à comparer à l’attribut. Expression

Valeur renvoyée Pour les dictionnaires à clé unique : un tableau de clés dont l’attribut correspond à value_expr. Pour les dictionnaires à clés multiples : un tableau de tuples de clés dont l’attribut correspond à value_expr. S’il n’existe aucun attribut correspondant à value_expr dans le dictionnaire, un tableau vide est renvoyé. ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne peut pas être convertie dans le type de données de l’attribut. Exemples Exemple d’utilisation

Query

CREATE TABLE task_priority_source (task_id UInt64, priority_level String) ENGINE = Memory;
INSERT INTO task_priority_source VALUES (1, 'low'), (2, 'high'), (3, 'medium'), (4, 'high');
CREATE DICTIONARY task_id_to_priority_dictionary (task_id UInt64, priority_level String) PRIMARY KEY task_id SOURCE(CLICKHOUSE(TABLE 'task_priority_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 0 MAX 0);
SELECT arraySort(dictGetKeys('task_id_to_priority_dictionary', 'priority_level', 'high')) AS ids;

Response

┌─ids───┐
│ [2,4] │
└───────┘

dictGetOrDefault

Introduit dans : v18.16.0 Récupère des valeurs d’un dictionnaire, avec une valeur par défaut si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetOrDefault('dict_name', attr_names, id_expr, default_value)

Arguments

dict_name — Nom du dictionnaire. String
attr_names — Nom de la colonne du dictionnaire, ou tuple de noms de colonnes. String ou Tuple(String)
id_expr — Valeur de la clé. Pour un dictionnaire avec une clé simple, une expression renvoyant une valeur UInt64. Pour un dictionnaire avec une clé composite (complexe), une expression renvoyant un tuple des valeurs de la clé. Si la clé composite se compose d’un seul attribut, sa valeur peut être transmise directement, sans être encapsulée dans tuple. UInt64 ou Tuple(T)
default_value — Valeur par défaut à renvoyer si la clé n’est pas trouvée. Le type doit correspondre au type de données de l’attribut.

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr si la clé est trouvée. Si la clé n’est pas trouvée, renvoie la default_value fournie. Exemples Obtenir la valeur avec une valeur par défaut

Query

CREATE TABLE dict_mult_source (id UInt32, c1 UInt32, c2 String) ENGINE = Memory;
INSERT INTO dict_mult_source VALUES (1, 1, '1'), (2, 2, '2'), (3, 3, '3');
CREATE DICTIONARY ext_dict_mult (id UInt32, c1 UInt32, c2 String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'dict_mult_source' DB currentDatabase())) LAYOUT(FLAT()) LIFETIME(MIN 0 MAX 0);
SELECT dictGetOrDefault('ext_dict_mult', 'c1', toUInt64(999), 0) AS val

Response

dictGetOrNull

Introduit dans : v21.4.0 Récupère des valeurs dans un dictionnaire et renvoie NULL si la clé est introuvable.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetOrNull('dict_name', 'attr_name', id_expr)

Arguments

dict_name — Nom du dictionnaire. Littéral de chaîne. - attr_name — Nom de la colonne à récupérer. Littéral de chaîne. - id_expr — Valeur de clé. Expression renvoyant une valeur du type de la clé du dictionnaire.

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr si la clé est trouvée. Si la clé n’est pas trouvée, renvoie NULL. Exemples Exemple avec le dictionnaire à clé d’intervalle

Query

CREATE TABLE range_key_dictionary_source_table (key UInt64, start_date Date, end_date Date, value String, value_nullable Nullable(String)) ENGINE = TinyLog();
INSERT INTO range_key_dictionary_source_table VALUES(1, toDate('2019-05-20'), toDate('2019-05-20'), 'First', 'First');
INSERT INTO range_key_dictionary_source_table VALUES(2, toDate('2019-05-20'), toDate('2019-05-20'), 'Second', NULL);
INSERT INTO range_key_dictionary_source_table VALUES(3, toDate('2019-05-20'), toDate('2019-05-20'), 'Third', 'Third');
CREATE DICTIONARY range_key_dictionary (key UInt64, start_date Date, end_date Date, value String, value_nullable Nullable(String)) PRIMARY KEY key SOURCE(CLICKHOUSE(TABLE 'range_key_dictionary_source_table' DB currentDatabase())) LIFETIME(MIN 1 MAX 1000) LAYOUT(RANGE_HASHED()) RANGE(MIN start_date MAX end_date);
SELECT
    (number, toDate('2019-05-20')),
    dictGetOrNull('range_key_dictionary', 'value', number, toDate('2019-05-20')),
FROM system.numbers LIMIT 5 FORMAT TabSeparated;

Response

(0,'2019-05-20')	\N
(1,'2019-05-20')	First
(2,'2019-05-20')	Second
(3,'2019-05-20')	Third
(4,'2019-05-20')	\N

dictGetRoot

Introduit dans : v26.7.0 Renvoyer l’ancêtre le plus haut (la racine) d’une clé dans un dictionnaire hiérarchique. Il s’agit d’un équivalent pratique consistant à prendre le dernier élément du tableau renvoyé par dictGetHierarchy, c.-à-d. dictGetHierarchy(dict_name, key)[-1]. Si la clé est elle-même un nœud de niveau supérieur dans la hiérarchie, la clé est renvoyée. Si la clé est absente du dictionnaire, 0 est renvoyé.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetRoot(dict_name, key)

Arguments

dict_name — Nom du dictionnaire. String
key — Valeur de la clé. UInt64

Valeur renvoyée Renvoie l’ancêtre le plus haut (la racine) pour la clé. UInt64 Exemples Obtenir la racine d’une clé

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetRoot('hierarchical_dictionary', 5)

Response

┌─dictGetRoot('hierarchical_dictionary', 5)─┐
│                                         1 │
└───────────────────────────────────────────┘

dictGetString

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données String, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetString(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, le contenu de l’élément <null_value> spécifié pour l’attribut dans la configuration du dictionnaire.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetString('all_types_dict', 'String_value', 1)

Response

┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘

dictGetStringOrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données String, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetStringOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient aucune ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur passée dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, String_value String) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 'test string');
CREATE DICTIONARY all_types_dict (id UInt32, String_value String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetString('all_types_dict', 'String_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default');

Response

┌─dictGetString('all_types_dict', 'String_value', 1)─┐
│ test string                                        │
└────────────────────────────────────────────────────┘
┌─dictGetStringOrDefault('all_types_dict', 'String_value', 999, 'default')─┐
│ default                                                                  │
└──────────────────────────────────────────────────────────────────────────┘

dictGetUInt16

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données UInt16, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt16(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne parvient pas à analyser la valeur de l’attribut ou si celle-ci ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1)

Response

┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘

dictGetUInt16OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données UInt16, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé n’est pas trouvée.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt16OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne correspondant à la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur passée dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt16_value UInt16) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 5000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt16_value UInt16) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt16('all_types_dict', 'UInt16_value', 1);

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0);

Response

┌─dictGetUInt16('all_types_dict', 'UInt16_value', 1)─┐
│                                               5000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt16OrDefault('all_types_dict', 'UInt16_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt32

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données UInt32, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt32(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1)

Response

┌─dictGetUInt32('all_types_dict', 'UInt32_value', 1)─┐
│                                            1000000 │
└────────────────────────────────────────────────────┘

dictGetUInt32OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données UInt32, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt32OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr ; sinon, renvoie la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne parvient pas à analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt32_value UInt32) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 1000000);
CREATE DICTIONARY all_types_dict (id UInt32, UInt32_value UInt32) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt32('all_types_dict', 'UInt32_value', 1);

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0);

Response

┌─dictGetUInt32('all_types_dict', 'UInt32_value', 1)─┐
│                                            1000000 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt32OrDefault('all_types_dict', 'UInt32_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt64

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données UInt64, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt64(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1)

Response

┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘

dictGetUInt64OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données UInt64, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt64OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient aucune ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, ou, à défaut, la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt64_value UInt64) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 9223372036854775807);
CREATE DICTIONARY all_types_dict (id UInt32, UInt64_value UInt64) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt64('all_types_dict', 'UInt64_value', 1);

-- for key which does not exist, returns the provideddefault value (0)
SELECT dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0);

Response

┌─dictGetUInt64('all_types_dict', 'UInt64_value', 1)─┐
│                                9223372036854775807 │
└────────────────────────────────────────────────────┘
┌─dictGetUInt64OrDefault('all_types_dict', 'UInt64_value', 999, 0)─┐
│                                                                0 │
└──────────────────────────────────────────────────────────────────┘

dictGetUInt8

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données UInt8, quelle que soit la configuration du dictionnaire.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt8(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1)

Response

┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘

dictGetUInt8OrDefault

Introduit dans : v1.1.0 Convertit une valeur d’attribut de dictionnaire en type de données UInt8, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUInt8OrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne avec la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr, sinon renvoie la valeur transmise dans le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas interpréter la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UInt8_value UInt8) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, 100);
CREATE DICTIONARY all_types_dict (id UInt32, UInt8_value UInt8) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUInt8('all_types_dict', 'UInt8_value', 1);

-- for key which does not exist, returns the provided default value (0)
SELECT dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0);

Response

┌─dictGetUInt8('all_types_dict', 'UInt8_value', 1)─┐
│                                              100 │
└──────────────────────────────────────────────────┘
┌─dictGetUInt8OrDefault('all_types_dict', 'UInt8_value', 999, 0)─┐
│                                                              0 │
└────────────────────────────────────────────────────────────────┘

dictGetUUID

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données UUID, quelle que soit la configuration du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUUID(dict_name, attr_name, id_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de clé. Expression renvoyant une valeur de type clé de dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)

ClickHouse lève une exception s’il ne parvient pas à analyser la valeur de l’attribut ou si la valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '123e4567-e89b-12d3-a456-426614174000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1)

Response

┌─dictGetUUID('all_types_dict', 'UUID_value', 1)─┐
│ 123e4567-e89b-12d3-a456-426614174000           │
└────────────────────────────────────────────────┘

dictGetUUIDOrDefault

Introduit dans : v1.1.0 Convertit la valeur d’un attribut de dictionnaire en type de données UUID, quelle que soit la configuration du dictionnaire, ou renvoie la valeur par défaut fournie si la clé est introuvable.

Cette fonction est non déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictGetUUIDOrDefault(dict_name, attr_name, id_expr, default_value_expr)

Arguments

dict_name — Nom du dictionnaire. String
attr_name — Nom de la colonne du dictionnaire. String ou Tuple(String)
id_expr — Valeur de la clé. Expression renvoyant une valeur du type de clé du dictionnaire ou une valeur de tuple (selon la configuration du dictionnaire). Expression ou Tuple(T)
default_value_expr — Valeur(s) renvoyée(s) si le dictionnaire ne contient pas de ligne correspondant à la clé id_expr. Expression ou Tuple(T)

Valeur renvoyée Renvoie la valeur de l’attribut du dictionnaire correspondant à id_expr ; sinon, renvoie la valeur transmise via le paramètre default_value_expr.

ClickHouse lève une exception s’il ne peut pas analyser la valeur de l’attribut ou si cette valeur ne correspond pas au type de données de l’attribut.

Exemples Exemple d’utilisation

Query

CREATE TABLE all_types_test (id UInt32, UUID_value UUID) ENGINE = MergeTree() ORDER BY id;
INSERT INTO all_types_test VALUES (1, '550e8400-e29b-41d4-a716-446655440000');
CREATE DICTIONARY all_types_dict (id UInt32, UUID_value UUID) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'all_types_test' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- for key which exists
SELECT dictGetUUID('all_types_dict', 'UUID_value', 1);

-- for key which does not exist, returns the provided default value
SELECT dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, '00000000-0000-0000-0000-000000000000'::UUID);

Response

┌─dictGetUUID('all_types_dict', 'UUID_value', 1)─┐
│ 550e8400-e29b-41d4-a716-446655440000           │
└────────────────────────────────────────────────┘
┌─dictGetUUIDOrDefault('all_types_dict', 'UUID_value', 999, CAST('00000000-0000-0000-0000-000000000000', 'UUID'))─┐
│ 00000000-0000-0000-0000-000000000000                                                                            │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

dictHas

Introduit dans : v1.1.0 Vérifie si une clé est présente dans un dictionnaire.

Cette fonction n’est pas déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictHas('dict_name', id_expr)

Arguments

dict_name — Nom du dictionnaire. String
id_expr — Valeur de la clé const String

Valeur renvoyée Renvoie 1 si la clé existe, sinon 0. UInt8 Exemples Vérifier l’existence d’une clé dans un dictionnaire

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- consider the following hierarchical dictionary:
-- 0 (Root)
-- └── 1 (Level 1 - Node 1)
--     ├── 2 (Level 2 - Node 2)
--     │   ├── 4 (Level 3 - Node 4)
--     │   └── 5 (Level 3 - Node 5)
--     └── 3 (Level 2 - Node 3)
--         └── 6 (Level 3 - Node 6)

SELECT dictHas('hierarchical_dictionary', 2);
SELECT dictHas('hierarchical_dictionary', 7);

Response

┌─dictHas('hierarchical_dictionary', 2)─┐
│                                     1 │
└───────────────────────────────────────┘
┌─dictHas('hierarchical_dictionary', 7)─┐
│                                     0 │
└───────────────────────────────────────┘

dictIsIn

Introduit dans : v1.1.0 Vérifie l’ancêtre d’une clé sur l’ensemble de la chaîne hiérarchique du dictionnaire.

Cette fonction est non-déterministe : elle peut renvoyer des résultats différents pour les mêmes arguments.

Syntaxe

dictIsIn(dict_name, child_id_expr, ancestor_id_expr)

Arguments

dict_name — Nom du dictionnaire. String
child_id_expr — Clé à vérifier. String
ancestor_id_expr — Ancêtre présumé de la clé child_id_expr. const String

Valeur renvoyée Renvoie 0 si child_id_expr n’est pas un enfant de ancestor_id_expr, et 1 si child_id_expr est un enfant de ancestor_id_expr ou si child_id_expr est égal à ancestor_id_expr. UInt8 Exemples Vérification de la relation hiérarchique

Query

CREATE TABLE hierarchy_source (id UInt64, parent_id UInt64, name String) ENGINE = Memory;
INSERT INTO hierarchy_source VALUES (0, 0, 'Root'), (1, 0, 'Level 1 - Node 1'), (2, 1, 'Level 2 - Node 2'), (3, 1, 'Level 2 - Node 3'), (4, 2, 'Level 3 - Node 4'), (5, 2, 'Level 3 - Node 5'), (6, 3, 'Level 3 - Node 6');
CREATE DICTIONARY hierarchical_dictionary (id UInt64, parent_id UInt64 HIERARCHICAL, name String) PRIMARY KEY id SOURCE(CLICKHOUSE(TABLE 'hierarchy_source' DB currentDatabase())) LAYOUT(HASHED()) LIFETIME(MIN 300 MAX 600);
-- valid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 6, 3);

-- invalid hierarchy
SELECT dictIsIn('hierarchical_dictionary', 3, 5);

Response

┌─dictIsIn('hierarchical_dictionary', 6, 3)─┐
│                                         1 │
└───────────────────────────────────────────┘
┌─dictIsIn('hierarchical_dictionary', 3, 5)─┐
│                                         0 │
└───────────────────────────────────────────┘

​Exemples de dictionnaires

​Passage des clés aux fonctions de dictionnaire

​dictGet

​dictGetAll

​dictGetChildren

​dictGetDate

​dictGetDateOrDefault

​dictGetDateTime

​dictGetDateTimeOrDefault

​dictGetDescendants

​dictGetFloat32

​dictGetFloat32OrDefault

​dictGetFloat64

​dictGetFloat64OrDefault

​dictGetHierarchy

​dictGetIPv4

​dictGetIPv4OrDefault

​dictGetIPv6

​dictGetIPv6OrDefault

​dictGetInt16

​dictGetInt16OrDefault

​dictGetInt32

​dictGetInt32OrDefault

​dictGetInt64

​dictGetInt64OrDefault

​dictGetInt8

​dictGetInt8OrDefault

​dictGetKeys

​dictGetOrDefault

​dictGetOrNull

​dictGetRoot

​dictGetString

​dictGetStringOrDefault

​dictGetUInt16

​dictGetUInt16OrDefault

​dictGetUInt32

​dictGetUInt32OrDefault

​dictGetUInt64

​dictGetUInt64OrDefault

​dictGetUInt8

​dictGetUInt8OrDefault

​dictGetUUID

​dictGetUUIDOrDefault

​dictHas

​dictIsIn

Exemples de dictionnaires

Passage des clés aux fonctions de dictionnaire

dictGet

dictGetAll

dictGetChildren

dictGetDate

dictGetDateOrDefault

dictGetDateTime

dictGetDateTimeOrDefault

dictGetDescendants

dictGetFloat32

dictGetFloat32OrDefault

dictGetFloat64

dictGetFloat64OrDefault

dictGetHierarchy

dictGetIPv4

dictGetIPv4OrDefault

dictGetIPv6

dictGetIPv6OrDefault

dictGetInt16

dictGetInt16OrDefault

dictGetInt32

dictGetInt32OrDefault

dictGetInt64

dictGetInt64OrDefault

dictGetInt8

dictGetInt8OrDefault

dictGetKeys

dictGetOrDefault

dictGetOrNull

dictGetRoot

dictGetString

dictGetStringOrDefault

dictGetUInt16

dictGetUInt16OrDefault

dictGetUInt32

dictGetUInt32OrDefault

dictGetUInt64

dictGetUInt64OrDefault

dictGetUInt8

dictGetUInt8OrDefault

dictGetUUID

dictGetUUIDOrDefault

dictHas

dictIsIn