Questa pagina mostra come modificare le impostazioni di elaborazione del flusso di lavoro SQL Dataform per un repository specifico.
Ti consigliamo di modificare il file delle impostazioni per rinominare gli schemi o aggiungere variabili di compilazione personalizzate al tuo repository.
Informazioni sulle impostazioni del repository
Ogni repository Dataform contiene un file di impostazioni di flusso di lavoro univoco. Il file contiene l'ID progetto Google Cloud e lo schema in cui Dataform pubblica gli asset in BigQuery. Dataform utilizza impostazioni predefinite che puoi sostituire in base alle tue esigenze modificando il file di impostazioni.
A partire dalla versione Dataform Core 3.0.0,
le impostazioni del flusso di lavoro vengono memorizzate nel file workflow_settings.yaml per impostazione predefinita.
Nelle versioni precedenti di Dataform Core,
le impostazioni del flusso di lavoro sono memorizzate nel file dataform.json
.
Il file workflow_settings.yaml
di Dataform Core 3.0 è compatibile con le versioni precedenti di dataform.json
. Puoi continuare a utilizzare
dataform.json
per memorizzare le impostazioni di flusso di lavoro. Come best practice, devi
eseguire la migrazione delle impostazioni del flusso di lavoro del repository
al formato workflow_settings.yaml
per la compatibilità futura.
Informazioni su workflow_settings.yaml
Il file workflow_settings.yaml
, introdotto in
Dataform Core 3.0,
memorizza 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 BigQuery.defaultDataset
: il set di dati BigQuery in cui Dataform crea gli asset, chiamatodataform
per impostazione predefinita.defaultLocation
: la regione del set di dati BigQuery predefinito. Per ulteriori informazioni sulle posizioni dei set di dati BigQuery, consulta Località dei set di dati. In questa posizione, Dataform elabora il codice e archivia i dati eseguiti. Questa regione di elaborazione deve corrispondere alla posizione degli set di dati BigQuery, ma non deve corrispondere alla regione del repository Dataform.defaultAssertionDataset
: il set di dati BigQuery in cui Dataform crea viste con i risultati delle asserzioni, chiamatodataform_assertions
per impostazione predefinita.
Per maggiori informazioni sulle proprietà workflow_settings.yaml
, consulta la pagina relativa al riferimento alle configurazioni per le impostazioni di flusso di lavoro su GitHub.
Puoi accedere alle proprietà definite in workflow_settings.yaml
nel codice Dataform come proprietà dell'oggetto dataform.projectConfig
.
Si applicano le seguenti mappature dalle opzioni workflow_settings.yaml
alle opzioni dataform.projectConfig
accessibili per il codice:
defaultProject
=>defaultDatabase
.defaultDataset
=>defaultSchema
.defaultAssertionDataset
=>assertionSchema
.projectSuffix
=>databaseSuffix
.datasetSuffix
=>schemaSuffix
.namePrefix
=>tablePrefix
.
Il seguente esempio di codice mostra l'oggetto dataform.projectConfig
a cui viene fatto riferimento
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
memorizza 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 BigQuery.defaultSchema
: il set di dati BigQuery in cui Dataform crea gli asset.defaultLocation
: la regione del set di dati BigQuery predefinito. Per ulteriori informazioni sulle località dei set di dati BigQuery, consulta Località dei set di dati. In questa posizione, Dataform elabora il codice e archivia i dati eseguiti. Questa regione di elaborazione deve corrispondere alla località degli set di dati BigQuery, ma non deve corrispondere alla regione del repository Dataform.assertionSchema
: il set di dati BigQuery in cui Dataform crea viste con i risultati delle asserzioni, chiamatodataform_assertions
per impostazione predefinita.
Puoi accedere alle proprietà definite in dataform.json
nel codice del progetto come proprietà dell'oggetto dataform.projectConfig
.
Prima di iniziare
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per configurare le impostazioni di Dataform,
chiedi all'amministratore di concederti il ruolo IAM Amministratore Dataform (roles/dataform.admin
) nei repository.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Configura i nomi degli schemi
Per configurare i nomi degli schemi, devi modificare le proprietà defaultDataset
e
defaultAssertionSchema
nel
file workflow_settings.yaml
o le proprietà defaultSchema
e assertionSchema
nel file dataform.json
.
Per configurare il nome di uno schema:
workflow_settings.yaml
Nella tua area di lavoro di sviluppo, fai clic sul file
workflow_settings.yaml
nel riquadro File.Modifica il valore di
defaultDataset
,defaultAssertionSchema
o di entrambi.
Il seguente esempio di codice mostra un nome defaultDataset
personalizzato definito nel
file workflow_settings.yaml
:
...
defaultDataset: mytables
...
dataform.json
Nella tua area di lavoro di sviluppo, fai clic sul file
dataform.json
nel riquadro File.Modifica il valore di
defaultSchema
,assertionSchema
o di 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 puoi modificare con le override di compilazione in una configurazione di release o in una richiesta dell'API Dataform.
Dopo aver definito una variabile di compilazione in workflow_settings.yaml
e averla aggiunta alle tabelle selezionate, puoi modificarne il valore in una configurazione di release o nelle sostituzione della compilazione dell'API Dataform per eseguire le tabelle in modo condizionale.
Per ulteriori informazioni sull'esecuzione condizionale delle tabelle mediante variabili di compilazione, consulta Introduzione al ciclo di vita del codice in Dataform.
Per creare una variabile di compilazione che puoi utilizzare in un repository:
workflow_settings.yaml
- Vai alla tua area di lavoro di sviluppo Dataform.
- Nel riquadro File, seleziona il file
workflow_settings.yaml
. 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 la variabile di compilazione myVariableName
impostata su myVariableValue
nel file workflow_settings.yaml
:
...
vars:
myVariableName: myVariableValue
...
Il seguente esempio di codice mostra il file workflow_settings.yaml
con la variabile di compilazione executionSetting
impostata su dev
:
defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev
dataform.json
- Vai alla tua area di lavoro di sviluppo Dataform.
- Nel riquadro File, seleziona il file
dataform.json
. 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 la variabile di compilazione myVariableName
impostata su myVariableValue
nel file dataform.json
:
{
...
"vars": {
"myVariableName": "myVariableValue"
},
...
}
Il seguente esempio di codice mostra il file dataform.json
con la 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 della tabella SQLX:
- Vai alla tua area di lavoro di sviluppo Dataform.
- Nel riquadro File, seleziona un file di definizione della tabella SQLX.
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.
- YOUR_VARIABLE con il nome della variabile,
ad esempio
Il seguente esempio di codice mostra un file SQLX di definizione della tabella con una clausola when
e la variabile executionSetting
che esegue il 10% dei dati nell'impostazione di esecuzione di staging:
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 una clausola 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 in workflow_settings.yaml
Per assicurarti che il file delle impostazioni di flusso di lavoro sia compatibile con le versioni future del framework di Dataform, devi eseguire la migrazione delle impostazioni di flusso di lavoro 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
sostituisce anche il file package.json
.
Per maggiori informazioni sulla sostituzione di package.json
con
workflow_settings.yaml
, consulta
Gestire il pacchetto principale di Dataform.
La tabella seguente mostra la mappatura delle proprietà delle impostazioni di flusso di lavoro 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 predefinito del progetto Google Cloud. |
defaultLocation |
defaultLocation |
Obbligatorio. La posizione BigQuery predefinita in cui Dataform creerà le tabelle. Per ulteriori informazioni sulle località di BigQuery, consulta Località dei set di dati. |
defaultSchema |
defaultDataset |
Obbligatorio. Il set di dati predefinito. |
databaseSuffix |
projectSuffix |
Facoltativo. Il suffisso da aggiungere a tutti i riferimenti ai progetti 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 rese disponibili al codice del progetto durante la compilazione. Un oggetto contenente un elenco di coppie key: value . |
warehouse |
- | Obbligatorio in dataform.json . Deve essere impostato su bigquery . Non disponibile in workflow_settings.yaml . |
- | dataformCoreVersion |
Non disponibile in dataform.json . Installato in workflow_settings.yaml per impostazione predefinita per i nuovi repository. Per saperne di più, consulta Gestire il pacchetto principale di Dataform. |
Per eseguire la migrazione delle impostazioni di flusso di lavoro in workflow_settings.yaml
:
Nella console Google Cloud, vai alla pagina Dataform.
Seleziona un repository e poi uno spazio di lavoro.
Nel riquadro File, fai clic su AggiungiAggiungi, quindi su Crea file.
Nel campo Aggiungi un percorso del file, inserisci
workflow_settings.yaml
.Fai clic su Crea file.
Nel file
workflow_settings.yaml
, aggiungi le impostazioni del filedataform.json
, mappate al formato YAML.Nel riquadro File, fai clic sul menu Altro accanto a
dataform.json
, quindi su Elimina.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
Per scoprire di più sulla migrazione del pacchetto principale di Dataform a
workflow_settings.yaml
, consulta Gestire il pacchetto principale di Dataform.Per scoprire di più sulle impostazioni del progetto Dataform, consulta la guida di riferimento di
IProjectConfig
.