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 :
_local, et non à la table distribuée servant de proxy.
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
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éfiniruse_lw_deletes=truedans 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 deincremental_predicatesnon 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)
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)
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.)