Le tutoriel dlt pratique — Loading Data Made Simple — guide à travers trois pipelines progressivement complexes en utilisant l’API GitHub : récupérer les dépôts d’une organisation, récupérer les commits de ces dépôts en utilisant des ressources dépendantes, puis ajouter le chargement incrémental pour ne récupérer que les nouveaux commits lors des exécutions suivantes.
Ce hub cartographie les concepts de ce tutoriel vers des notes de jardin individuelles, afin que vous puissiez approfondir n’importe quelle partie sans relire l’article complet.
La progression du tutoriel
Le tutoriel est structuré comme une échelle. Chaque étape ajoute un concept :
- Configuration de l’environnement et du projet → Premier pipeline exécuté localement contre DuckDB
- Configuration REST API Source → Comprendre les blocs client et ressources
- Ressources dépendantes → Utiliser la sortie d’un endpoint pour en piloter un autre
- Chargement incrémental → Ne récupérer que les nouvelles données lors des exécutions répétées
Suivre cet ordre est la bonne façon de le lire si vous débutez avec dlt. Si vous avez déjà un pipeline en cours et que vous avez besoin de comprendre une pièce spécifique, les notes ci-dessous sont autonomes.
Parcours de lecture
Configuration de l’environnement dlt — Les étapes avant tout code de pipeline : environnement virtuel Python, pip install "dlt[duckdb]", et dlt init rest_api duckdb. La commande dlt init crée le scaffold du projet incluant le répertoire de configuration .dlt/, un fichier pipeline de démarrage et un .gitignore préconfiguré qui exclut secrets.toml. Lisez ceci en premier si vous partez de zéro.
Concepts fondamentaux de dlt — Sources, ressources, pipelines et les trois write dispositions (replace, append, merge). C’est le vocabulaire nécessaire pour comprendre tout le reste. Le tutoriel suppose ce vocabulaire sans l’expliquer en ligne.
Configuration dlt REST API Source — Le dictionnaire de configuration déclaratif : le bloc client (URL de base, authentification, pagination), le bloc resources (chemins d’endpoint, noms), et ce que dlt fait automatiquement — pagination, inférence de schéma, normalisation JSON imbriqué en tables parent-enfant, création de tables de métadonnées. Couvre le pipeline de dépôts GitHub du tutoriel en détail.
Ressources dépendantes dans dlt — La syntaxe de template de chemin {resources.parent.field} qui permet à la sortie d’un endpoint de piloter l’URL d’un autre endpoint. Le deuxième pipeline du tutoriel — récupérer les commits pour chaque dépôt — utilise ce pattern. Cette note couvre pourquoi il existe, comment il se compose avec le chargement incrémental, et à quoi faire attention à grande échelle (les limites de débit se multiplient avec le nombre d’enregistrements parents).
Chargement incrémental dlt — Comment dlt suit l’état du pipeline entre les exécutions en utilisant le chargement basé sur curseur. La configuration déclarative pour REST API Source utilise "type": "incremental" avec un cursor_path et une initial_value. L’état est stocké dans _dlt_pipeline_state dans votre destination — visible et interrogeable. Cette note couvre également comment l’incrémentalité au niveau de l’extraction de dlt complète les modèles incrémentiels de dbt au niveau de la transformation en aval.
Gestion des secrets dlt — Le fichier .dlt/secrets.toml pour le développement local, les variables d’environnement pour le CI/CD, et la convention de nommage que dlt utilise (SOURCES__GITHUB__API_KEY correspond à sources.github.api_key). C’est mentionné tout au long du tutoriel mais expliqué en détail ici.
Le tutoriel en un diagramme
GitHub API │ ├── /orgs/PokeAPI/repos ← ressource pokeapi_repos │ (récupère tous les dépôts, paginé) │ └── /repos/PokeAPI/{name}/commits ← ressource pokeapi_repos_commits (dépend de pokeapi_repos) (incrémental : since=date_dernière_exécution) │ ▼DuckDB (local) → BigQuery (production) │ ├── github_data.pokeapi_repos ├── github_data.pokeapi_repos_commits └── github_data._dlt_* (tables de métadonnées)Ce que le tutoriel ne couvre pas
Le tutoriel est intentionnellement limité à REST API Source et DuckDB. Il ne couvre pas :
- RESTClient — L’alternative impérative pour l’authentification complexe ou la pagination personnalisée. Voir dlt RESTClient vs REST API Source pour la décision.
- BigQuery comme destination — Staging vs. streaming inserts, configuration du partitionnement, implications de coûts. Couvert dans le hub dlt chargement Python-native.
- Déploiement en production — Cloud Run, GitHub Actions, Airflow, Modal. Couvert dans Construire des pipelines API personnalisés avec dlt.
- Tests — Validation du schéma, tests d’état incrémental, patterns de test local DuckDB.
La valeur du tutoriel est de montrer un pipeline de bout en bout fonctionnel avec une configuration minimale. Les notes ci-dessus vous permettent d’approfondir n’importe quelle pièce individuelle.