dbt : installer notre environnement local et découvrir les seeds

Dans le monde du Data Engineering, difficile de ne pas avoir déjà entendu le nom « dbt ». Pourtant, même s'il est aujourd'hui très largement utilisé, ce n'est pas forcément la norme sur tous les projets.

Une grosse annonce vient justement de tomber : dbt v2 vient de passer en GA. C'est donc un bon moment pour repartir de la base et découvrir dbt dans sa nouvelle génération.

Dans cette série, nous allons construire progressivement un petit projet local autour d’un dataset de jeux vidéo rétro. L’objectif n’est pas de couvrir toutes les possibilités de dbt, mais de comprendre ses concepts fondamentaux : charger quelques données, créer des modèles, déclarer leurs dépendances, tester leur qualité puis construire une première couche destinée à l’analyse.

Pour rester concentrés sur dbt, nous allons travailler entièrement en local avec DuckDB, qui est directement pris en charge par dbt v2.

Aussi, pour que tout le monde puisse suivre, on utilisera le dataset Retro Video Games publié par Nice Data. Il est tout petit, mais c'est parfait pour comprendre ce que fait dbt sans devoir chercher une erreur dans plusieurs millions de lignes.

Ce que nous allons construire

Nous partirons de deux fichiers CSV :

games.csv, qui contient les jeux ;

platforms.csv, qui contient les plateformes.

Dans ce premier article, on va demander à dbt de charger ces fichiers dans DuckDB avec la commande dbt seed.

Notre résultat sera volontairement simple :

CSV Small
├── games.csv      → table games
└── platforms.csv  → table platforms

Nous construirons les zones Silver et Gold dans les articles suivants.

Installer Python sous Windows

dbt est un outil que nous allons installer avec Python. Commençons par ouvrir PowerShell et vérifions si Python est déjà disponible :

py --version

Si une version de Python est affichée, nous pouvons continuer. Dans le cas contraire, il faudra installer Python. Vous pouvez choisir votre méthode favorite, mais l'une des plus faciles est d'utiliser le gestionnaire de paquets Windows avec une petite ligne de code :

winget install --exact --id Python.Python.3.13

Une fois l'installation terminée, il faudra fermer et réouvrir PowerShell. Cette étape permet au terminal de retrouver la nouvelle commande py.

Après votre installation, il faut s'assurer que Python est bien visible par votre environnement :

py --version

La version exacte pourra être un peu différente, mais Python doit maintenant répondre.

Créer le dossier du projet

Commençons par créer un dossier dbt-retro-games dans nos Documents. Vous pouvez simplement le faire depuis l'Explorateur Windows.

Ouvrez ensuite ce dossier dans PowerShell. Le plus simple sous Windows est de faire un clic droit dans le dossier puis Ouvrir dans le Terminal.

Ou vous pouvez travailler directement dans VS Code si vous préférez. Dans ce cas, il suffit d'ouvrir VS Code dans ce répertoire de la même façon. L'idée est que notre ligne de commande soit bien à la racine de ce répertoire que l'on vient de créer car toutes les commandes de cette série seront exécutées depuis ce dossier, sauf indication contraire.

Isoler dbt dans un environnement Python

Une bonne pratique en développement Python est de ne pas utiliser l'environnement Python par défaut de l'ordinateur. On crée en général un environnement virtuel qui permet d'isoler nos travaux et nos dépendances.

La bonne pratique est plutôt de créer un environnement virtuel nommé .venv :

py -m venv .venv
.venv\Scripts\Activate.ps1

Lorsque l'environnement est actif, (.venv) apparaît normalement au début de la ligne PowerShell ou un segment spécial si vous utilisez Oh-My-Posh comme moi :

Mettons ensuite pip à jour (avant qu'on nous le demande : un classique lorsqu'on travaille avec Python) et installons maintenant dbt v2. L’adaptateur DuckDB est directement pris en charge, nous n’avons donc rien de plus à installer :

python -m pip install --upgrade pip
python -m pip install dbt

Vérifions l'installation :

dbt --version

La sortie doit afficher dbt dans une version 2.0.0 ou plus récente.

Créer la structure du projet

Ouvrons maintenant le dossier dbt-retro-games dans notre éditeur. Nous allons créer nous-mêmes une structure minimale pour voir précisément de quoi dbt a besoin :

dbt-retro-games/
├── analyses/
├── macros/
├── models/
│   ├── gold/
│   └── silver/
├── seeds/
├── snapshots/
├── tests/
├── .gitignore
└── dbt_project.yml

Plusieurs dossiers resteront vides pour le moment. Ce n'est pas grave : ils préparent simplement la suite du projet.

Vous pouvez soit le faire à la main, soit avec la commande PowerShell suivante :

New-Item -ItemType Directory -Path analyses, macros, models, seeds, snapshots, tests -Force
New-Item -ItemType Directory -Path models\silver, models\gold -Force

Ça y est, nous pouvons maintenant commencer à définir notre projet ! Créons un fichier dbt_project.yml à la racine du projet avec ce contenu :

name: retro_games
version: "1.0.0"
config-version: 2

profile: retro_games

model-paths: ["models"]
seed-paths: ["seeds"]
test-paths: ["tests"]
analysis-paths: ["analyses"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]

target-path: "target"
clean-targets:
  - "target"
  - "dbt_packages"

models:
  retro_games:
    +materialized: table

Ce fichier décrit notre projet. Il indique notamment où se trouvent les modèles, les seeds et les tests. Pour commencer simplement, tous nos modèles seront créés sous forme de tables.

Si on utilise Git, ce qui est une bonne pratique, ajoutons également un fichier .gitignore pour que la base locale, l'environnement Python et la config VS Code ne fassent pas partie du code du projet.

.vscode
.venv/
target/
dbt_packages/
logs/
*.duckdb
*.duckdb.wal

Configurer la connexion à DuckDB

Le fichier dbt_project.yml décrit notre projet, mais il ne dit pas encore à dbt où exécuter nos requêtes. Cette connexion est définie dans un autre fichier nommé profiles.yml.

Par défaut, dbt cherche ce fichier dans le dossier .dbt de notre profil Windows.

Créons le dossier s'il n'existe pas :

New-Item -ItemType Directory -Path "$env:USERPROFILE\.dbt" -Force

Créons ensuite le fichier %USERPROFILE%\.dbt\profiles.yml (ou complétons-le s’il existe déjà) avec la configuration de notre connexion DuckDB :

retro_games:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: retro_games.duckdb
      schema: main
      threads: 4

Le nom retro_games correspond au profil décrit dans dbt_project.yml. Le paramètre path indique que DuckDB enregistrera la base dans un fichier retro_games.duckdb.

Revenons maintenant dans PowerShell et vérifions la configuration :

dbt debug

Si tout est correct, dbt termine par un message indiquant que les vérifications ont réussi.

Télécharger les deux fichiers Small

Nous allons maintenant récupérer les deux CSV directement depuis le repository public Nice Data. Vous pouvez soit le faire manuellement en téléchargant les fichiers et en les déposant dans le dossier seeds, soit via un script. Toujours depuis la racine du projet :

$baseUrl = "https://raw.githubusercontent.com/nicedatafr/datasets/retro-video-games-v1.0.0/retro-video-games/data/v1/small/relational/csv"

Invoke-WebRequest -Uri "$baseUrl/games.csv" -OutFile "seeds/games.csv"
Invoke-WebRequest -Uri "$baseUrl/platforms.csv" -OutFile "seeds/platforms.csv"

Notre dossier seeds contient maintenant les deux fichiers. Nous n'avons écrit aucun programme de téléchargement, aucun script spécifique. Ces quelques commandes font seulement partie de la préparation du projet.

Créer les tables avec dbt seed

Nous arrivons à notre première vraie commande dbt :

dbt seed

dbt lit les fichiers CSV placés dans seeds, déduit leurs colonnes et crée les tables games et platforms dans DuckDB.

Nous pouvons maintenant prévisualiser la table games directement depuis dbt :

dbt show --select games --limit 3 

Le fichier retro_games.duckdb est également apparu à la racine du projet. C'est notre base de données locale. Nous n'avons pas besoin de l'ouvrir manuellement : dbt s'occupera de créer et de transformer les tables à l'intérieur.

Un seed n'est pas un pipeline d'ingestion

Dans notre projet, les tables games et platforms vont jouer le rôle d'une petite zone Bronze. Elles représentent les données telles qu'elles arrivent avant nos transformations Silver et Gold.

Il faut cependant garder une nuance importante : dbt seed n'est pas destiné à remplacer un véritable processus d'ingestion de données volumineuses ou régulièrement mises à jour.

Dans un projet de production, un pipeline, un notebook ou un autre outil chargerait généralement les données sources dans de vraies tables. dbt commencerait ensuite son travail de transformation à partir de ces tables.

Les seeds sont surtout pratiques pour de petites données statiques, des tables de correspondance ou, comme ici, un projet d'apprentissage. Ils nous permettent de nous concentrer sur dbt sans devoir construire toute l'ingestion avant notre premier modèle. Ça nous permet de rentrer dans le vif du sujet sans prise de tête !

En résumé

Nous avons installé Python, créé un environnement virtuel, installé dbt v2 et configuré une base DuckDB locale. Puis dbt seed a transformé nos deux CSV Small en tables games et platforms.

Pour l'instant, nous n'avons encore transformé aucune donnée. Nous n'avons pas encore exploité dbt pour ce qu'il est. Nous avons seulement préparé notre point de départ, l'équivalent pédagogique d'une petite zone Bronze.

Dans le prochain article, nous allons pouvoir écrire nos premiers modèles SQL et construire les tables Silver directement depuis le point final de cet article.

Ressources officielles

• Installer dbt en local — les méthodes d’installation et la vérification de dbt v2.
• Ajouter des seeds à un projet dbt — leur fonctionnement, leur configuration et leurs limites.