Utilizza l'interfaccia a riga di comando open source Dataform

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

Grazie all'interfaccia a riga di comando open source Dataform, puoi inizializzare, compilare, testare ed eseguire Dataform core in locale al di fuori di Google Cloud.

Dataform distribuisce un'immagine Docker che puoi utilizzare per eseguire l'equivalente dei comandi dell'interfaccia a riga di comando di Dataform.

L'interfaccia a riga di comando Dataform supporta Credenziali predefinite dell'applicazione (ADC). Con ADC, puoi rendere disponibili le credenziali per la tua applicazione in una varietà di ambienti, ad esempio sviluppo o produzione locale, senza dover modificare il codice dell'applicazione. Per utilizzare ADC, devi prima fornire le credenziali ad ADC.

Prima di iniziare

Prima di installare l'interfaccia a riga di comando Dataform, installa NPM.

Installa l'interfaccia a riga di comando Dataform

  • Per installare l'interfaccia a riga di comando Dataform, esegui questo comando:

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

Inizializzare un progetto Dataform

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

    dataform init

Aggiorna Dataform

  • Per aggiornare il framework Dataform, aggiorna dataformCoreVersion nel file workflow_settings.yaml, quindi esegui di nuovo l'installazione di Gestione dei partner di rete:

    npm i

Aggiorna interfaccia a riga di comando Dataform

  • Per aggiornare lo strumento di interfaccia a riga di comando 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 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 di init-creds che illustra come creare i file delle credenziali.

Crea un progetto

Un progetto Dataform vuoto 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-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Sostituisci PROJECT_NAME con il nome del progetto e YOUR_GOOGLE_CLOUD_PROJECT_ID con l'ID progetto Google Cloud.

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 questo comando nella directory del repository clonato:

    dataform install

Definisci 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 con il tipo di tabella: table, incremental o view.
    • SELECT_STATEMENT con un'istruzione SELECT che definisce la tabella.
    • FILE con 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 con un'istruzione SELECT che definisce l'asserzione.
    • FILE con il nome del file di definizione delle operazioni SQL personalizzato.

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 con la tua operazione SQL personalizzata.
    • FILE con il nome del file di definizione delle operazioni SQL personalizzato.

Visualizza output compilazione

Dataform compila il tuo 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 con la tua variabile di compilazione personalizzata.
    • SAMPLE_VALUE con il valore della variabile di compilazione personalizzata.

Esegui codice

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

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

    dataform run

  • Per eseguire il codice del tuo 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 con la tua variabile di compilazione personalizzata.
    • SAMPLE_VALUE con il valore della variabile di compilazione personalizzata.

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

    dataform run --full-refresh

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

  • Per visualizzare il codice SQL compilato finale personalizzato in base allo stato attuale di BigQuery, senza eseguirlo in BigQuery, esegui questo comando:

    dataform run --dry-run

Ricevere 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 che vuoi approfondire.

Passaggi successivi