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.

Remarque : À partir de Dataform Core 3.0.0., Dataform ne distribue pas d'image Docker. Vous pouvez créer votre propre image Docker de Dataform, que vous pouvez utiliser pour exécuter l'équivalent des commandes de la CLI Dataform. Pour créer votre propre image Docker, consultez la section Conteneuriser une application dans la documentation Docker.

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
  

Remarque : La version 3.0.0-beta n’est pas compatible. Si npm audit signale une vulnérabilité de gravité élevée liée au package vm2, notez que, bien que Dataform utilise vm2, il ne l'utilise pas pour le bac à sable, qui est la source des vulnérabilités signalées.vm2 Les versions plus récentes de la CLI Dataform ne dépendent pas des versions vm2 vulnérables.

Initialiser un projet Dataform

• Pour initialiser un 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 (facultatif) : emplacement dans lequel vous souhaitez que Dataform écrive les données BigQuery. Si ce paramètre n'est pas défini, Dataform détermine l'emplacement en fonction des ensembles de données auxquels votre requête SQL fait référence. Voici comment cela fonctionne :

    • Si votre requête fait référence à des ensembles de données du même emplacement, Dataform utilise cet emplacement.
    • Si votre requête fait référence à des ensembles de données provenant d'au moins deux emplacements différents, une erreur se produit. Pour en savoir plus sur cette limitation, consultez la section Réplication interrégionale d'ensembles de données.
    • Si votre requête ne fait référence à aucun ensemble de données, l'emplacement par défaut de Dataform est l'emplacement multirégional US. Pour choisir un autre emplacement, définissez l'emplacement par défaut. Vous pouvez également utiliser la @@location variable système dans votre requête. Pour en savoir plus, consultez la section Spécifier des emplacements.

Mettre à jour Dataform Core

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

  npm i
  

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.

Avertissement : Si vous utilisez un système de contrôle des sources, n'effectuez pas de commit du fichier .df-credentials.json dans votre dépôt pour protéger ces identifiants d'accès. Nous vous recommandons d'ajouter le fichier .df-credentials.json à .gitignore.

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 de votre projet.
  • YOUR_GOOGLE_CLOUD_PROJECT_ID: ID de votre Google Cloud projet.

  • DEFAULT_LOCATION (facultatif) : emplacement dans lequel vous souhaitez que Dataform écrive les données BigQuery. Si ce paramètre n'est pas défini, Dataform détermine l'emplacement en fonction des ensembles de données auxquels votre requête SQL fait référence. Voici comment cela fonctionne :

    • Si votre requête fait référence à des ensembles de données du même emplacement, Dataform utilise cet emplacement.
    • Si votre requête fait référence à des ensembles de données provenant d'au moins deux emplacements différents, une erreur se produit. Pour en savoir plus sur cette limitation, consultez la section Réplication interrégionale d'ensembles de données.
    • Si votre requête ne fait référence à aucun ensemble de données, l'emplacement par défaut de Dataform est l'emplacement multirégional US. Pour choisir un autre emplacement, définissez l'emplacement par défaut. Vous pouvez également utiliser la @@location variable système dans votre requête. Pour en savoir plus, consultez la section Spécifier des emplacements.

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 table : table, incremental ou view.
  • SELECT_STATEMENT : instruction SELECT qui définit la table.
  • FILE : nom du fichier de définition de la 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 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 : votre opération SQL personnalisée.
  • FILE: 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 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 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émentales sans les recréer à partir de zéro.

• Pour exécuter une simulation de votre code par rapport à BigQuery, exécutez la commande suivante :

  dataform run --dry-run
  

Remarque : Dans Dataform Core 3.0.2 ou version ultérieure, Dataform effectue une simulation de chaque action dans le résultat de votre compilation par rapport à BigQuery et nécessite les autorisations IAM correspondantes. Pour vérifier la compilation sans simulation, consultez le résultat de la compilation.

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

• Pour en savoir plus sur la CLI Dataform, consultez la documentation de référence de la CLI Dataform .
• Pour en savoir plus sur Dataform, consultez la présentation de Dataform.