Utilizzare l'interfaccia a riga di comando Dataform open source

Questo documento mostra come utilizzare l'interfaccia a riga di comando (CLI) open source di Dataform per sviluppare localmente i workflow utilizzando il terminale.

Con la CLI open source di Dataform, puoi inizializzare, compilare, testare, ed eseguire Dataform Core localmente, al di fuori di Google Cloud.

La CLI di Dataform supporta le Credenziali predefinite dell'applicazione (ADC). Con le ADC, puoi rendere disponibili le credenziali per la tua applicazione in vari ambienti, ad esempio per lo sviluppo locale o la produzione, senza dover modificare il codice dell'applicazione. Per utilizzare le ADC, devi prima fornire le tue credenziali alle ADC.

Prima di iniziare

Prima di installare la CLI di Dataform, installa NPM.

Installare la CLI di Dataform

  • Per installare la CLI di Dataform, esegui questo comando:

    npm i -g @dataform/cli

Inizializzare un progetto Dataform

  • Per inizializzare un nuovo progetto Dataform, esegui questo comando nella directory del progetto:

    dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION

    Sostituisci quanto segue:

    • YOUR_GOOGLE_CLOUD_PROJECT_ID: l' Google Cloud ID progetto.
    • DEFAULT_LOCATION: la località BigQuery in cui vuoi che Dataform elabori e memorizzi i dati.

Aggiornare Dataform Core

  • Per aggiornare il framework Dataform Core, aggiorna dataformCoreVersion nel file workflow_settings.yaml. Quando dataformCoreVersion è impostato in workflow_settings.yaml, Dataform installa @dataform/core automaticamente in fase di runtime. Se invece il progetto gestisce @dataform/core in un file package.json senza dataformCoreVersion in workflow_settings.yaml, aggiorna la versione in package.json ed esegui:

    dataform install

Aggiornare la CLI di Dataform

  • Per aggiornare lo strumento della CLI di Dataform, esegui questo comando:

    npm i -g @dataform/cli@^3.0.50

Creare un file di credenziali

Dataform richiede un file di credenziali per connettersi ai servizi remoti e creare il file .df-credentials.json sul disco.

Per creare il file di credenziali:

  1. Esegui questo comando:

    dataform init-creds

  2. Segui la procedura guidata init-creds che ti guida nella creazione del file di credenziali.

Creare un progetto

Un progetto Dataform vuoto in Dataform Core 3.0.0 o versioni successive ha la seguente struttura:

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

  • Per creare un progetto Dataform per eseguire il deployment degli asset in BigQuery, esegui questo comando:

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

    Sostituisci quanto segue:

    • PROJECT_NAME: il nome della directory del progetto.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: l' Google Cloud ID progetto.
    • DEFAULT_LOCATION: la località BigQuery in cui vuoi che Dataform elabori e memorizzi i dati.

Clonare un progetto

Per clonare un progetto Dataform esistente da un repository Git di terze parti, segui le istruzioni del tuo provider Git.

  • Se il progetto clonato dichiara dipendenze esterne in un file package.json (senza dataformCoreVersion in workflow_settings.yaml), esegui questo comando nella directory del repository clonato:

    dataform install

Definire una tabella

Archivia le definizioni nella cartella definitions/.

  • Per definire una tabella, esegui questo comando:

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

    Sostituisci quanto segue:

    • TABLE_TYPE: il tipo di tabella: table, incremental o view.
    • SELECT_STATEMENT: un'istruzione SELECT che definisce la tabella.
    • FILE: il nome del file di definizione della tabella.

Il seguente esempio di codice definisce una visualizzazione nel file SQLX example.

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

Definire un'asserzione manuale

Archivia le definizioni nella cartella definitions/.

  • Per definire un'asserzione manuale, esegui questo comando:

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

    Sostituisci quanto segue:

    • SELECT_STATEMENT: un'istruzione SELECT che definisce l'asserzione.
    • FILE: il nome del file di definizione dell'operazione SQL personalizzata.

Definire un'operazione SQL personalizzata

Archivia le definizioni nella cartella definitions/.

  • Per definire un'operazione SQL personalizzata, esegui questo comando:

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

    Sostituisci quanto segue:

    • SQL_QUERY: la tua operazione SQL personalizzata.
    • FILE: il nome del file di definizione dell'operazione SQL personalizzata.

Visualizzare l'output di compilazione

Dataform compila il codice in tempo reale.

  • Per visualizzare l'output del processo di compilazione nel terminale, esegui questo comando:

    dataform compile

  • Per visualizzare l'output del processo di compilazione come oggetto JSON, esegui questo comando:

    dataform compile --json

  • Per visualizzare l'output della compilazione con variabili di compilazione personalizzate, esegui questo comando:

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

    Sostituisci quanto segue:

    • SAMPLE_VAR: la tua variabile di compilazione personalizzata.
    • SAMPLE_VALUE: il valore della variabile di compilazione personalizzata.

Eseguire codice

Per eseguire il codice, Dataform accede a BigQuery per determinarne lo stato attuale e adattare di conseguenza l'SQL risultante.

  • Per eseguire il codice del progetto Dataform, esegui questo comando:

    dataform run

  • Per eseguire il codice del progetto Dataform in BigQuery con variabili di compilazione personalizzate, esegui questo comando:

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

    Sostituisci quanto segue:

    • SAMPLE_VAR: la tua variabile di compilazione personalizzata.
    • SAMPLE_VALUE: il valore della variabile di compilazione personalizzata.

  • Per eseguire il codice del progetto Dataform in BigQuery e ricompilare da zero le tabelle incrementali (a meno che non siano contrassegnate come protected), esegui questo comando:

    dataform run --full-refresh

Senza --full-refresh, Dataform aggiorna le tabelle incrementali senza ricompilarle da zero (le tabelle e le visualizzazioni normali vengono sempre ricompilate).

  • Per eseguire un dry run del codice in BigQuery, esegui questo comando:

    dataform run --dry-run

Assistenza

  • Per visualizzare l'elenco di tutti i comandi e le opzioni disponibili, esegui questo comando:

    dataform help

  • Per visualizzare la descrizione di un comando specifico, esegui questo comando:

    dataform help COMMAND

    Sostituisci COMMAND con il comando di cui vuoi saperne di più.

Passaggi successivi