Layouts de dictionnaires

Types de layout de dictionnaire

Il existe plusieurs façons de stocker les dictionnaires en mémoire, chacune avec ses propres compromis en termes d’utilisation du CPU et de la RAM.

Layout	Description
flat	Stocke les données dans des tableaux simples indexés par clé. C’est le layout le plus rapide, mais les clés doivent être de type `UInt64` et rester inférieures à `max_array_size`.
hashed	Stocke les données dans une table de hachage. Aucune limite sur la taille des clés, et prend en charge n’importe quel nombre d’éléments.
sparse_hashed	Comme `hashed`, mais avec un compromis en faveur d’une utilisation mémoire plus faible au prix du CPU.
complex_key_hashed	Comme `hashed`, pour les clés composites.
complex_key_sparse_hashed	Comme `sparse_hashed`, pour les clés composites.
hashed_array	Attributs stockés dans des tableaux, avec une table de hachage qui associe les clés aux indices des tableaux. Économe en mémoire lorsqu’il y a de nombreux attributs.
complex_key_hashed_array	Comme `hashed_array`, pour les clés composites.
range_hashed	Table de hachage avec plages ordonnées. Prend en charge les recherches par clé + plage de dates/heures.
complex_key_range_hashed	Comme `range_hashed`, pour les clés composites.
cache	Cache en mémoire de taille fixe. Seules les clés fréquemment consultées sont stockées.
complex_key_cache	Comme `cache`, pour les clés composites.
ssd_cache	Comme `cache`, mais stocke les données sur SSD avec un index en mémoire.
complex_key_ssd_cache	Comme `ssd_cache`, pour les clés composites.
direct	Aucun stockage en mémoire — interroge directement la source pour chaque requête.
complex_key_direct	Comme `direct`, pour les clés composites.
ip_trie	Structure en trie pour des recherches rapides de préfixes IP (basées sur CIDR).
hierarchical	Prise en charge des hiérarchies avec une clé numérique décrivant les relations parent-enfant.
polygon	Recherches point-dans-polygone efficaces (géocodage inversé).
regexp_tree	Fait correspondre les clés à un arbre d’expressions régulières.

Layouts recommandésflat, hashed et complex_key_hashed offrent les meilleures performances de requête. Les layouts de cache ne sont pas recommandés en raison de performances potentiellement médiocres et de la difficulté à régler les paramètres — voir cache pour plus de détails.

Les layouts basés sur un cache ne permettent pas un enrichissement fiable au moment de l’insertion : leurs entrées mises en cache sont propres à chaque serveur et sont perdues lorsqu’un serveur redémarre ou est remplacé. L’autoscaling et le remplacement géré des nœuds dans ClickHouse Cloud rendent ce cas de figure plus probable. Privilégiez plutôt un layout entièrement chargé ; voir Dictionnaires de cache dans les chemins d’ingestion.

Spécifier le layout du dictionnaire

Si vous utilisez un dictionary avec ClickHouse Cloud, utilisez l’option DDL query pour créer vos dictionaries, et créez votre dictionary en tant qu’utilisateur default. Vérifiez également la liste des dictionary sources prises en charge dans le guide de compatibilité Cloud.

Vous pouvez configurer le layout d’un dictionnaire avec la clause LAYOUT (pour le DDL) ou le paramètre layout dans les définitions du fichier de configuration.

DDL
Fichier de configuration

CREATE DICTIONARY (...)
...
LAYOUT(LAYOUT_TYPE(param value)) -- paramètres de layout
...

<clickhouse>
    <dictionary>
        ...
        <layout>
            <layout_type>
                <!-- paramètres de layout -->
            </layout_type>
        </layout>
        ...
    </dictionary>
</clickhouse>

Voir aussi CREATE DICTIONARY pour la syntaxe DDL complète. Les dictionnaires dont le layout ne contient pas complex-key* ont une clé de type UInt64 ; les dictionnaires complex-key* ont une clé composite (complexe, avec des types arbitraires). Exemple de clé numérique (la colonne key_column est de type UInt64) :

DDL
Fichier de configuration

CREATE DICTIONARY dict_name (
    key_column UInt64,
    ...
)
PRIMARY KEY key_column

<structure>
    <id>
        <name>key_column</name>
    </id>
    ...
</structure>

Exemple de clé composite (la clé comporte un élément de type String) :

DDL
Fichier de configuration

CREATE DICTIONARY dict_name (
    country_code String,
    ...
)
PRIMARY KEY country_code

<structure>
    <key>
        <attribute>
            <name>country_code</name>
            <type>String</type>
        </attribute>
    </key>
    ...
</structure>

Améliorer les performances des dictionnaires

Il existe plusieurs façons d’améliorer les performances des dictionnaires :

Appeler la fonction de manipulation du dictionnaire après GROUP BY.
Marquer comme injectifs les attributs à extraire. Un attribut est dit injectif si des clés différentes correspondent à des valeurs d’attribut différentes. Ainsi, lorsque GROUP BY utilise une fonction qui récupère une valeur d’attribut à partir de la clé, cette fonction est automatiquement retirée de GROUP BY.

ClickHouse génère une exception en cas d’erreur liée aux dictionnaires. Voici quelques exemples d’erreurs :

Le dictionnaire auquel l’accès est demandé n’a pas pu être chargé.
Erreur lors d’une requête sur un dictionnaire cached.

Vous pouvez afficher la liste des dictionnaires et leur statut dans la table system.dictionaries.

Référence SQL

Types de données

Moteurs

Fonctions

Formats

Paramètres

Tables système

Lacs de données

Types de layout de dictionnaire

Spécifier le layout du dictionnaire

Améliorer les performances des dictionnaires

​Types de layout de dictionnaire

​Spécifier le layout du dictionnaire

​Améliorer les performances des dictionnaires

Types de layout de dictionnaire

Spécifier le layout du dictionnaire

Améliorer les performances des dictionnaires