La CLI Dataform Open Source vous permet d'initialiser, de compiler, de tester et d'exécuter Dataform Core localement, en dehors de Google Cloud.
La Dataform CLI 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 ADC, vous devez d'abord fournir vos identifiants à ADC.
Avant de commencer
Avant d'installer la CLI Dataform, installez NPM.
Installer la CLI Dataform
Pour installer Dataform CLI, exécutez la commande suivante :
npm i -g @dataform/cli@^3.0.0-beta
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 où vous souhaitez que Dataform écrive les données BigQuery. Si elle n'est pas définie, 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 provenant du même emplacement, Dataform utilise cet emplacement.
- Si votre requête fait référence à des ensembles de données provenant de deux emplacements différents ou plus, une erreur se produit. Pour en savoir plus sur cette limitation, consultez 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 pour Dataform est la région multirégionale
US
. Pour choisir un autre emplacement, définissez l'emplacement par défaut. Vous pouvez également utiliser la variable système@@location
dans votre requête. Pour en savoir plus, consultez Spécifier des zones.
Mettre à jour Dataform Core
Pour mettre à jour le framework Dataform Core, mettez à jour
dataformCoreVersion
dans le fichierworkflow_settings.yaml
, puis réexécutez l'installation NPM :npm i
Mettre à jour la CLI Dataform
Pour mettre à jour l'outil Dataform CLI, exécutez la commande suivante :
npm i -g @dataform/cli@^3.0.0-beta.2
Créer un fichier d'identifiants
Dataform a besoin d'un fichier d'identifiants pour se connecter aux services à distance et créer le fichier .df-credentials.json
sur votre disque.
Pour créer le fichier d'identifiants, procédez comme suit :
Exécutez la commande suivante :
dataform init-creds
Suivez l'assistant
init-creds
qui vous guide dans 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 permettant 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 projet Google Cloud .DEFAULT_LOCATION
(facultatif) : emplacement où vous souhaitez que Dataform écrive les données BigQuery. Si elle n'est pas définie, 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 provenant du même emplacement, Dataform utilise cet emplacement.
- Si votre requête fait référence à des ensembles de données provenant de deux emplacements différents ou plus, une erreur se produit. Pour en savoir plus sur cette limitation, consultez 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 pour Dataform est la région multirégionale
US
. Pour choisir un autre emplacement, définissez l'emplacement par défaut. Vous pouvez également utiliser la variable système@@location
dans votre requête. Pour en savoir plus, consultez Spécifier des zones.
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
: type de tableau :table
,incremental
ouview
.SELECT_STATEMENT
: instructionSELECT
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
: instructionSELECT
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 reconstruire 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 reconstruire à partir de zéro.
Pour effectuer une simulation de votre code par rapport à BigQuery, exécutez la commande suivante :
dataform run --dry-run
Obtenir de l'aide
Pour lister 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
- 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.