Skip to main content
Cette section présente toutes les matérialisations disponibles dans dbt-clickhouse, y compris les fonctionnalités expérimentales.

Configurations générales des matérialisations

Le tableau suivant présente les configurations partagées par certaines des matérialisations disponibles. Pour des informations détaillées sur les configurations générales des modèles dbt, consultez la documentation dbt :

Moteurs de table pris en charge

Remarque : pour les vues matérialisées, tous les moteurs de la famille *MergeTree sont pris en charge.

Moteurs de table pris en charge à titre expérimental

Si vous rencontrez des problèmes de connexion à ClickHouse depuis dbt avec l’un des moteurs ci-dessus, veuillez signaler le problème ici.

Remarque sur les paramètres du modèle

ClickHouse propose plusieurs types/niveaux de « settings ». Dans la configuration du modèle ci-dessus, deux de ces types sont configurables. settings désigne la clause SETTINGS utilisée dans les instructions DDL de type CREATE TABLE/VIEW ; il s’agit donc généralement de paramètres propres au moteur de table ClickHouse concerné. Le nouveau query_settings permet d’ajouter une clause SETTINGS aux requêtes INSERT et DELETE utilisées pour la matérialisation du modèle ( y compris les matérialisations incrémentales). Il existe des centaines de paramètres ClickHouse, et il n’est pas toujours évident de savoir lequel est un paramètre de « table » et lequel est un paramètre « utilisateur » (bien que ces derniers soient généralement disponibles dans la table system.settings.) En règle générale, il est recommandé de conserver les valeurs par défaut, et toute utilisation de ces propriétés doit être soigneusement étudiée et testée.

Configuration des colonnes

REMARQUE : Les options de configuration des colonnes ci-dessous nécessitent l’application des contrats de modèle.

Exemple de configuration de schéma

Ajout de types complexes

dbt détermine automatiquement le type de données de chaque colonne en analysant le SQL utilisé pour créer le modèle. Cependant, dans certains cas, ce processus peut ne pas identifier correctement le type de données, ce qui entraîne des conflits avec les types spécifiés dans la propriété de contrat data_type. Pour y remédier, nous recommandons d’utiliser la fonction CAST() dans le SQL du modèle afin de définir explicitement le type souhaité. Par exemple :

Matérialisation : vue

Un modèle dbt peut être créé sous forme de vue ClickHouse et configuré à l’aide de la syntaxe suivante : Fichier du projet (dbt_project.yml) :
Ou bloc de configuration (models/<model_name>.sql) :

Matérialisation : table

Un modèle dbt peut être créé comme une table ClickHouse et configuré à l’aide de la syntaxe suivante : Fichier de projet (dbt_project.yml) :
Ou bloc de configuration (models/<model_name>.sql) :

Index de saut de données

Vous pouvez ajouter des index de saut de données aux matérialisations table à l’aide de la configuration indexes :

Projections

Vous pouvez ajouter des projections aux matérialisations table et distributed_table à l’aide de la configuration projections :
Remarque : Pour les tables distribuées, la projection s’applique aux tables _local, et non à la table distribuée servant de proxy.

Matérialisation : incrémentielle

Le modèle de type table sera reconstruit à chaque exécution de dbt. Cela peut s’avérer irréaliste et extrêmement coûteux pour des jeux de résultats volumineux ou des transformations complexes. Pour relever ce défi et réduire le temps de build, un modèle dbt peut être créé en tant que table ClickHouse incrémentielle et se configure à l’aide de la syntaxe suivante : Définition du modèle dans dbt_project.yml :
Ou le bloc de configuration dans models/<model_name>.sql :

Configurations

Les configurations spécifiques à ce type de matérialisation sont listées ci-dessous :

Stratégies pour les modèles incrémentaux

dbt-clickhouse prend en charge trois stratégies de modèles incrémentaux.

La stratégie par défaut (legacy)

Historiquement, ClickHouse ne prenait en charge les mises à jour et les suppressions que de façon limitée, sous la forme de « mutations » asynchrones. Pour reproduire le comportement attendu de dbt, dbt-clickhouse crée par défaut une nouvelle table temporaire contenant tous les anciens enregistrements non affectés (non supprimés, non modifiés), ainsi que les enregistrements nouveaux ou mis à jour, puis permute ou échange cette table temporaire avec la relation incremental existante du modèle. C’est la seule stratégie qui préserve la relation d’origine si quelque chose tourne mal avant la fin de l’opération ; toutefois, comme elle implique une copie complète de la table d’origine, son exécution peut s’avérer coûteuse et lente.

La stratégie Delete+Insert

ClickHouse a ajouté les « lightweight deletes » en tant que fonctionnalité expérimentale dans la version 22.8. Les lightweight deletes sont nettement plus rapides que les opérations ALTER TABLE … DELETE, car ils ne nécessitent pas de réécrire les data parts de ClickHouse. La stratégie incrémentielle delete+insert s’appuie sur les lightweight deletes pour implémenter des matérialisations incrémentielles bien plus performantes que la stratégie « legacy ». Cependant, il y a quelques points importants à prendre en compte lors de l’utilisation de cette stratégie :
  • Les lightweight deletes doivent être activés sur votre serveur ClickHouse à l’aide du paramètre allow_experimental_lightweight_delete=1, ou vous devez définir use_lw_deletes=true dans votre profil (ce qui activera ce paramètre pour vos sessions dbt)
  • Les lightweight deletes sont désormais prêts pour un usage en production, mais il peut subsister des problèmes de performances et d’autres problèmes sur les versions de ClickHouse antérieures à 23.3.
  • Cette stratégie agit directement sur la table/relation concernée (sans créer de tables intermédiaires ou temporaires) ; ainsi, en cas de problème pendant l’opération, les données du modèle incrémentiel risquent fort de se retrouver dans un état invalide
  • Lors de l’utilisation des lightweight deletes, dbt-clickhouse active le paramètre allow_nondeterministic_mutations. Dans certains cas très rares, l’utilisation de incremental_predicates non déterministes peut entraîner une situation de concurrence pour les éléments mis à jour/supprimés (ainsi que des messages de journal associés dans les logs ClickHouse). Pour garantir des résultats cohérents, les prédicats incrémentiels ne doivent inclure que des sous-requêtes sur des données qui ne seront pas modifiées pendant la matérialisation incrémentielle.

La stratégie Microbatch (nécessite dbt-core >= 1.9)

La stratégie incrémentale microbatch est une fonctionnalité de dbt-core depuis la version 1.9, conçue pour traiter efficacement de grandes transformations de données chronologiques. Dans dbt-clickhouse, elle s’appuie sur la stratégie incrémentale delete_insert existante en scindant l’incrément en lots chronologiques prédéfinis, selon les configurations de modèle event_time et batch_size. Au-delà de la gestion de transformations volumineuses, microbatch permet de : Pour plus de détails sur l’utilisation de microbatch, consultez la documentation officielle.
Configurations disponibles pour Microbatch

La stratégie Append

Cette stratégie remplace le paramètre inserts_only dans les versions précédentes de dbt-clickhouse. Cette approche ajoute simplement de nouvelles lignes à la relation existante. Par conséquent, les lignes en double ne sont pas éliminées et il n’y a ni table temporaire ni table intermédiaire. C’est l’approche la plus rapide si les doublons sont soit autorisés dans les données, soit exclus par la requête incrémentielle via la clause/le filtre WHERE.

La stratégie insert_overwrite (Expérimental)

[IMPORTANT] Actuellement, la stratégie insert_overwrite n’est pas entièrement fonctionnelle avec les matérialisations distribuées.
Elle exécute les étapes suivantes :
  1. Crée une table de staging (temporaire) avec la même structure que la relation du modèle incrémental : CREATE TABLE <staging> AS <target>.
  2. Insère uniquement les nouveaux enregistrements (produits par SELECT) dans la table de staging.
  3. Remplace uniquement les nouvelles partitions (présentes dans la table de staging) dans la table cible.
Cette approche présente les avantages suivants :
  • Elle est plus rapide que la stratégie par défaut, car elle ne copie pas l’intégralité de la table.
  • Elle est plus sûre que les autres stratégies, car elle ne modifie pas la table d’origine tant que l’opération INSERT n’est pas terminée avec succès : en cas d’échec intermédiaire, la table d’origine n’est pas modifiée.
  • Elle met en œuvre la bonne pratique d’ingénierie des données dite de « l’immutabilité des partitions », ce qui simplifie le traitement incrémental et parallèle des données, les rollbacks, etc.
La stratégie nécessite que partition_by soit défini dans la configuration du modèle. Elle ignore tous les autres paramètres du modèle spécifiques aux stratégies.

Matérialisation : materialized_view

La matérialisation materialized_view crée une vue matérialisée dans ClickHouse, qui fait office de déclencheur d’insertion en transformant et en insérant automatiquement les nouvelles lignes d’une table source vers une table cible. Il s’agit de l’une des matérialisations les plus puissantes disponibles dans dbt-clickhouse. Compte tenu de sa complexité, cette matérialisation dispose de sa propre page dédiée. Consultez le guide des vues matérialisées pour accéder à la documentation complète

Matérialisation : dictionnaire (expérimental)

Consultez les tests dans https://github.com/ClickHouse/dbt-clickhouse/blob/main/tests/integration/adapter/dictionary/test&#95;dictionary.py pour voir des exemples d’implémentation de matérialisations pour les dictionnaires ClickHouse

Matérialisation : distributed_table (expérimental)

Une table distribuée est créée selon les étapes suivantes :
  1. Création d’une vue temporaire avec une requête SQL afin d’obtenir la bonne structure
  2. Création de tables locales vides à partir de la vue
  3. Création d’une table distribuée à partir des tables locales.
  4. Les données sont insérées dans la table distribuée, puis réparties entre les shards sans duplication.
Remarques :
  • Les requêtes dbt-clickhouse incluent désormais automatiquement le paramètre insert_distributed_sync = 1 afin de garantir que les opérations de matérialisation incrémentielle en aval s’exécutent correctement. Cela peut ralentir davantage que prévu certaines insertions dans des tables distribuées.

Exemple de modèle pour une table distribuée

Migrations générées

Configurations

Les configurations propres à ce type de matérialisation sont indiquées ci-dessous :

matérialisation : distributed_incremental (expérimental)

Modèle incrémental fondé sur le même principe qu’une table distribuée ; la principale difficulté consiste à traiter correctement toutes les stratégies incrémentales.
  1. La stratégie Append se contente d’insérer les données dans la table distribuée.
  2. La stratégie Delete+Insert crée une table temporaire distribuée pour travailler avec l’ensemble des données sur chaque shard.
  3. La stratégie Default (Legacy) crée des tables temporaires et intermédiaires distribuées pour la même raison.
Seules les tables de shard sont remplacées, car la table distribuée ne stocke pas les données. La table distribuée n’est rechargée que lorsque le mode full_refresh est activé ou que la structure de la table a pu changer.

Exemple de modèle distributed incremental

Migrations générées

Snapshot

Les snapshots dbt permettent de conserver un historique des modifications apportées à un modèle mutable au fil du temps. Cela permet ensuite d’effectuer des requêtes à un instant donné sur les modèles, afin que les analystes puissent « remonter dans le temps » jusqu’à l’état antérieur d’un modèle. Cette fonctionnalité est prise en charge par le ClickHouse Connector et se configure à l’aide de la syntaxe suivante : Bloc de config dans snapshots/<model_name>.sql:
Pour en savoir plus sur la configuration, consultez la page de référence snapshot configs.

Contrats et contraintes

Seuls les contrats correspondant exactement au type de la colonne sont pris en charge. Par exemple, un contrat avec une colonne de type UInt32 échouera si le modèle renvoie un UInt64 ou un autre type entier. ClickHouse ne prend également en charge que les contraintes CHECK sur l’ensemble de la table/du modèle. Les contraintes de clé primaire, de clé étrangère, d’unicité et les contraintes CHECK au niveau des colonnes ne sont pas prises en charge. (Voir la documentation ClickHouse sur les clés primaires et les clés ORDER BY.)
Dernière modification le 24 juillet 2026