> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Vous pouvez transformer et modéliser vos données dans ClickHouse à l’aide de dbt
# Intégration de dbt et ClickHouse
export const ClickHouseSupportedBadge = () => {
return
Compatible avec ClickHouse
;
};
## L’adaptateur dbt-clickhouse
**dbt** (data build tool) permet aux ingénieurs data spécialisés en analytics de transformer les données dans leurs entrepôts de données en écrivant simplement des instructions SELECT. dbt se charge de matérialiser ces instructions SELECT en objets de la base de données, sous forme de tables et de vues, assurant ainsi le T de [Extract Load and Transform (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform). Vous pouvez créer un modèle défini par une instruction SELECT.
Dans dbt, ces modèles peuvent être référencés entre eux et organisés en couches afin de construire des concepts de plus haut niveau. Le code SQL répétitif nécessaire pour relier les modèles est généré automatiquement. De plus, dbt identifie les dépendances entre les modèles et veille à ce qu’ils soient créés dans le bon ordre à l’aide d’un graphe orienté acyclique (DAG).
dbt est compatible avec ClickHouse grâce à un [adaptateur pris en charge par ClickHouse](https://github.com/ClickHouse/dbt-clickhouse).
## Pages connexes
| Page | Description |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Fonctionnalités et configurations](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | Description des fonctionnalités et des configurations générales disponibles |
| [Matérialisations](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/materializations) | Matérialisations disponibles et leurs configurations |
| [Vues matérialisées](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | Documentation spécifique sur la matérialisation materialized\_view |
| [Guides](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/guides) | Guides d'utilisation de dbt avec ClickHouse |
## Fonctionnalités prises en charge
Liste des fonctionnalités prises en charge :
* [x] Matérialisation de table
* [x] Matérialisation de vue
* [x] Matérialisation incrémentielle
* [x] Matérialisation incrémentielle Microbatch
* [x] Matérialisations vue matérialisée (utilise la forme `TO` de MATERIALIZED VIEW, expérimentale)
* [x] Seeds
* [x] Sources
* [x] Génération de la documentation
* [x] Tests
* [x] Snapshots
* [x] La plupart des macros dbt-utils (désormais incluses dans dbt-core)
* [x] Matérialisation éphémère
* [x] Matérialisation de table distribuée (expérimentale)
* [x] Matérialisation incrémentielle distribuée (expérimentale)
* [x] Contrats
* [x] Configurations de colonnes spécifiques à ClickHouse (codec, TTL...)
* [x] Paramètres de table spécifiques à ClickHouse (indexes, projections...)
Toutes les fonctionnalités jusqu’à dbt-core 1.10 sont prises en charge, y compris l’option `--sample`, et tous les avertissements de dépréciation ont été corrigés pour les versions ultérieures. Les **intégrations de catalogue** (par exemple, Iceberg) introduites dans dbt 1.10 ne sont pas encore prises en charge nativement par l’adaptateur, mais des solutions de contournement sont disponibles. Voir la [section Prise en charge du catalogue](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support) pour plus de détails.
Cet adaptateur n’est pas encore disponible dans [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview), mais nous prévoyons de le proposer prochainement. Veuillez contacter le support pour obtenir plus d’informations à ce sujet.
## Concepts dbt et matérialisations prises en charge
dbt introduit le concept de modèle. Celui-ci est défini comme une instruction SQL, pouvant éventuellement joindre de nombreuses tables. Un modèle peut être « matérialisé » de plusieurs façons. Une matérialisation représente une stratégie de construction pour la requête select du modèle. Le code sous-jacent à une matérialisation est du SQL standard qui encapsule votre requête SELECT dans une instruction afin de créer une nouvelle relation ou de mettre à jour une relation existante.
dbt propose 5 types de matérialisation. Tous sont pris en charge par `dbt-clickhouse` :
* **view** (par défaut) : Le modèle est créé sous forme de vue dans la base de données. Dans ClickHouse, cela correspond à une [vue](/docs/fr/reference/statements/create/view).
* **table** : Le modèle est créé sous forme de table dans la base de données. Dans ClickHouse, cela correspond à une [table](/docs/fr/reference/statements/create/table).
* **ephemeral** : Le modèle n'est pas créé directement dans la base de données, mais est intégré aux modèles dépendants sous forme de CTE (Common Table Expressions).
* **incrémentiel** : Le modèle est d'abord matérialisé sous forme de table et, lors des exécutions suivantes, dbt insère de nouvelles lignes et met à jour les lignes modifiées dans la table.
* **materialized view** : Le modèle est créé sous forme de vue matérialisée dans la base de données. Dans ClickHouse, cela correspond à une [vue matérialisée](/docs/fr/reference/statements/create/view#materialized-view).
Une syntaxe et des clauses supplémentaires définissent la manière dont ces modèles doivent être mis à jour si leurs données sous-jacentes changent. dbt recommande généralement de commencer par la matérialisation view jusqu'à ce que les performances deviennent un enjeu. La matérialisation table améliore les performances à l'exécution des requêtes en enregistrant les résultats de la requête du modèle dans une table, au prix d'un stockage plus important. L'approche incrémentiel va plus loin en permettant de répercuter dans la table cible les mises à jour ultérieures des données sous-jacentes.
L'[adaptateur actuel](https://github.com/silentsokolov/dbt-clickhouse) pour ClickHouse prend également en charge les matérialisations **dictionary**, **table distribuée** et **distributed incrémentiel**. L'adaptateur prend également en charge les [snapshots](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy) et les [seeds](https://docs.getdbt.com/docs/building-a-dbt-project/seeds) de dbt.
Voici les [fonctionnalités expérimentales](/docs/fr/reference/settings/beta-and-experimental-features) de `dbt-clickhouse` :
| Type | Prise en charge ? | Détails |
| ---------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| vue matérialisée materialization | Oui. La création avec cible explicite est en Beta | Crée une [vue matérialisée](/docs/fr/reference/statements/create/view#materialized-view). |
| table distribuée materialization | Oui, Experimental | Crée une [table distribuée](/docs/fr/reference/engines/table-engines/special/distributed). |
| Distributed incrémentiel materialization | Oui, Experimental | Modèle incrémentiel reposant sur le même principe qu'une table distribuée. Notez que toutes les stratégies ne sont pas prises en charge ; consultez [la section correspondante de la documentation](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental) pour plus d'informations. |
| Dictionary materialization | Oui, Experimental | Crée un [dictionnaire](/docs/fr/reference/engines/table-engines/special/dictionary). |
## Configuration de dbt et de l’adaptateur ClickHouse
### Installer dbt-core et dbt-clickhouse
dbt propose plusieurs options pour installer l’interface en ligne de commande (CLI), détaillées [ici](https://docs.getdbt.com/dbt-cli/install/overview). Nous recommandons d’utiliser `pip` pour installer dbt et dbt-clickhouse.
```sh theme={null}
pip install dbt-core dbt-clickhouse
```
### Fournissez à dbt les paramètres de connexion de notre instance ClickHouse.
Configurez le profil `clickhouse-service` dans le fichier `~/.dbt/profiles.yml` et renseignez les propriétés `schema`, `host`, `port`, `user` et `password`. La liste complète des options de configuration de la connexion est disponible sur la page [Fonctionnalités et configurations](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) :
```yaml theme={null}
clickhouse-service:
target: dev
outputs:
dev:
type: clickhouse
schema: [ default ] # ClickHouse database for dbt models
# Optional
host: [ localhost ]
port: [ 8123 ] # Defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings
user: [ default ] # User for all database operations
password: [ ] # Password for the user
secure: True # Use TLS (native protocol) or HTTPS (http protocol)
```
### Créer un projet dbt
Vous pouvez désormais utiliser ce profil dans l’un de vos projets existants ou en créer un nouveau à l’aide de :
```sh theme={null}
dbt init project_name
```
Dans le répertoire `project_name`, mettez à jour votre fichier `dbt_project.yml` afin d’y indiquer un nom de profil pour vous connecter au serveur ClickHouse.
```yaml theme={null}
profile: 'clickhouse-service'
```
### Tester la connexion
Exécutez `dbt debug` avec l’outil CLI afin de vérifier si dbt parvient à se connecter à ClickHouse. Vérifiez que la réponse contient `Connection test: [OK connection ok]`, ce qui indique que la connexion a réussi.
Consultez la [page des guides](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/guides) pour en savoir plus sur l’utilisation de dbt avec ClickHouse.
### Tester et déployer vos modèles (CI/CD)
Il existe de nombreuses façons de tester et de déployer votre projet dbt. dbt propose quelques recommandations sur les [bonnes pratiques de workflow](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) et les [jobs CI](https://docs.getdbt.com/docs/deploy/ci-jobs). Nous allons passer en revue plusieurs stratégies, mais gardez à l'esprit qu'elles devront შესაძლოა être adaptées en profondeur à votre cas d'usage.
#### CI/CD avec des tests de données simples et des tests unitaires
Pour démarrer simplement votre pipeline de CI, vous pouvez exécuter un cluster ClickHouse dans votre job, puis y exécuter vos modèles. Vous pouvez insérer des données de démonstration dans ce cluster avant d’exécuter vos modèles. Vous pouvez simplement utiliser un [seed](https://docs.getdbt.com/reference/commands/seed) pour alimenter l’environnement de préproduction avec un sous-ensemble de vos données de production.
Une fois les données insérées, vous pouvez alors exécuter vos [tests de données](https://docs.getdbt.com/docs/build/data-tests) et vos [tests unitaires](https://docs.getdbt.com/docs/build/unit-tests).
Votre étape de CD peut être aussi simple que d’exécuter `dbt build` sur votre cluster ClickHouse de production.
#### Étape CI/CD plus complète : utiliser des données récentes, ne tester que les modèles concernés
Une stratégie courante consiste à utiliser des jobs [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci), dans lesquels seuls les modèles modifiés (ainsi que leurs dépendances en amont et en aval) sont redéployés. Cette approche s'appuie sur les artefacts de vos exécutions en production (c.-à-d. le [manifest dbt](https://docs.getdbt.com/reference/artifacts/manifest-json)) pour réduire le temps d'exécution de votre projet et garantir l'absence de dérive de schéma entre les environnements.
Pour garder vos environnements de développement synchronisés et éviter d'exécuter vos modèles sur des déploiements obsolètes, vous pouvez utiliser [clone](https://docs.getdbt.com/reference/commands/clone) ou même [defer](https://docs.getdbt.com/reference/node-selection/defer).
Nous recommandons d'utiliser un cluster ou un service ClickHouse dédié pour l'environnement de test (c.-à-d. un environnement de préproduction) afin d'éviter d'affecter le fonctionnement de votre environnement de production. Pour que l'environnement de test soit représentatif, il est important d'utiliser un sous-ensemble de vos données de production et d'exécuter dbt d'une manière qui empêche toute dérive de schéma entre les environnements.
* Si vous n'avez pas besoin de données fraîches pour vos tests, vous pouvez restaurer une sauvegarde de vos données de production dans l'environnement de préproduction.
* Si vous avez besoin de données fraîches pour vos tests, vous pouvez utiliser une combinaison de la [table function `remoteSecure()`](/docs/fr/reference/functions/table-functions/remote) et de vues matérialisées actualisables pour insérer des données à la fréquence souhaitée. Une autre option consiste à utiliser le stockage objet comme intermédiaire, à y écrire périodiquement des données depuis votre service de production, puis à les importer dans l'environnement de préproduction à l'aide des table functions de stockage objet ou de ClickPipes (pour l'ingestion continue).
L'utilisation d'un environnement dédié aux tests CI vous permet également d'effectuer des tests manuels sans affecter votre environnement de production. Par exemple, vous pouvez vouloir connecter un outil BI à cet environnement pour vos tests.
Pour le déploiement (c.-à-d. l'étape CD), nous recommandons d'utiliser les artefacts de vos déploiements en production pour ne mettre à jour que les modèles qui ont changé. Cela nécessite de configurer le stockage objet (par exemple, S3) comme stockage intermédiaire pour vos artefacts dbt. Une fois cela en place, vous pouvez exécuter une commande telle que `dbt build --select state:modified+ --state path/to/last/deploy/state.json` afin de reconstruire de manière sélective le nombre minimal de modèles nécessaires en fonction de ce qui a changé depuis la dernière exécution en production.
## Dépannage des problèmes courants
### Connexions
Si vous rencontrez des problèmes de connexion à ClickHouse depuis dbt, assurez-vous que les critères suivants sont remplis :
* Le moteur doit faire partie des [moteurs pris en charge](/docs/fr/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines).
* Vous devez disposer des permissions nécessaires pour accéder à la base de données.
* Si vous n’utilisez pas le moteur de table par défaut de la base de données, vous devez spécifier un moteur de table dans la configuration de votre modèle.
### Comprendre les opérations de longue durée
Certaines opérations peuvent prendre plus de temps que prévu en raison de requêtes ClickHouse spécifiques. Pour mieux identifier les requêtes qui prennent le plus de temps, augmentez le [niveau de journalisation](https://docs.getdbt.com/reference/global-configs/logs#log-level) à `debug` — cela affichera le temps d’exécution de chaque requête. Par exemple, vous pouvez le faire en ajoutant `--log-level debug` aux commandes dbt.
## Limitations
L’adaptateur ClickHouse actuel pour dbt présente plusieurs limitations dont vous devez être conscient :
* Le plugin utilise une syntaxe qui nécessite ClickHouse version 25.3 ou ultérieure. Nous ne testons pas les versions plus anciennes de ClickHouse. Nous ne testons pas non plus actuellement les tables Replicated.
* Différentes exécutions de `dbt-adapter` peuvent entrer en conflit si elles sont lancées en même temps, car elles peuvent utiliser en interne les mêmes noms de table pour les mêmes opérations. Pour plus d’informations, consultez l’issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420).
* L’adaptateur matérialise actuellement les modèles sous forme de tables à l’aide d’un [INSERT INTO SELECT](/docs/fr/reference/statements/insert-into#inserting-the-results-of-select). Cela entraîne effectivement une duplication des données si l’exécution est relancée. Des jeux de données très volumineux (PB) peuvent provoquer des temps d’exécution extrêmement longs, au point de rendre certains modèles peu viables. Pour améliorer les performances, utilisez des vues matérialisées ClickHouse en implémentant la vue comme `materialized: materialization_view`. En outre, efforcez-vous de réduire au minimum le nombre de lignes renvoyées par chaque requête en utilisant `GROUP BY` lorsque c’est possible. Préférez les modèles qui résument les données à ceux qui se contentent de les transformer tout en conservant le même nombre de lignes que la source.
* Pour utiliser des tables distribuées pour représenter un modèle, vous devez créer manuellement les tables replicated sous-jacentes sur chaque nœud. La table Distributed peut ensuite être créée au-dessus de celles-ci. L’adaptateur ne gère pas la création du cluster.
* Lorsque dbt crée une relation (table/view) dans une base de données, il la crée généralement comme suit : `{{ database }}.{{ schema }}.{{ table/view id }}`. ClickHouse n’a pas de notion de schéma. L’adaptateur utilise donc `{{schema}}.{{ table/view id }}`, où `schema` correspond à la base de données ClickHouse.
* Les modèles/CTE éphémères ne fonctionnent pas s’ils sont placés avant le `INSERT INTO` dans une instruction insert ClickHouse, voir [https://github.com/ClickHouse/ClickHouse/issues/30323](https://github.com/ClickHouse/ClickHouse/issues/30323). Cela ne devrait pas affecter la plupart des modèles, mais il faut faire attention à l’emplacement d’un modèle éphémère dans les définitions de modèles et les autres instructions SQL. {/* TODO review this limitation, looks like the issue was already closed and the fix was introduced in 24.10 */}
## Fivetran
Le connecteur `dbt-clickhouse` peut également être utilisé dans les [transformations Fivetran](https://fivetran.com/docs/transformations/dbt), ce qui permet une intégration fluide et des capacités de transformation directement au sein de la plateforme Fivetran à l'aide de `dbt`.