Tutoriel : créer, exécuter et tester des modèles dbt localement

Ce tutoriel vous guide tout au long de la création, de l’exécution et du test de modèles dbt localement. Vous pouvez également exécuter des projets dbt en tant que tâches de travail Azure Databricks. Pour plus d’informations, consultez Utiliser les transformations dbt dans les travaux Lakeflow.

Conditions préalables

Pour suivre ce tutoriel, vous devez d’abord connecter votre espace de travail Azure Databricks à dbt Core. Pour plus d’informations, consultez Se connecter à dbt Core.

Étape 1 : créer et exécuter des modèles

Dans cette étape, vous allez utiliser votre éditeur de texte favori pour créer des modèles, à savoir des instructions select qui créent soit une nouvelle vue (par défaut), soit une nouvelle table dans une base de données, en fonction des données existantes de cette même base de données. Cette procédure crée un modèle basé sur l’exemple de table diamonds des Exemples de jeux de données.

Conseil

Si votre espace de travail est activé pour Unity Catalog avec un entrepôt SQL serverless, Databricks recommande de matérialiser des modèles de production qui doivent rester à jour sous forme de vues matérialisées ou de tables de streaming, plutôt que sous forme de tables ou de vues. Ces matérialisations se rafraîchissent de manière incrémentielle au lieu de recalculer le résultat complet à chaque exécution. Voir l’étape 4 : Gardez les modèles frais avec des vues matérialisées et des tableaux en streaming.

Utilisez le code suivant pour créer cette table.

DROP TABLE IF EXISTS diamonds;

CREATE TABLE diamonds USING CSV OPTIONS (path "/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", header "true")

Dans le répertoire du models projet, créez un fichier nommé diamonds_four_cs.sql avec l’instruction SQL suivante. Cette instruction sélectionne uniquement les détails relatifs aux carats, à la taille, à la couleur et à la clarté de chaque diamant dans la table diamonds. Le bloc config indique à dbt de créer une table dans la base de données en fonction de cette instruction.
```
{{ config(
  materialized='table',
  file_format='delta'
) }}
```
```
select carat, cut, color, clarity
from diamonds
```
Conseil

Pour obtenir des options config supplémentaires telles que l’utilisation du format de fichier Delta et de la stratégie incrémentielle merge, consultez Configurations Databricks dans la documentation dbt.
Dans le répertoire du models projet, créez un deuxième fichier nommé diamonds_list_colors.sql avec l’instruction SQL suivante. Cette instruction sélectionne des valeurs uniques dans la colonne colors de la table diamonds_four_cs, en triant les résultats par ordre alphabétique du premier au dernier. Étant donné qu’il n’y a aucun bloc config, ce modèle demande à dbt de créer une vue dans la base de données en fonction de cette instruction.
```
select distinct color
from {{ ref('diamonds_four_cs') }}
sort by color asc
```
Dans le répertoire du models projet, créez un troisième fichier nommé diamonds_prices.sql avec l’instruction SQL suivante. Cette instruction calcule la moyenne des prix des diamants par couleur, en triant les résultats par prix moyen, du plus élevé au plus bas. Ce modèle demande à dbt de créer une vue dans la base de données en fonction de cette instruction.
```
select color, avg(price) as price
from diamonds
group by color
order by price desc
```

Une fois l’environnement virtuel activé, exécutez la commande dbt run avec les chemins d’accès aux trois fichiers précédents. Dans la base de données default (spécifiée dans le fichier profiles.yml), dbt crée une table nommée diamonds_four_cs et deux affichages nommés diamonds_list_colors et diamonds_prices. dbt obtient ces noms d’affichages et de table à partir des noms de fichiers .sql associés.

dbt run --model models/diamonds_four_cs.sql models/diamonds_list_colors.sql models/diamonds_prices.sql

...
... | 1 of 3 START table model default.diamonds_four_cs.................... [RUN]
... | 1 of 3 OK created table model default.diamonds_four_cs............... [OK ...]
... | 2 of 3 START view model default.diamonds_list_colors................. [RUN]
... | 2 of 3 OK created view model default.diamonds_list_colors............ [OK ...]
... | 3 of 3 START view model default.diamonds_prices...................... [RUN]
... | 3 of 3 OK created view model default.diamonds_prices................. [OK ...]
... |
... | Finished running 1 table model, 2 view models ...

Completed successfully

Done. PASS=3 WARN=0 ERROR=0 SKIP=0 TOTAL=3

Exécutez le code SQL suivant pour répertorier les informations relatives aux nouvelles vues et sélectionner toutes les lignes de la table et des vues.

Si vous vous connectez à un cluster, vous pouvez exécuter ce code SQL à partir d’un notebook connecté au cluster, en spécifiant SQL comme langage par défaut pour le notebook. Si vous vous connectez à un entrepôt SQL, vous pouvez exécuter ce code SQL à partir d’une requête.

SHOW views IN default;

+-----------+----------------------+-------------+
| namespace | viewName             | isTemporary |
+===========+======================+=============+
| default   | diamonds_list_colors | false       |
+-----------+----------------------+-------------+
| default   | diamonds_prices      | false       |
+-----------+----------------------+-------------+

SELECT * FROM diamonds_four_cs;

+-------+---------+-------+---------+
| carat | cut     | color | clarity |
+=======+=========+=======+=========+
| 0.23  | Ideal   | E     | SI2     |
+-------+---------+-------+---------+
| 0.21  | Premium | E     | SI1     |
+-------+---------+-------+---------+
...

SELECT * FROM diamonds_list_colors;

+-------+
| color |
+=======+
| D     |
+-------+
| E     |
+-------+
...

SELECT * FROM diamonds_prices;

+-------+---------+
| color | price   |
+=======+=========+
| J     | 5323.82 |
+-------+---------+
| I     | 5091.87 |
+-------+---------+
...

Étape 2 : créer et exécuter des modèles plus complexes

Dans cette étape, vous créez des modèles plus complexes pour un ensemble de tables de données associées. Ces tables de données contiennent des informations sur une ligue sportive fictive composée de trois équipes jouant une saison de six matchs. Cette procédure crée les tables de données, crée les modèles et exécute les modèles.

Exécutez le code SQL suivant pour créer les tables de données nécessaires.

Les tables et les vues de cette étape commencent par zzz_ afin de les identifier comme faisant partie de cet exemple. Vous n’avez pas besoin de suivre ce modèle pour vos propres tables et vues.

DROP TABLE IF EXISTS zzz_game_opponents;
DROP TABLE IF EXISTS zzz_game_scores;
DROP TABLE IF EXISTS zzz_games;
DROP TABLE IF EXISTS zzz_teams;

CREATE TABLE zzz_game_opponents (
game_id INT,
home_team_id INT,
visitor_team_id INT
) USING DELTA;

INSERT INTO zzz_game_opponents VALUES (1, 1, 2);
INSERT INTO zzz_game_opponents VALUES (2, 1, 3);
INSERT INTO zzz_game_opponents VALUES (3, 2, 1);
INSERT INTO zzz_game_opponents VALUES (4, 2, 3);
INSERT INTO zzz_game_opponents VALUES (5, 3, 1);
INSERT INTO zzz_game_opponents VALUES (6, 3, 2);

-- Result:
-- +---------+--------------+-----------------+
-- | game_id | home_team_id | visitor_team_id |
-- +=========+==============+=================+
-- | 1       | 1            | 2               |
-- +---------+--------------+-----------------+
-- | 2       | 1            | 3               |
-- +---------+--------------+-----------------+
-- | 3       | 2            | 1               |
-- +---------+--------------+-----------------+
-- | 4       | 2            | 3               |
-- +---------+--------------+-----------------+
-- | 5       | 3            | 1               |
-- +---------+--------------+-----------------+
-- | 6       | 3            | 2               |
-- +---------+--------------+-----------------+

CREATE TABLE zzz_game_scores (
game_id INT,
home_team_score INT,
visitor_team_score INT
) USING DELTA;

INSERT INTO zzz_game_scores VALUES (1, 4, 2);
INSERT INTO zzz_game_scores VALUES (2, 0, 1);
INSERT INTO zzz_game_scores VALUES (3, 1, 2);
INSERT INTO zzz_game_scores VALUES (4, 3, 2);
INSERT INTO zzz_game_scores VALUES (5, 3, 0);
INSERT INTO zzz_game_scores VALUES (6, 3, 1);

-- Result:
-- +---------+-----------------+--------------------+
-- | game_id | home_team_score | visitor_team_score |
-- +=========+=================+====================+
-- | 1       | 4               | 2                  |
-- +---------+-----------------+--------------------+
-- | 2       | 0               | 1                  |
-- +---------+-----------------+--------------------+
-- | 3       | 1               | 2                  |
-- +---------+-----------------+--------------------+
-- | 4       | 3               | 2                  |
-- +---------+-----------------+--------------------+
-- | 5       | 3               | 0                  |
-- +---------+-----------------+--------------------+
-- | 6       | 3               | 1                  |
-- +---------+-----------------+--------------------+

CREATE TABLE zzz_games (
game_id INT,
game_date DATE
) USING DELTA;

INSERT INTO zzz_games VALUES (1, '2020-12-12');
INSERT INTO zzz_games VALUES (2, '2021-01-09');
INSERT INTO zzz_games VALUES (3, '2020-12-19');
INSERT INTO zzz_games VALUES (4, '2021-01-16');
INSERT INTO zzz_games VALUES (5, '2021-01-23');
INSERT INTO zzz_games VALUES (6, '2021-02-06');

-- Result:
-- +---------+------------+
-- | game_id | game_date  |
-- +=========+============+
-- | 1       | 2020-12-12 |
-- +---------+------------+
-- | 2       | 2021-01-09 |
-- +---------+------------+
-- | 3       | 2020-12-19 |
-- +---------+------------+
-- | 4       | 2021-01-16 |
-- +---------+------------+
-- | 5       | 2021-01-23 |
-- +---------+------------+
-- | 6       | 2021-02-06 |
-- +---------+------------+

CREATE TABLE zzz_teams (
team_id INT,
team_city VARCHAR(15)
) USING DELTA;

INSERT INTO zzz_teams VALUES (1, "San Francisco");
INSERT INTO zzz_teams VALUES (2, "Seattle");
INSERT INTO zzz_teams VALUES (3, "Amsterdam");

-- Result:
-- +---------+---------------+
-- | team_id | team_city     |
-- +=========+===============+
-- | 1       | San Francisco |
-- +---------+---------------+
-- | 2       | Seattle       |
-- +---------+---------------+
-- | 3       | Amsterdam     |
-- +---------+---------------+

Dans le répertoire du models projet, créez un fichier nommé zzz_game_details.sql avec l’instruction SQL suivante. Cette instruction crée une table qui fournit les détails de chaque match, tels que les noms des équipes et les scores. Le bloc config indique à dbt de créer une table dans la base de données en fonction de cette instruction.

-- Create a table that provides full details for each game, including
-- the game ID, the home and visiting teams' city names and scores,
-- the game winner's city name, and the game date.

{{ config(
  materialized='table',
  file_format='delta'
) }}

-- Step 4 of 4: Replace the visitor team IDs with their city names.
select
  game_id,
  home,
  t.team_city as visitor,
  home_score,
  visitor_score,
  -- Step 3 of 4: Display the city name for each game's winner.
  case
    when
      home_score > visitor_score
        then
          home
    when
      visitor_score > home_score
        then
          t.team_city
  end as winner,
  game_date as date
from (
  -- Step 2 of 4: Replace the home team IDs with their actual city names.
  select
    game_id,
    t.team_city as home,
    home_score,
    visitor_team_id,
    visitor_score,
    game_date
  from (
    -- Step 1 of 4: Combine data from various tables (for example, game and team IDs, scores, dates).
    select
      g.game_id,
      go.home_team_id,
      gs.home_team_score as home_score,
      go.visitor_team_id,
      gs.visitor_team_score as visitor_score,
      g.game_date
    from
      zzz_games as g,
      zzz_game_opponents as go,
      zzz_game_scores as gs
    where
      g.game_id = go.game_id and
      g.game_id = gs.game_id
  ) as all_ids,
    zzz_teams as t
  where
    all_ids.home_team_id = t.team_id
) as visitor_ids,
  zzz_teams as t
where
  visitor_ids.visitor_team_id = t.team_id
order by game_date desc

Dans le répertoire du models projet, créez un fichier nommé zzz_win_loss_records.sql avec l’instruction SQL suivante. Cette instruction crée une vue qui répertorie les bilans des victoires et des défaites des équipes pour la saison.

-- Create a view that summarizes the season's win and loss records by team.

-- Step 2 of 2: Calculate the number of wins and losses for each team.
select
  winner as team,
  count(winner) as wins,
  -- Each team played in 4 games.
  (4 - count(winner)) as losses
from (
  -- Step 1 of 2: Determine the winner and loser for each game.
  select
    game_id,
    winner,
    case
      when
        home = winner
          then
            visitor
      else
        home
    end as loser
  from {{ ref('zzz_game_details') }}
)
group by winner
order by wins desc

Une fois l’environnement virtuel activé, exécutez la commande dbt run avec les chemins d’accès aux deux fichiers précédents. Dans la base de données default (spécifiée dans le fichier profiles.yml), dbt crée une table nommée zzz_game_details et un affichage nommé zzz_win_loss_records. dbt obtient ces noms d’affichages et de table à partir des noms de fichiers .sql associés.

dbt run --model models/zzz_game_details.sql models/zzz_win_loss_records.sql

...
... | 1 of 2 START table model default.zzz_game_details.................... [RUN]
... | 1 of 2 OK created table model default.zzz_game_details............... [OK ...]
... | 2 of 2 START view model default.zzz_win_loss_records................. [RUN]
... | 2 of 2 OK created view model default.zzz_win_loss_records............ [OK ...]
... |
... | Finished running 1 table model, 1 view model ...

Completed successfully

Done. PASS=2 WARN=0 ERROR=0 SKIP=0 TOTAL=2

Exécutez le code SQL suivant pour répertorier les informations relatives à la nouvelle vue et sélectionner toutes les lignes de la table et de la vue.

SHOW VIEWS FROM default LIKE 'zzz_win_loss_records';

+-----------+----------------------+-------------+
| namespace | viewName             | isTemporary |
+===========+======================+=============+
| default   | zzz_win_loss_records | false       |
+-----------+----------------------+-------------+

SELECT * FROM zzz_game_details;

+---------+---------------+---------------+------------+---------------+---------------+------------+
| game_id | home          | visitor       | home_score | visitor_score | winner        | date       |
+=========+===============+===============+============+===============+===============+============+
| 1       | San Francisco | Seattle       | 4          | 2             | San Francisco | 2020-12-12 |
+---------+---------------+---------------+------------+---------------+---------------+------------+
| 2       | San Francisco | Amsterdam     | 0          | 1             | Amsterdam     | 2021-01-09 |
+---------+---------------+---------------+------------+---------------+---------------+------------+
| 3       | Seattle       | San Francisco | 1          | 2             | San Francisco | 2020-12-19 |
+---------+---------------+---------------+------------+---------------+---------------+------------+
| 4       | Seattle       | Amsterdam     | 3          | 2             | Seattle       | 2021-01-16 |
+---------+---------------+---------------+------------+---------------+---------------+------------+
| 5       | Amsterdam     | San Francisco | 3          | 0             | Amsterdam     | 2021-01-23 |
+---------+---------------+---------------+------------+---------------+---------------+------------+
| 6       | Amsterdam     | Seattle       | 3          | 1             | Amsterdam     | 2021-02-06 |
+---------+---------------+---------------+------------+---------------+---------------+------------+

SELECT * FROM zzz_win_loss_records;

+---------------+------+--------+
| team          | wins | losses |
+===============+======+========+
| Amsterdam     | 3    | 1      |
+---------------+------+--------+
| San Francisco | 2    | 2      |
+---------------+------+--------+
| Seattle       | 1    | 3      |
+---------------+------+--------+

Étape 3 : créer et exécuter des tests

Dans cette étape, vous créez des tests, qui sont des instructions d’assertion que vous faites sur vos modèles. Lorsque vous exécutez ces tests, dbt vous indique si chaque test de votre projet réussit ou échoue.

Il existe deux types de tests. Les tests de schéma, appliqués dans YAML, renvoient le nombre d’enregistrements qui ne réussissent pas l’instruction d’assertion. Lorsque ce nombre est égal à zéro, tous les enregistrements réussissent. Par conséquent, les tests réussissent. Les tests de données sont des requêtes spécifiques qui doivent renvoyer zéro enregistrement pour réussir.

Dans le répertoire du models projet, créez un fichier nommé schema.yml avec le contenu suivant. Ce fichier comprend des tests de schéma qui déterminent si les colonnes spécifiées ont des valeurs uniques, n’ont pas de valeurs Null, ont uniquement les valeurs spécifiées ou une combinaison.

version: 2

models:
  - name: zzz_game_details
    columns:
      - name: game_id
        tests:
          - unique
          - not_null
      - name: home
        tests:
          - not_null
          - accepted_values:
              values: ['Amsterdam', 'San Francisco', 'Seattle']
      - name: visitor
        tests:
          - not_null
          - accepted_values:
              values: ['Amsterdam', 'San Francisco', 'Seattle']
      - name: home_score
        tests:
          - not_null
      - name: visitor_score
        tests:
          - not_null
      - name: winner
        tests:
          - not_null
          - accepted_values:
              values: ['Amsterdam', 'San Francisco', 'Seattle']
      - name: date
        tests:
          - not_null
  - name: zzz_win_loss_records
    columns:
      - name: team
        tests:
          - unique
          - not_null
          - relationships:
              to: ref('zzz_game_details')
              field: home
      - name: wins
        tests:
          - not_null
      - name: losses
        tests:
          - not_null

Dans le répertoire du tests projet, créez un fichier nommé zzz_game_details_check_dates.sql avec l’instruction SQL suivante. Ce fichier comprend un test de données permettant de déterminer si des matchs ont eu lieu en dehors de la saison normale.
```
-- This season's games happened between 2020-12-12 and 2021-02-06.
-- For this test to pass, this query must return no results.

select date
from {{ ref('zzz_game_details') }}
where date < '2020-12-12'
or date > '2021-02-06'
```

Dans le répertoire du tests projet, créez un fichier nommé zzz_game_details_check_scores.sql avec l’instruction SQL suivante. Ce fichier comprend un test de données permettant de déterminer si les scores sont négatifs ou si les matchs sont à égalité.

-- This sport allows no negative scores or tie games.
-- For this test to pass, this query must return no results.

select home_score, visitor_score
from {{ ref('zzz_game_details') }}
where home_score < 0
or visitor_score < 0
or home_score = visitor_score

Dans le répertoire du tests projet, créez un fichier nommé zzz_win_loss_records_check_records.sql avec l’instruction SQL suivante. Ce fichier comprend un test de données permettant de déterminer si des équipes ont eu un nombre négatif de victoires ou de défaites, si elles ont eu plus de victoires ou de défaites que de matchs joués ou si elles ont joué plus de matchs qu’elles n’étaient autorisées.
```
-- Each team participated in 4 games this season.
-- For this test to pass, this query must return no results.

select wins, losses
from {{ ref('zzz_win_loss_records') }}
where wins < 0 or wins > 4
or losses < 0 or losses > 4
or (wins + losses) > 4
```

Une fois l’environnement virtuel activé, exécutez la dbt test commande .

dbt test --models zzz_game_details zzz_win_loss_records

...
... | 1 of 19 START test accepted_values_zzz_game_details_home__Amsterdam__San_Francisco__Seattle [RUN]
... | 1 of 19 PASS accepted_values_zzz_game_details_home__Amsterdam__San_Francisco__Seattle [PASS ...]
...
... |
... | Finished running 19 tests ...

Completed successfully

Done. PASS=19 WARN=0 ERROR=0 SKIP=0 TOTAL=19

Étape 4 : Gardez les modèles frais avec des vues matérialisées et des tableaux de streaming

Lorsqu’un modèle doit rester à jour à l’arrivée de nouvelles données, matérialisez-le sous forme de vue matérialisée ou de table en flux plutôt que de table ou de vue. Une vue matérialisée actualise progressivement les résultats de sa requête, de sorte qu’Azure Databricks ne met à jour que ce qui a changé au lieu de recalculer l’ensemble du résultat à chaque exécution, ce qui rend les vues matérialisées adaptées aux agrégations et aux données fournies aux tableaux de bord. Une table de streaming ingère progressivement des données sources en mode ajout seul ou en continu, telles que des fichiers qui arrivent dans un stockage cloud, sans retraiter les lignes qu’elle a déjà lues. Les deux sont soutenus par des pipelines Lakeflow et constituent les matérialisations recommandées pour les transformations de production qui doivent rester à jour.

Note

Cette étape nécessite un espace de travail activé pour Unity Catalog avec un entrepôt SQL sans serveur. La materialized_view matérialisation est intégrée à dbt, tandis que streaming_table est fournie par l’adaptateur dbt-databricks.

Dans le répertoire du models projet, créez un fichier nommé diamonds_prices_mv.sql avec l’instruction SQL suivante. C’est la même agrégation que la diamonds_prices vue, mais le config bloc indique dbt de créer une vue matérialisée. Contrairement à la vue, qui recalcule à chaque requête, la vue matérialisée précalcule le résultat et le rafraîchit progressivement.
```
{{ config(
  materialized='materialized_view'
) }}
```
```
select color, avg(price) as price
from diamonds
group by color
order by price desc
```
Dans le répertoire du models projet, créez un fichier nommé diamonds_raw_stream.sql avec l’instruction SQL suivante. Le config bloc demande à dbt de créer une table de streaming qui ingère progressivement le fichier CSV source diamonds . La read_files fonction à valeurs de table lit le fichier, et le STREAM mot-clé ne traite que les données nouvellement arrivées à chaque rafraîchissement.
```
{{ config(
  materialized='streaming_table'
) }}
```
```
select * from stream read_files(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  format => 'csv',
  header => true
)
```
Une fois l’environnement virtuel activé, exécutez la commande dbt run avec les chemins d’accès aux deux fichiers précédents.
```
dbt run --model models/diamonds_prices_mv.sql models/diamonds_raw_stream.sql
```

Gardez à l’esprit les comportements suivants lorsque vous mettez à jour ces modèles :

Changer la requête d’une table de streaming ne retraite pas les données déjà ingérées. DBT utilise CREATE OR REFRESH, qui applique la requête mise à jour uniquement aux lignes futures. Pour retraiter les données sources disponibles, exécutez avec --full-refresh.
Modifier la configuration d’une vue matérialisée oblige dbt à la supprimer et à la recréer, sauf en cas de modification de la planification.
Les tags que vous définissez à l’aide de databricks_tags ne peuvent pas être supprimés via dbt une fois appliqués. Pour supprimer une balise, utilisez directement Azure Databricks ou un hook de post-traitement.

Pour la liste complète des configurations prises en charge, telles que les rafrahissements programmés, le partitionnement et les filtres de lignes, voir Vues matérialisées et tables de streaming dans la documentation dbt.

Étape 5 : Nettoyer

Vous pouvez supprimer les tables et les vues que vous avez créées pour cet exemple en exécutant le code SQL suivant.

DROP TABLE zzz_game_opponents;
DROP TABLE zzz_game_scores;
DROP TABLE zzz_games;
DROP TABLE zzz_teams;
DROP TABLE zzz_game_details;
DROP VIEW zzz_win_loss_records;

DROP MATERIALIZED VIEW diamonds_prices_mv;
DROP TABLE diamonds_raw_stream;
DROP TABLE diamonds;
DROP TABLE diamonds_four_cs;
DROP VIEW diamonds_list_colors;
DROP VIEW diamonds_prices;

Note

Si vous n’avez pas effectué l’étape 4, omettez les déclarations DROP MATERIALIZED VIEW diamonds_prices_mv et DROP TABLE diamonds_raw_stream.

Résolution des problèmes

Pour plus d’informations sur les problèmes courants liés à l’utilisation de dbt Core avec Azure Databricks et sur la façon de les résoudre, consultez Obtenir de l’aide sur le site web dbt Labs.

Étapes suivantes

Exécutez des projets dbt Core en tant que tâches de travail Azure Databricks. Voir Utilisation des transformations dbt dans les tâches Lakeflow.
Découvrez les matérialisations qui maintiennent vos données à jour. Consultez Utiliser des vues matérialisées autonomes et Utiliser des tables de diffusion en continu autonomes.

Ressources supplémentaires

Consultez les ressources suivantes sur le site web dbt Labs :

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-10-15