Utiliser la CLI Dataform Open Source

Ce document explique comment utiliser l'interface de ligne de commande (CLI) Open Source Dataform 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 pour déployer des éléments dans les entrepôts de données suivants:

  • BigQuery
  • Snowflake
  • Redshift
  • Azure SQL Data Warehouse
  • Postgres

Dataform distribue une image Docker que vous pouvez utiliser pour exécuter l'équivalent des commandes de la CLI Dataform.

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@^2.3.2

Initialiser un projet Dataform

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

    dataform init

Mettre à jour Dataform

  • Pour mettre à jour le framework Dataform, exécutez la commande suivante dans le répertoire du projet contenant votre fichier dataform.json:

    npm i @dataform/core@^2.3.2

Mettre à jour la CLI Dataform

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

    npm i -g @dataform/cli@^2.3.2

Créer un fichier d'identifiants

Dataform a besoin d'un fichier d'identifiants pour se connecter à votre entrepôt 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 WAREHOUSE

    Remplacez WAREHOUSE par votre entrepôt: bigquery, postgres, redshift, snowflake ou sqldatawarehouse.

  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 présente la structure suivante:

   project-dir
   ├── definitions
   ├── includes
   ├── package.json
   └── dataform.json

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

    dataform init bigquery PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID

    Remplacez PROJECT_NAME par le nom de votre projet et YOUR_GOOGLE_CLOUD_PROJECT_ID par l'ID de votre projet Google Cloud.

  • Pour créer un projet Dataform afin de déployer des éléments sur Postgres, Redshift, Snowflake ou Azure SQL Data Warehouse, exécutez la commande suivante:

    dataform init WAREHOUSE PROJECT_NAME

    Remplacez PROJECT_NAME par le nom de votre projet et WAREHOUSE par votre entrepôt: postgres, redshift, snowflake ou sqldatawarehouse.

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 un tableau

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 par le type de la table : table, incremental ou view.
    • SELECT_STATEMENT avec une instruction SELECT qui définit la table.
    • FILE par le 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 par une instruction SELECT qui définit l'assertion.
    • FILE par le nom du fichier de définition de l'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 par votre opération SQL personnalisée.
    • FILE par le nom du fichier de définition de l'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 dans un 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 par votre variable de compilation personnalisée.
    • SAMPLE_VALUE par la valeur de votre variable de compilation personnalisée.

Exécuter le code

Pour exécuter votre code, Dataform accède à votre entrepôt de données afin de déterminer son état actuel et d'adapter le code SQL obtenu en conséquence.

  • Pour exécuter le code de votre projet Dataform dans votre entrepôt de données, exécutez la commande suivante:

    dataform run

  • Pour exécuter le code de votre projet Dataform dans votre entrepôt de données 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 par votre variable de compilation personnalisée.
    • SAMPLE_VALUE par la valeur de votre variable de compilation personnalisée.

  • Pour exécuter le code de votre projet Dataform dans votre entrepôt de données 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 afficher le code SQL final compilé adapté à l'état actuel de votre entrepôt, sans l'exécuter dans votre entrepôt, exécutez la commande suivante:

    dataform run --dry-run

Obtenir de l'aide

  • Pour répertorier 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.

Étapes suivantes