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 flussi di lavoro SQL utilizzando il terminale.

Con l'interfaccia a riga di comando Dataform open source, puoi inizializzare, compilare, testare e eseguire Dataform Core localmente, al di fuori di Google Cloud.

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

Prima di iniziare

Prima di installare Dataform CLI, installa NPM.

Installa l'interfaccia a riga di comando Dataform

  • Per installare Dataform CLI, esegui il seguente comando:

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

Inizializzare un progetto Dataform

  • Per inizializzare un nuovo progetto Dataform, esegui il seguente comando all'interno della directory del progetto:

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Sostituisci quanto segue:

    • PROJECT_NAME: il nome del progetto.
    • DEFAULT_LOCATION: la regione in cui vuoi che Dataform scriva i dati BigQuery. Per ulteriori informazioni sulle regioni BigQuery, consulta Località BigQuery.

Aggiornare il nucleo di Dataform

  • Per aggiornare il framework di base di Dataform, aggiorna il file dataformCoreVersion in workflow_settings.yaml, quindi esegui di nuovo l'installazione NPM:

    npm i

Aggiornare l'interfaccia a riga di comando Dataform

  • Per aggiornare lo strumento CLI Dataform, esegui il seguente comando:

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

Crea un file delle credenziali

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

Per creare il file delle credenziali:

  1. Esegui questo comando:

    dataform init-creds

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

Crea un progetto

Un progetto Dataform vuoto in Dataform Core 3.0.0-beta.0 o versioni successive ha la seguente struttura:

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

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

    dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Sostituisci quanto segue:

    • PROJECT_NAME: il nome del progetto.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: il tuo Google Cloud ID progetto.

Clonare un progetto

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

  • Dopo aver clonato il repository, esegui il seguente comando all'interno della directory del repository clonato:

    dataform install

Definire una tabella

Memorizza le definizioni nella cartella definitions/.

  • Per definire una tabella, esegui il seguente 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 vista nel file SQLX example.

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

Definire un'affermazione manuale

Memorizza le definizioni nella cartella definitions/.

  • Per definire un'affermazione manuale, esegui il seguente comando:

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

    Sostituisci quanto segue:

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

Definisci un'operazione SQL personalizzata

Memorizza le definizioni nella cartella definitions/.

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

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

    Sostituisci quanto segue:

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

Visualizzare l'output della compilazione

Dataform compila il codice in tempo reale.

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

    dataform compile

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

    dataform compile --json

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

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

    Sostituisci quanto segue:

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

Esegui codice

Per eseguire il codice, Dataform accede a BigQuery per determinare il suo stato corrente e personalizzare di conseguenza il codice SQL risultante.

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

    dataform run

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

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

    Sostituisci quanto segue:

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

  • Per eseguire il codice del progetto Dataform in BigQuery e ricostruire tutte le tabelle da zero, esegui il seguente comando:

    dataform run --full-refresh

Senza --full-refresh, Dataform aggiorna le tabelle incrementali senza doverle ricostruire da zero.

  • Per eseguire una simulazione del codice su BigQuery, esegui il seguente comando:

    dataform run --dry-run

Assistenza

  • Per elencare tutti i comandi e le opzioni disponibili, esegui il seguente comando:

    dataform help

  • Per visualizzare una descrizione di un comando specifico, esegui il seguente comando:

    dataform help COMMAND

    Sostituisci COMMAND con il comando che vuoi conoscere.

Passaggi successivi