Configurations générales des matérialisations
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
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
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
dbt_project.yml) :
models/<model_name>.sql) :
Matérialisation : table
dbt_project.yml) :
models/<model_name>.sql) :
Index de saut de données
table à l’aide de la configuration indexes :
Projections
table et distributed_table à l’aide de la configuration projections. Chaque entrée de projection nécessite une clé query ou une clé index (mais pas les deux).
Remarque : Pour les tables distribuées, la projection s’applique aux tables _local, et non à la table distribuée servant de proxy.
Remarque : Spécifier à la fois query et index dans la même entrée de projection génère une erreur lors de la compilation.
Projections de requêtes
query pour définir une requête de projection complète :
Projections d’index
index comme raccourci syntaxique pour des projections d’index légères utilisant la colonne virtuelle _part_offset. Indiquez un nom de colonne ou une liste de colonnes selon laquelle effectuer le tri :
Matérialisation : incrémentielle
dbt_project.yml :
models/<model_name>.sql :
Configurations
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)
La stratégie Delete+Insert
delete+insert utilise les suppressions légères pour supprimer les lignes concernées, puis insérer les nouvelles. Comme elle ne copie pas l’intégralité de la table, elle est nettement plus performante que la stratégie « legacy ». Définir use_lw_deletes: true dans votre profil fait de delete+insert la stratégie incrémentielle par défaut.
Cette stratégie comporte d’importantes mises en garde :
- Elle agit directement sur la table concernée sans créer de tables intermédiaires ou temporaires. Par conséquent, en cas de problème lors de l’opération, les données du modèle incrémentiel risquent de se retrouver dans un état non valide.
- Elle nécessite le paramètre ClickHouse
allow_nondeterministic_mutations. L’adaptateur l’active automatiquement pour ses propres sessions lorsque cela est possible. Lorsqu’il ne peut pas être activé (par exemple, parce qu’il est en lecture seule pour votre utilisateur dbt), le comportement dépend de la manière dont la stratégie a été choisie : les modèles s’appuyant sur la stratégie par défaut basculent silencieusement vers la stratégie legacy, les modèles qui définissent explicitementdelete+insertoumicrobatchéchouent à l’exécution, etuse_lw_deletes: truedans le profil échoue lors de la connexion. - Dans de très rares cas, l’utilisation de
incremental_predicatesnon déterministes peut entraîner une condition de concurrence pour les éléments mis à jour ou supprimés. Pour garantir des résultats cohérents, les prédicats incrémentiels ne doivent inclure que des sous-requêtes portant sur des données qui ne seront pas modifiées lors de la matérialisation incrémentielle.
La stratégie Microbatch (nécessite dbt-core >= 1.9)
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 :
- Retraiter les lots en échec.
- Détecter automatiquement l’exécution parallèle des lots.
- Éliminer le besoin d’une logique conditionnelle complexe pour le chargement rétroactif.
Configurations disponibles pour Microbatch
La stratégie Append
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 :
- 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>. - Insère uniquement les nouveaux enregistrements (produits par
SELECT) dans la table de staging. - Remplace uniquement les nouvelles partitions (présentes dans la table de staging) dans la table cible.
- 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.
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
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)
dbt run, le dictionnaire est remplacé par la définition actuelle du modèle à l’aide de CREATE OR REPLACE DICTIONARY.
Configurations
Exemple avec une source ClickHouse
Exemple avec une source HTTP
source_type='http' (ou l’option table), le SQL du modèle n’est pas utilisé comme source, mais dbt exige tout de même un corps : utilisez select 1 comme espace réservé.
Matérialisation : distributed_table (expérimental)
- Création d’une vue temporaire avec une requête SQL afin d’obtenir la bonne structure
- Création de tables locales vides à partir de la vue
- Création d’une table distribuée à partir des tables locales.
- Les données sont insérées dans la table distribuée, puis réparties entre les shards sans duplication.
- Les requêtes dbt-clickhouse incluent désormais automatiquement le paramètre
insert_distributed_sync = 1afin 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
matérialisation : distributed_incremental (expérimental)
- La stratégie Append se contente d’insérer les données dans la table distribuée.
- La stratégie Delete+Insert crée une table temporaire distribuée pour travailler avec l’ensemble des données sur chaque shard.
- La stratégie Default (Legacy) crée des tables temporaires et intermédiaires distribuées pour la même raison.
Exemple de modèle distributed incremental
Migrations générées
Snapshot
snapshots/<model_name>.sql:
Contrats et 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.)