Utilizzare l'interfaccia a riga di comando Dataform open source

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

Con la CLI Dataform open source, puoi inizializzare, compilare, testare ed 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 una serie di ambienti, ad esempio sviluppo locale o 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 questo comando:

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

Inizializza un progetto Dataform

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

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Sostituisci quanto segue:

    • PROJECT_NAME: il nome del progetto.

    • DEFAULT_LOCATION (facoltativo): la posizione in cui vuoi che Dataform scriva i dati BigQuery. Se non è impostata, Dataform determina la posizione in base ai set di dati a cui fa riferimento la query SQL. Ecco come funziona:

      • Se la query fa riferimento a set di dati della stessa località, Dataform utilizza quella località.
      • Se la query fa riferimento a set di dati di due o più località diverse, si verifica un errore. Per informazioni dettagliate su questa limitazione, vedi Replica dei set di dati tra regioni.
      • Se la query non fa riferimento a nessun set di dati, la località predefinita per Dataform è la multi-regione US. Per scegliere una località diversa, imposta la località predefinita. In alternativa, utilizza la variabile di sistema @@location nella query. Per ulteriori informazioni, consulta Specificare le posizioni.

Aggiorna Dataform Core

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

    npm i

Aggiorna la CLI Dataform

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

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

Crea un file delle credenziali

Dataform richiede un file delle credenziali per connettersi a 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 questo comando:

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

    Sostituisci quanto segue:

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

    • DEFAULT_LOCATION (facoltativo): la località in cui vuoi che Dataform scriva i dati BigQuery. Se non è impostata, Dataform determina la posizione in base ai set di dati a cui fa riferimento la query SQL. Ecco come funziona:

      • Se la query fa riferimento a set di dati della stessa località, Dataform utilizza quella località.
      • Se la query fa riferimento a set di dati di due o più località diverse, si verifica un errore. Per informazioni dettagliate su questa limitazione, vedi Replica dei set di dati tra regioni.
      • Se la query non fa riferimento a nessun set di dati, la località predefinita per Dataform è la multi-regione US. Per scegliere una località diversa, imposta la località predefinita. In alternativa, utilizza la variabile di sistema @@location nella query. Per ulteriori informazioni, consulta Specificare le posizioni.

Clonare un progetto

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

  • Una volta clonato il repository, esegui questo comando all'interno della 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 vista nel file SQLX example.

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

Definisci 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.

Definisci 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: 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 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 le variabili di compilazione personalizzate, esegui questo 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 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 variabile di compilazione personalizzata.
    • SAMPLE_VALUE: il valore della variabile di compilazione personalizzata.

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

    dataform run --full-refresh

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

  • Per eseguire una prova generale del codice in BigQuery, esegui questo comando:

    dataform run --dry-run

Assistenza

  • Per elencare 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 su cui vuoi saperne di più.

Passaggi successivi