Utiliser la CLI Dataform Open Source

Ce document explique comment utiliser l'interface de ligne de commande (CLI) Dataform Open Source pour développer des workflows localement à l'aide du terminal.

Avec la CLI Dataform Open Source, vous pouvez initialiser, compiler, tester, et exécuter Dataform Core localement, en dehors de Google Cloud.

La CLI Dataform est compatible avec les identifiants par défaut de l'application (ADC). Le service ADC vous permet de mettre des identifiants à disposition de votre application dans divers environnements, tels que le développement local ou de production, sans avoir à modifier le code de votre application. Pour utiliser le service ADC, vous devez d'abord lui fournir vos identifiants.

Avant de commencer

Avant d'installer la CLI Dataform, installez NPM.

Installer la CLI Dataform

  • Pour installer la CLI Dataform, exécutez la commande suivante :

    npm i -g @dataform/cli

Initialiser un projet Dataform

  • Pour initialiser un projet Dataform, exécutez la commande suivante dans le répertoire de votre projet :

    dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION

    Remplacez les éléments suivants :

    • YOUR_GOOGLE_CLOUD_PROJECT_ID: ID de votre Google Cloud projet.
    • DEFAULT_LOCATION : emplacement BigQuery où vous souhaitez que Dataform traite et stocke les données.

Mettre à jour Dataform Core

  • Pour mettre à jour le framework Dataform Core, mettez à jour dataformCoreVersion dans le fichier workflow_settings.yaml. Lorsque dataformCoreVersion est défini dans workflow_settings.yaml, Dataform installe automatiquement @dataform/core au moment de l'exécution. Si votre projet gère plutôt @dataform/core dans un fichier package.json sans dataformCoreVersion dans workflow_settings.yaml, mettez à jour la version dans package.json et exécutez :

    dataform install

Mettre à jour la CLI Dataform

  • Pour mettre à jour l'outil de la CLI Dataform, exécutez la commande suivante :

    npm i -g @dataform/cli@^3.0.50

Créer un fichier d'identifiants

Dataform nécessite un fichier d'identifiants pour se connecter à des services à distance et créer le fichier .df-credentials.json sur votre disque.

Pour créer le fichier d'identifiants, procédez comme suit :

  1. Exécutez la commande suivante :

    dataform init-creds

  2. Suivez l'assistant init-creds qui vous guide tout au long de la création du fichier d'identifiants.

Créer un projet

Un projet Dataform vide dans Dataform Core 3.0.0 ou version ultérieure présente la structure suivante :

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

  • Pour créer un projet Dataform afin de déployer des éléments dans BigQuery, exécutez la commande suivante :

    dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION

    Remplacez les éléments suivants :

    • PROJECT_NAME : nom du répertoire de votre projet.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: ID de votre Google Cloud projet.
    • DEFAULT_LOCATION : emplacement BigQuery où vous souhaitez que Dataform traite et stocke les données.

Cloner un projet

Pour cloner un projet Dataform existant à partir d'un dépôt Git tiers, suivez les instructions de votre fournisseur Git.

  • Si le projet cloné déclare des dépendances externes dans un fichier package.json (sans dataformCoreVersion dans workflow_settings.yaml), exécutez la commande suivante dans le répertoire du dépôt cloné :

    dataform install

Définir une table

Stockez les définitions dans le dossier definitions/.

  • Pour définir une table, exécutez la commande suivante :

    echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx

    Remplacez les éléments suivants :

    • TABLE_TYPE: type de table : table, incremental ou view.
    • SELECT_STATEMENT : instruction SELECT qui définit la table.
    • FILE : nom du fichier de définition de table.

L'exemple de code suivant définit une vue dans le fichier SQLX example.

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

Définir une assertion manuelle

Stockez les définitions dans le dossier definitions/.

  • Pour définir une assertion manuelle, exécutez la commande suivante :

    echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx

    Remplacez les éléments suivants :

    • SELECT_STATEMENT : instruction SELECT qui définit l'assertion.
    • FILE: nom du fichier de définition d'opération SQL personnalisée.

Définir une opération SQL personnalisée

Stockez les définitions dans le dossier definitions/.

  • Pour définir une opération SQL personnalisée, exécutez la commande suivante :

    echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx

    Remplacez les éléments suivants :

    • SQL_QUERY : votre opération SQL personnalisée.
    • FILE: nom du fichier de définition d'opération SQL personnalisée.

Afficher le résultat de la compilation

Dataform compile votre code en temps réel.

  • Pour afficher le résultat du processus de compilation dans le terminal, exécutez la commande suivante :

    dataform compile

  • Pour afficher le résultat du processus de compilation sous forme d'objet JSON, exécutez la commande suivante :

    dataform compile --json

  • Pour afficher le résultat de la compilation avec des variables de compilation personnalisées, exécutez la commande suivante :

    dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar

    Remplacez les éléments suivants :

    • SAMPLE_VAR : votre variable de compilation personnalisée.
    • SAMPLE_VALUE: valeur de votre variable de compilation personnalisée.

Exécuter le code

Pour exécuter votre code, Dataform accède à BigQuery afin de déterminer son état actuel et d'adapter le code SQL résultant en conséquence.

  • Pour exécuter le code de votre projet Dataform, exécutez la commande suivante :

    dataform run

  • Pour exécuter le code de votre projet Dataform dans BigQuery avec des variables de compilation personnalisées, exécutez la commande suivante :

    dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2

    Remplacez les éléments suivants :

    • SAMPLE_VAR : votre variable de compilation personnalisée.
    • SAMPLE_VALUE: valeur de votre variable de compilation personnalisée.

  • Pour exécuter le code de votre projet Dataform dans BigQuery et recréer des tables incrémentales (sauf si elles sont marquées comme protected) à partir de zéro, exécutez la commande suivante :

    dataform run --full-refresh

Sans --full-refresh, Dataform met à jour les tables incrémentales sans les recréer à partir de zéro (les tables et vues standards sont toujours recréées).

  • Pour effectuer un dry run de votre code par rapport à BigQuery, exécutez la commande suivante :

    dataform run --dry-run

Obtenir de l'aide

  • Pour afficher la liste de toutes les commandes et options disponibles, exécutez la commande suivante :

    dataform help

  • Pour afficher la description d'une commande spécifique, exécutez la commande suivante :

    dataform help COMMAND

    Remplacez COMMAND par la commande sur laquelle vous souhaitez en savoir plus.

Étape suivante