Utiliser la CLI Dataform Open Source

Ce document explique comment utiliser Dataform Open Source interface de ligne de commande (CLI) pour développer localement des workflows SQL à 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). Avec l'ADC, vous pouvez mettre des identifiants à la disposition de votre application dans de nombreuses d'environnements, tels que le développement local ou la production, sans avoir à modifier le code de votre application. Pour utiliser ADC, vous devez d'abord fournir vos identifiants à l'ADC.

Avant de commencer

Avant d'installer la CLI Dataform, installez GPR

Installer la CLI Dataform

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

    npm i -g @dataform/cli@^3.0.0-beta

Initialiser un projet Dataform

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

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Remplacez les éléments suivants :

    • PROJECT_NAME : nom de votre projet.
    • DEFAULT_LOCATION: région dans laquelle vous souhaitez Dataform pour écrire des données BigQuery Pour plus d'informations sur les régions BigQuery, consultez Emplacements BigQuery.

Mettre à jour Dataform

  • Pour mettre à jour le framework Dataform, mettez à jour le dataformCoreVersion. dans le fichier workflow_settings.yaml, puis réexécutez NPM install:

    npm i

Mettre à jour la CLI Dataform

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

    npm i -g @dataform/cli@^3.0.0-beta.2

Créer un fichier d'identifiants

Dataform nécessite un fichier d'identifiants pour se connecter aux services distants et créez 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-beta.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-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Remplacez les éléments suivants :

    • PROJECT_NAME : nom de votre projet.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID : ID de votre projet Google Cloud.

Cloner un projet

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

  • Une fois le dépôt cloné, 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 la table. table, incremental ou view.
    • SELECT_STATEMENT: une 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: une instruction SELECT qui définit l'assertion.
    • FILE: nom de l'opération SQL personnalisée. fichier de définition d'origine.

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 de l'opération SQL personnalisée. fichier de définition d'origine.

Afficher la sortie de compilation

Dataform compile votre code en temps réel.

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

    dataform compile

  • Pour afficher le résultat du processus de compilation en tant qu'objet JSON, exécutez la commande suivante:

    dataform compile --json

  • Pour afficher le résultat de la compilation avec 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: la valeur de votre variable de compilation personnalisée.

Exécuter le code

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

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

    dataform run

  • 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: la valeur de votre variable de compilation personnalisée.

  • Pour exécuter le code de votre projet Dataform dans BigQuery et recréer toutes les tables à partir de zéro, exécutez la commande suivante:

    dataform run --full-refresh

Sans --full-refresh, Dataform met à jour les tables incrémentielles sans les recréer entièrement.

  • Pour voir le code SQL final compilé adapté à l'état actuel de sans l'exécuter dans 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 qui vous intéresse.

Étape suivante