Tutoriel : Premiers pas avec les projets dbt sur Snowflake¶

Introduction¶

Ce tutoriel vous guide dans la création d’un espace de travail pour dbt Projects on Snowflake qui est connecté à un dépôt GitHub que vous faites bifurquer depuis notre dépôt getting-started-with-dbt-on-snowflake dans Snowflake Labs. Vous utilisez ensuite l’espace de travail pour mettre à jour les fichiers de projet dbt, et pour tester et exécuter le projet dbt, qui matérialise la sortie du modèle de données du projet dbt dans les bases de données et les schémas cibles de Snowflake. Vous déployez le projet pour créer un objet de projet dbt sur Snowflake. Enfin, vous configurez une tâche pour exécuter le projet selon un calendrier que vous définissez.

Configurer votre environnement¶

Suivez les étapes ci-dessous pour configurer votre environnement pour ce tutoriel :

1. Créer et cloner le dépôt dbt Projects on Snowflake de démarrage

2. (Facultatif) Créer un entrepôt pour exécuter des actions d’espace de travail

3. Créer une base de données et un schéma pour les intégrations et les matérialisations de modèles

4. Créer une intégration d’API dans Snowflake pour une connexion à GitHub

5. Créer une intégration d’accès externe dans Snowflake pour les dépendances dbt

CREATE WAREHOUSE tasty_bytes_dbt_wh WAREHOUSE_SIZE = XLARGE;

CREATE DATABASE tasty_bytes_dbt_db;
CREATE SCHEMA tasty_bytes_dbt_db.integrations;
CREATE SCHEMA tasty_bytes_dbt_db.dev;
CREATE SCHEMA tasty_bytes_dbt_db.prod;

USE tasty_bytes_dbt_db.integrations;
CREATE OR REPLACE SECRET tasty_bytes_dbt_db.integrations.tb_dbt_git_secret
  TYPE = password
  USERNAME = 'your-gh-username'
  PASSWORD = 'YOUR_PERSONAL_ACCESS_TOKEN';

CREATE OR REPLACE API INTEGRATION tb_dbt_git_api_integration
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://github.com/my-github-account')
  -- Comment out the following line if your forked repository is public
  ALLOWED_AUTHENTICATION_SECRETS = (tasty_bytes_dbt_db.integrations.tb_dbt_git_secret)
  ENABLED = TRUE;

-- Create NETWORK RULE for external access integration

CREATE OR REPLACE NETWORK RULE dbt_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  -- Minimal URL allowlist that is required for dbt deps
  VALUE_LIST = (
    'hub.getdbt.com',
    'codeload.github.com'
    );

-- Create EXTERNAL ACCESS INTEGRATION for dbt access to external dbt package locations

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION dbt_ext_access
  ALLOWED_NETWORK_RULES = (dbt_network_rule)
  ENABLED = TRUE;

Créer un espace de travail connecté à votre dépôt Git¶

Dans cette étape, vous créez un espace de travail dans Snowsight qui est connecté à votre dépôt GitHub. Pour plus d’informations sur les espaces de travail, voir Snowsight.

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation gauche, sélectionnez. Projects » Espaces de travail.

3. Dans la liste Espaces de travail au-dessus de la zone des fichiers d’espaces de travail, sous Create Workspace, sélectionnez From Git repository. (La liste Espaces de travail a une sélection par défaut de My Workspace.)

4. Pour Repository URL, entrez l’URL SSH de votre dépôt GitHub bifurqué ; par exemple : https://github.com/my-github-account/getting-started-with-dbt-on-snowflake.git

5. Pour Workspace name, saisissez un nom. Plus loin dans ce tutoriel, nous utilisons tasty_bytes_dbt.

6. Sous API integration, sélectionnez le nom de l’intégration d’API que vous avez créée précédemment ; par exemple, TB_DBT_GIT_API_INTEGRATION.

7. Si votre dépôt GitHub est public, sélectionnez Public repository, puis sélectionnez Create.

   Note

   Les espaces de travail ne prennent pas en charge la validation et le transfert de modifications d’un espace de travail vers un dépôt public.

8. Si votre dépôt GitHub est privé et vous avez créé un secret pour votre intégration d’API pendant la configuration, procédez comme suit :

   1. Sélectionnez Personal access token.

   2. Sous Credentials secret, sélectionnez Select database and schema.

   3. Sélectionnez la base de données dans la liste (par exemple, TASTY_BYTES_DBT_DB), puis sélectionnez le schéma dans la liste (par exemple, INTEGRATIONS) où vous avez stocké l’intégration d’API.

   4. Sélectionnez Select secret, puis sélectionnez votre secret dans la liste. par exemple, tb_dbt_git_secret.

9. Sélectionnez Create.

   Snowflake se connecte au dépôt GitHub que vous avez spécifié et ouvre votre nouvel espace de travail. Un seul dossier dans l’espace de travail nommé tasty_bytes_dbt_demo contient le projet dbt avec lequel vous allez travailler.

tasty_bytes:
target: dev
outputs:
  dev:
    type: snowflake
    account: 'not needed'
    user: 'not needed'
    role: accountadmin
    database: tasty_bytes_dbt_db
    schema: dev
    warehouse: tasty_bytes_dbt_wh
  prod:
    type: snowflake
    account: 'not needed'
    user: 'not needed'
    role: accountadmin
    database: tasty_bytes_dbt_db
    schema: prod
    warehouse: tasty_bytes_dbt_wh

Exécuter les commandes SQL dans tasty_bytes_setup.sql pour configurer les données sources¶

Comme donnée source pour ses transformations, le projet dbt de votre dépôt utilise le modèle de données de base pour la marque fictive de food truck Tasty Bytes. Le script SQL pour créer le modèle de données se trouve dans l’espace de travail.

1. Dans votre espace de travail, naviguez jusqu’au fichier tasty_bytes_dbt_demo/setup/tasty_bytes_setup.sql, puis ouvrez-le.

2. Dans le sélecteur de contexte en haut à droite de l’éditeur d’espace de travail, sélectionnez l’entrepôt que vous avez créé précédemment ; par exemple, TASTY_BYTES_DBT_WH.

3. Le fichier SQL contient des commandes que vous avez déjà exécutées dans ce tutoriel. Au début du fichier, recherchez les commandes suivantes, puis commentez-les afin de ne pas les exécuter à nouveau et de créer des ressources en double :

   CREATE OR REPLACE WAREHOUSE ...;
   CREATE OR REPLACE API INTEGRATION ...;
   CREATE OR REPLACE NETWORK RULE ...;
   CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION ...;
   

   Copy

4. Exécutez les commandes SQL sans commentaire dans le fichier.

   Astuce

   Utilisez cmd + :kbd :Maj + :kbd :Entrée pour exécuter toutes les commandes sans commentaire.

   L’onglet Output affiche le message suivant :

   tb_101 setup is now complete

ALTER SCHEMA tasty_bytes_dbt_db.dev SET LOG_LEVEL = 'INFO';
ALTER SCHEMA tasty_bytes_dbt_db.dev SET TRACE_LEVEL = 'ALWAYS';
ALTER SCHEMA tasty_bytes_dbt_db.dev SET METRIC_LEVEL = 'ALL';

ALTER SCHEMA tasty_bytes_dbt_db.prod SET LOG_LEVEL = 'INFO';
ALTER SCHEMA tasty_bytes_dbt_db.prod SET TRACE_LEVEL = 'ALWAYS';
ALTER SCHEMA tasty_bytes_dbt_db.prod SET METRIC_LEVEL = 'ALL';

Exécuter la commande dbt deps pour votre projet¶

Vous pouvez utiliser l’espace de travail pour exécuter des commandes dbt courantes pour un projet. Pour une liste des commandes disponibles, voir Commandes dbt prises en charge. Pour exécuter une commande, vous sélectionnez le:ui:Project dbt et la commande:ui:Profile dbt à partir des listes au-dessus l’éditeur d’espace de travail. Vous sélectionnez ensuite le bouton d’exécution. Utilisez la flèche vers le bas à côté du bouton d’exécution pour spécifier des arguments supplémentaires pris en charge par la commande dbt.

Lorsque vous exécutez une commande dbt dans l’espace de travail, l’onglet Output montre la commande qui s’exécute sur Snowflake (en vert) et la sortie stdout pour cette commande afin que vous puissiez surveiller la réussite ou l’échec de la commande.

La première commande que vous devez exécuter pour tout projet dbt est deps, qui met à jour les dépendances de votre projet spécifié dans le fichier packages.yml de votre projet. Les autres commandes échoueront si vous n’avez pas mis à jour les dépendances. Pour plus d’informations, voir Dépendances dbt.

1. Sous l’éditeur d’espace de travail, ouvrez l’onglet Output pour que vous puissiez voir stdout après avoir exécuté des commandes dbt à partir de l’espace de travail.

2. Dans la barre de menu au-dessus de l’éditeur d’espace de travail, confirmez que la valeur par défaut Project (tasty_bytes_dbt_demo) est sélectionnée. Vous pouvez avoir n’importe quel Profile sélectionné. Ce projet a les profils dev et prod définis dans le fichier profiles.yml.

3. Sélectionnez la liste Profile, puis choisissez Enable secondary roles pour activer les rôles secondaires pour ce projet et cette session.

   Note

   Vous devez activer les rôles secondaires initialement pour exécuter des commandes dbt pour chaque projet pendant chaque session Snowsight. Les comptes Enterprise Edition peuvent être configurés pour interdire les rôles secondaires pour un utilisateur spécifique ou pour tous les utilisateurs. Pour plus d’informations, voir Les rôles secondaires sont requis par projet, par session.

4. Dans la liste de commandes, sélectionnez. Deps.

5. À côté du bouton d’exécution, sélectionnez la flèche vers le bas.

6. Dans la fenêtre Deps dbt, laissez Run with defaults sélectionné, puis saisissez le nom de l”External Access Integration que vous avez créé lors de la configuration dans l’espace prévu à cet effet. par exemple, dbt_ext_access.

7. Pour exécuter la commande, sélectionnez. Deps.

   L’onglet Output affiche la commande SQL s’exécutant sur Snowflake, qui est similaire à ce qui suit :

   execute dbt project from workspace "USER$"."PUBLIC"."tasty_bytes_dbt" project_root='tasty_bytes_dbt_demo' args='deps --target dev' external_access_integrations = (dbt_ext_access)
   

   Copy

   Lorsque la commande se termine, des messages stdout apparaissent qui sont similaires à ce qui suit :

   14:47:19  Running with dbt=1.8.9
   14:47:19  Updating lock file in file path: /tmp/dbt/package-lock.yml
   14:47:19  Installing dbt-labs/dbt_utils
   14:47:19  Installed from version 1.3.0
   14:47:19  Up to date!
   Uploading /tmp/dbt/package-lock.yml to snow://workspace/USER$ADMIN.PUBLIC."tasty_bytes_dbt"/versions/live/dbt//package-lock.yml
   

   Le fichier package_lock.yml est créé et apparaît dans votre liste de fichiers d’espace de travail avec un A à côté. Cela indique que le fichier a été ajouté dans l’espace de travail de votre projet dbt, avec un contenu similaire à l’exemple suivant :

   packages:
     - package: dbt-labs/dbt_utils
       version: 1.3.0
   

   Copy

Compiler le projet dbt, voir le DAG et voir les instructions SQL compilées¶

La compilation d’un projet en dbt crée des instructions SQL exécutables à partir des fichiers SQL modélisés et une représentation visuelle du graphe orienté acyclique (DAG) pour le projet dans l’espace de travail. Pour plus d’informations sur la compilation des projets dbt, voir compiler dans la documentation dbt.

Après avoir compilé le projet dans l’espace de travail, vous pouvez voir les DAG. Vous pouvez également ouvrir n’importe quel fichier SQL dans le dossier models pour voir le modèle SQL et les instructions SQL compilées dans des onglets côte à côte.

1. Sélectionnez le projet et la cible que vous souhaitez compiler.

2. Dans la liste de commandes, sélectionnez. Compile, puis sélectionnez le bouton d’exécution (en option, vous pouvez sélectionner la flèche vers le bas et spécifier les arguments de la commande de compilation).

3. Dans la zone située sous l’éditeur d’espace de travail, sélectionnez l’onglet DAG.

   Vous pouvez utiliser le volet DAG pour visualiser les transformations de votre projet dbt à partir des fichiers sources vers les objets de modèle de données matérialisés dans Snowflake.

   • Cliquez et faites glisser n’importe où dans le volet pour partitionner la vue.

   • Utilisez les boutons + et – pour effectuer un zoom avant et arrière.

4. Pour afficher le contenu du fichier source d’un objet dans l’éditeur, sélectionnez une vignette pour n’importe quel objet.

5. Pour voir les instructions SQL compilées dans une vue à deux volets de l’éditeur d’espace de travail :

   1. Dans le DAG, sélectionnez la vignette d’un fichier de modèles SQL dbt; par exemple, orders.

      –OR–

      Dans la liste des fichiers de l’espace de travail, sélectionnez n’importe quel fichier dans le sous-répertoire models de votre projet dbt pour l’ouvrir dans l’éditeur d’espace de travail.

   2. Choisissez View Compiled SQL en haut à droite de l’éditeur d’espace de travail pour voir les instructions SQL compilées dans une vue à volets partagés.

Exécuter le projet dev dbt et vérifiez les objets Snowflake matérialisés¶

En exécutant la commande dbt run, vous exécutez vos instructions SQL compilées par rapport à la base de données et au schéma cibles en utilisant l’entrepôt Snowflake et le rôle qui sont spécifiés dans le fichier profiles.yml du projet. Dans cette étape, nous allons matérialiser la sortie de la cible Dev dans votre projet de démonstration dbt. Vous créez ensuite une feuille de calcul SQL nommée dbt_sandbox.sql dans l’espace de travail où vous pouvez exécuter les instructions SQL pour vérifier la création de l’objet.

1. À partir de la liste Profile, sélectionnez Dev.

2. Dans la liste de commandes, sélectionnez. Run, puis sélectionnez le bouton d’exécution.

   Le volet de sortie indique l’état d’achèvement de l’exécution.

3. Dans votre projet tasty_bytes_dbt_demo, accédez au dossier examples, sélectionnez le + à côté du nom du dossier, puis sélectionnez le SQL File.

4. Saisissez dbt_sandbox.sql, puis appuyez sur Entrée.

5. Dans l’onglet de l’espace de travail pour dbt_sandbox.sql, exécutez la requête suivante :

   SHOW TABLES IN DATABASE tasty_bytes_dbt_db;
   

   Copy

   Dans le volet Status and Results, vous devriez voir les tables CUSTOMER_LOYALTY_METRICS, ORDERS, et SALES_METRICS_BY_LOCATION.

6. Pour voir les vues créées par votre projet dbt, exécutez la commande suivante :

   SHOW VIEWS IN DATABASE tasty_bytes_dbt_db;
   

   Copy

Transférer les mises à jour de fichiers de l’espace de travail vers votre dépôt¶

Maintenant que vous avez mis à jour votre espace de travail et que vous avez compilé, testé, exécuté et déployé votre projet en tant qu’objet de projet dbt, vous pouvez transférer les modifications que vous avez apportées dans l’espace de travail vers votre dépôt GitHub privé. Cette étape n’est pas prise en charge pour les dépôts publics.

1. Lorsque votre espace de travail est ouvert, sélectionnez. Changes.

   La liste des fichiers de l’espace de travail est filtrée pour n’afficher que les fichiers qui ont changé depuis la synchronisation avec le dépôt Git.

   • A indique un fichier ajouté dans l’espace de travail et non dans le dépôt Git.

   • M indique un fichier modifié.

   • D indique un fichier supprimé.

2. Sélectionnez un fichier pour voir sa différence avec GitHub depuis le dernier transfert (dans ce cas, la date de création de l’espace de travail).

3. Dans la barre de menu au-dessus de la liste des fichiers de l’espace de travail, vérifiez que le sélecteur de branches est défini sur main pour ce tutoriel.

4. Sélectionnez le bouton Push, puis saisissez un message de validation dans la case prévue à cet effet ; par exemple, Updating project with initial changes from dbt on Snowflake.

5. Sélectionnez Push.

   Un transfert vers votre dépôt peut prendre plusieurs minutes.

Déployer l’objet de projet dbt à partir de l’espace de travail¶

Le déploiement de votre projet dbt à partir d’un espace de travail crée un objet de projet dbt. Vous pouvez utiliser l’objet pour planifier, exécuter et surveiller un projet dbt dans Snowflake en dehors de l’espace de travail.

Lorsque vous déployez votre objet de projet dbt de l’espace de travail vers une base de données et un schéma Snowflake, vous pouvez créer ou remplacer un objet que vous avez précédemment créé.

1. Sur le côté droit de l’éditeur d’espace de travail, sélectionnez. Connect » Deploy dbt project.

2. Sélectionnez Select database and schema, puis sélectionnez la base de données TASTY_BYTES_DBT_DB et le schéma DEV.

3. Sous Select or Create dbt Object, sélectionnez Create dbt Object.

4. Sous Enter Name, tapez TASTY_BYTES_DBT_PROJECT puis sélectionnez Deploy.

   L’onglet Output affiche la commande s’exécutant sur Snowflake, qui est similaire à l’exemple suivant :

   create or replace DBT PROJECT "TASTY_BYTES_DBT_DB"."DEV"."TASTY_BYTES_DBT_PROJECT" from snow://workspace/USER$MYUSER.PUBLIC."tasty_bytes_dbt_demo"/versions/live/dbt
   
   tasty_bytes_dbt_project successfully created.
   

   Copy

   Le menu Connect affiche maintenant le nom de l’objet de projet dbt que vous avez créé, avec les options suivantes :

   • Redeploy dbt project – Met à jour l’objet de projet dbt avec la version actuelle de l’espace de travail du projet en utilisant ALTER. Cela incrémente la version de l’objet de projet dbt par un. Pour plus d’informations, voir Gestion des versions pour les objets et fichiers de projet dbt.

   • Disconnect – Déconnecte l’espace de travail de l’objet de projet dbt, mais ne supprime pas l’objet de projet dbt.

   • View project – Ouvre l’objet de projet dbt dans l’explorateur d’objets, où vous pouvez voir la commande CREATE DBT PROJECTpour l’objet de projet dbt et l’historique d’exécution du projet.

   • Create schedule – Fournit des options pour vous permettre de créer une tâche qui exécute l’objet de projet dbt selon une planification. Pour plus d’informations, voir Créer une tâche pour planifier l’exécution d’un projet dbt.

   • View schedules – Ouvre une liste de planifications (tâches) qui exécutent l’objet de projet dbt, avec la possibilité d’afficher les détails des tâches dans l’explorateur d’objets.

5. Pour vérifier la création du projet, effectuez l’une ou les deux tâches suivantes :

   • Dans le menu du projet dbt, sélectionnez View project pour ouvrir l’objet de projet dbt dans l’explorateur d’objets.

     –OR–

   • À partir de la feuille de calcul du fichier dbt_sandbox.sql que vous avez créée précédemment, exécutez la commande suivante :

     SHOW DBT PROJECTS LIKE 'tasty%';
     

     Copy

Créer une tâche pour planifier l’exécution d’un projet dbt¶

Maintenant que vous avez déployé votre objet de projet dbt, vous pouvez utiliser l’espace de travail ou SQL pour configurer une tâche qui exécute une commande dbt sur votre objet de projet dbt.

Les étapes suivantes permettent d’établir un calendrier d’exécution du projet dbt toutes les heures à une minute après l’heure. La tâche exécute la commande dbt run avec l’option --select pour exécuter le modèle customer_loyalty_metrics dans le projet dbt.

1. Dans le menu du projet dbt en haut à droite de l’éditeur d’espace de travail, choisissez Create schedule.

2. Dans la boîte de dialogue Schedule a dbt run, procédez comme suit :

   • Pour Schedule name, saisissez un nom pour la tâche ; par exemple, run_prepped_data_dbt.

   • Pour Frequency, laissez Hourly à 01 pour votre fuseau horaire sélectionné.

   • Sous dbt properties :

     • Pour Operation, sélectionnez run.

     • Pour Profile, sélectionnez dev.

     • Pour Additional flags, saisissez --select customer_loyalty_metrics.

3. Choisissez Create.

   Snowflake crée une tâche qui exécute une commande EXECUTE DBT PROJECT utilisant ces paramètres. Pour plus d’informations sur les tâches et les options de tâches, voir Introduction aux tâches et CREATE TASK.

4. Dans le menu du projet dbt, sélectionnez View schedules, puis choisissez votre planification dans la liste.

   L’explorateur d’objets s’ouvre dans votre base de données avec le volte Task Details ouvert pour la tâche. La Task Definition affiche une commande CREATE TASK similaire à ce qui suit :

   CREATE OR REPLACE TASK tasty_bytes_dbt_db.dev.run_prepped_data_dbt
           WAREHOUSE=tasty_bytes_dbt_wh
           SCHEDULE ='USING CRON 1 * * * * America/Los_Angeles'
         AS
     EXECUTE DBT PROJECT tasty_bytes_dbt_project ARGS='run --select customer_loyalty_metrics --target dev';
   

   Copy

Nettoyage¶

Vous pouvez supprimer les bases de données, les espaces de travail et l’entrepôt que vous avez créés pour nettoyer après ce tutoriel.

Exécutez les commandes SQL suivantes à partir de votre feuille de calcul dbt_sandbox.sql pour supprimer l’entrepôt, les bases de données TASTY_BYTES_DBT_DB et TB_101 que vous avez créés, et tous les schémas et objets créés dans les bases de données :

DROP WAREHOUSE IF EXISTS tasty_bytes_dbt_wh;
DROP DATABASE IF EXISTS tasty_bytes_dbt_db;
DROP DATABASE IF EXISTS tb_101;

Copy

Pour supprimer votre espace de travail tasty_bytes_dbt_demo :

• Dans le menu vertical indiqué par une ellipse à côté du menu de l’espace de travail en haut de l’explorateur d’espaces de travail, sélectionnez. Delete, puis confirmez la suppression lorsque vous y êtes invité.