Configura le impostazioni del flusso di lavoro Dataform

Questa pagina mostra come modificare l'elaborazione del flusso di lavoro SQL di Dataform le impostazioni per un repository specifico.

Potrebbe essere opportuno modificare il file delle impostazioni per rinominare gli schemi o aggiungere di compilation al tuo repository.

Informazioni sulle impostazioni del repository

Ogni repository Dataform contiene un flusso di lavoro univoco del file di impostazioni. Il file contiene l'ID progetto Google Cloud e lo schema in quali Dataform pubblica gli asset in BigQuery. Dataform utilizza le impostazioni predefinite che puoi sostituire per soddisfare al meglio necessarie modificando il file delle impostazioni.

A partire da Dataform core 3.0.0, le impostazioni del flusso di lavoro sono archiviate nel file workflow_settings.yaml per impostazione predefinita. Nelle versioni precedenti del core Dataform, le impostazioni del flusso di lavoro sono archiviate nel file dataform.json. Il file Dataform Core 3.0 workflow_settings.yaml è compatibile con le versioni precedenti di dataform.json. Puoi continuare a utilizzare dataform.json per archiviare le impostazioni del flusso di lavoro. Come best practice, dovresti eseguire la migrazione delle impostazioni del flusso di lavoro del repository al formato workflow_settings.yaml per una compatibilità futura.

Informazioni su workflow_settings.yaml

Il file workflow_settings.yaml, introdotto in Dataform core 3.0, archivia le impostazioni del flusso di lavoro Dataform nel formato YAML.

Il seguente esempio di codice mostra un file workflow_settings.yaml di esempio:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

Nell'esempio di codice precedente, le coppie chiave-valore sono descritte come segue:

  • defaultProject: l'ID del tuo progetto Google Cloud di BigQuery.
  • defaultDataset: il set di dati BigQuery in cui Dataform crea asset, chiamati dataform per impostazione predefinita.
  • defaultLocation: la regione predefinita del set di dati BigQuery. Per ulteriori informazioni sulle posizioni dei set di dati BigQuery, consulta Località dei set di dati In questa posizione, Dataform elabora il tuo codice e archivia eseguito i dati. Questa regione di elaborazione deve corrispondere alla località dei set di dati BigQuery, ma non deve corrispondere la regione del repository Dataform.
  • defaultAssertionDataset: il set di dati BigQuery in cui Dataform crea viste con risultati delle asserzioni, chiamati dataform_assertions per impostazione predefinita.

Per ulteriori informazioni sulle proprietà workflow_settings.yaml, consulta riferimento alle configurazioni del flusso di lavoro in GitHub.

Puoi accedere alle proprietà definite in workflow_settings.yaml nel tuo il codice Dataform come proprietà dataform.projectConfig .

Le seguenti mappature dalle opzioni workflow_settings.yaml al codice accessibile Si applicano dataform.projectConfig opzioni:

  • defaultProject => defaultDatabase.
  • defaultDataset => defaultSchema.
  • defaultAssertionDataset => assertionSchema.
  • projectSuffix => databaseSuffix.
  • datasetSuffix => schemaSuffix.
  • namePrefix => tablePrefix.

Il seguente esempio di codice mostra l'oggetto dataform.projectConfig chiamato in un Istruzione SELECT in una vista:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

Informazioni su dataform.json

Il file dataform.json archivia le impostazioni del flusso di lavoro Dataform nel formato JSON.

Il seguente esempio di codice mostra un file dataform.json di esempio:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

Nell'esempio di codice precedente, le coppie chiave-valore sono descritte come segue:

  • warehouse: puntatore a BigQuery, dove Dataform crea gli asset.
  • defaultDatabase: l'ID del tuo progetto Google Cloud di BigQuery.
  • defaultSchema: il set di dati BigQuery in cui Dataform crea gli asset.
  • defaultLocation: la regione predefinita del set di dati BigQuery. Per ulteriori informazioni sulle posizioni dei set di dati BigQuery, consulta Località dei set di dati. In questa posizione, Dataform elabora il tuo codice e archivia eseguito i dati. Questa regione di elaborazione deve corrispondere alla località dei set di dati BigQuery, ma non deve corrispondere la regione del repository Dataform.
  • assertionSchema: il set di dati BigQuery in cui Dataform crea viste con risultati delle asserzioni, chiamati dataform_assertions per impostazione predefinita.

Puoi accedere alle proprietà definite in dataform.json nel codice del progetto come proprietà di dataform.projectConfig .

Prima di iniziare

  1. Crea un repository.

  2. Crea e inizializza un'area di lavoro di sviluppo nel tuo repository.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare le impostazioni di Dataform, chiedi all'amministratore di concederti Ruolo IAM Amministratore Dataform (roles/dataform.admin) nei repository. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite la ruoli o altri ruoli predefiniti ruoli.

Configura i nomi degli schemi

Per configurare i nomi degli schemi, devi modificare i campi defaultDataset e defaultAssertionSchema proprietà in il file workflow_settings.yaml o defaultSchema e assertionSchema nel file dataform.json.

Per configurare il nome di uno schema:

workflow_settings.yaml

  1. Nell'area di lavoro di sviluppo, nel riquadro File, fai clic su il file workflow_settings.yaml.

  2. Modifica il valore di defaultDataset, defaultAssertionSchema o entrambi.

Il seguente esempio di codice mostra un nome defaultDataset personalizzato definito in il file workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

  1. Nell'area di lavoro di sviluppo, nel riquadro File, fai clic su il file dataform.json.

  2. Modifica il valore di defaultSchema, assertionSchema o entrambi.

Il seguente esempio di codice mostra un nome defaultSchema personalizzato definito nel dataform.json file:

{
  ...
  "defaultSchema": "mytables",
  ...
}

Creare variabili di compilazione personalizzate

Le variabili di compilazione contengono valori che è possibile modificare con la compilazione in una configurazione di release o in una richiesta API Dataform.

Dopo aver definito una variabile di compilazione in workflow_settings.yaml e averla aggiunta a tabelle selezionate, puoi modificarne il valore in una configurazione di release Override delle compilazioni dell'API Dataform di eseguire le tabelle in modo condizionale.

Per saperne di più sull'esecuzione delle tabelle in modo condizionale tramite variabili di compilazione, consulta Introduzione al ciclo di vita del codice in Dataform.

Per creare una variabile di compilazione da utilizzare in un repository, segui questi passaggi:

workflow_settings.yaml

  1. Vai all'area di lavoro di sviluppo di Dataform.
  2. Nel riquadro File, seleziona il file workflow_settings.yaml.

  3. Inserisci il seguente snippet di codice:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Sostituisci quanto segue:

    • YOUR_VARIABLE con un nome per la variabile.
    • VALUE con il valore predefinito della variabile di compilazione.

Il seguente esempio di codice mostra il set di variabili di compilazione myVariableName a myVariableValue nel file workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

Il seguente esempio di codice mostra il file workflow_settings.yaml con Variabile di compilazione executionSetting impostata su dev:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

  1. Vai all'area di lavoro di sviluppo di Dataform.
  2. Nel riquadro File, seleziona il file dataform.json.

  3. Inserisci il seguente snippet di codice:

    "vars": {
  "YOUR_VARIABLE":"VALUE"
}

    Sostituisci quanto segue:

    • YOUR_VARIABLE con un nome per la variabile.
    • VALUE con il valore predefinito della variabile di compilazione.

Il seguente esempio di codice mostra il set di variabili di compilazione myVariableName a myVariableValue nel file dataform.json:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

Il seguente esempio di codice mostra il file dataform.json con Variabile di compilazione executionSetting impostata su dev:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

Aggiungere una variabile di compilazione a una tabella

Per aggiungere una variabile di compilazione a un file di definizione di una tabella SQLX, segui questi passaggi:

  1. Vai all'area di lavoro di sviluppo di Dataform.
  2. Nel riquadro File, seleziona un file di definizione di tabella SQLX.

  3. Nel file, inserisci una clausola when nel seguente formato:

    ${when(dataform.projectConfig.vars.YOUR_VARIABLE === "SET_VALUE", "CONDITION")}

    Sostituisci quanto segue:

    • YOUR_VARIABLE con il nome della variabile, ad esempio executionSetting.
    • SET_VALUE con un valore per la variabile, ad esempio staging.
    • CONDITION con una condizione per l'esecuzione della tabella.

Il seguente esempio di codice mostra un file SQLX di definizione di tabella con un when e la variabile executionSetting che esegue il 10% dei dati nella impostazione di esecuzione temporanea:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

Il seguente esempio di codice mostra un file SQLX di definizione della vista con un when e la variabile myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

Esegui la migrazione delle impostazioni del flusso di lavoro a workflow_settings.yaml

Per garantire che il file delle impostazioni del flusso di lavoro sia compatibile con le Versioni del framework di base Dataform, devi eseguire la migrazione del flusso di lavoro impostazioni dal file dataform.json al file workflow_settings.yaml.

Il file workflow_settings.yaml sostituisce il file dataform.json.

Se Dataform core è l'unico pacchetto di dipendenze nel tuo repository, il file workflow_settings.yaml sostituirà anche il file package.json. Per ulteriori informazioni sulla sostituzione di package.json con workflow_settings.yaml, vedi Gestire il pacchetto principale Dataform.

La tabella seguente mostra la mappatura delle proprietà delle impostazioni del flusso di lavoro da Da dataform.json a workflow_settings.yaml:

Proprietà a dataform.json Proprietà a workflow_settings.yaml Descrizione
assertionSchema defaultAssertionDataset Obbligatorio. Il set di dati predefinito per le asserzioni.
defaultDatabase defaultProject Obbligatorio. Il nome del progetto Google Cloud predefinito.
defaultLocation defaultLocation Obbligatorio. La località BigQuery predefinita in cui Dataform creerà tabelle. Per saperne di più sulle località BigQuery, vedi Località dei set di dati.
defaultSchema defaultDataset Obbligatorio. Il set di dati predefinito.
databaseSuffix projectSuffix Facoltativo. Il suffisso da aggiungere a tutti i riferimenti del progetto Google Cloud.
schemaSuffix datasetSuffix Facoltativo. Il suffisso da aggiungere a tutti i set di dati delle azioni.
tablePrefix namePrefix Facoltativo. Il prefisso da anteporre a tutti i nomi delle azioni.
vars vars Facoltativo. Variabili definite dall'utente che vengono rese disponibili per il codice di progetto durante la compilazione. Un oggetto contenente un elenco di key: value coppie.
warehouse - Obbligatorio in dataform.json. Deve essere impostato su bigquery. Non disponibile nel seguente paese: workflow_settings.yaml.
- dataformCoreVersion Non disponibile nel seguente paese: dataform.json. Istituito in workflow_settings.yaml per impostazione predefinita per i nuovi repository. Per saperne di più, vedi Gestire il pacchetto principale Dataform.

Per eseguire la migrazione delle impostazioni del flusso di lavoro a workflow_settings.yaml, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Dataform.

    Vai alla pagina Dataform

  2. Seleziona un repository, quindi seleziona un'area di lavoro.

  3. Nel riquadro File, fai clic su addAdd, e fai clic su Crea file.

  4. Nel campo Aggiungi un percorso file, inserisci workflow_settings.yaml.

  5. Fai clic su Crea file.

  6. Nel file workflow_settings.yaml, aggiungi le impostazioni dal tuo dataform.json, mappato al formato YAML.

  7. Nel riquadro File, fai clic sul menu Altro accanto a dataform.json, e fai clic su Elimina.

  8. Per confermare l'eliminazione di dataform.json, fai clic su Elimina.

Il seguente esempio di codice mostra le impostazioni del flusso di lavoro definite in un file dataform.json:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

Il seguente esempio di codice mostra il file dataform.json precedente convertito in workflow_settings.yaml:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

Passaggi successivi