Gestire un repository

Questo documento mostra come eseguire le seguenti operazioni in Dataform:

• Configura le impostazioni del workflow Dataform.
• Gestisci il pacchetto Dataform core.
• Controllo della versione del codice.

Prima di iniziare

1. Seleziona o crea un repository.

   Nota: l'elenco dei repository Dataform include solo i repository creati per lo sviluppo del flusso di lavoro Dataform. I repository per gli asset di BigQuery Studio, come i notebook o le query salvate, vengono gestiti separatamente e non vengono visualizzati in questo elenco.

2. (Facoltativo) Connetti il tuo repository a un repository Git di terze parti.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività descritte in questo documento, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Configura le impostazioni di Dataform e gestisci la posizione del pacchetto Dataform core: Amministratore Dataform (roles/dataform.admin) sui repository.
• Aggiorna il pacchetto principale di Dataform e utilizza il controllo della versione in Dataform: Dataform Editor (roles/dataform.editor) nei workspace.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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

Configura le impostazioni del workflow Dataform

Questa sezione mostra come modificare le impostazioni di elaborazione del flusso di lavoro Dataform per un repository specifico.

Potresti voler modificare il file delle impostazioni per rinominare gli schemi o aggiungere variabili di compilazione personalizzate al tuo repository.

Informazioni sulle impostazioni del repository

Per tutti i repository, è richiesto un account di servizio personalizzato per l'esecuzione del workflow e viene applicata la modalità act-as rigorosa. Non puoi utilizzare il service agent Dataform predefinito per eseguire i workflow.

Ogni repository Dataform contiene un file di impostazioni del workflow 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 ignorare per adattarle al meglio alle tue esigenze modificando il file delle impostazioni.

A partire da Dataform Core 3.0.0, le impostazioni del workflow vengono archiviate per impostazione predefinita nel file workflow_settings.yaml. Nelle versioni precedenti di Dataform Core, le impostazioni del workflow sono archiviate nel file dataform.json. Entrambi i file di configurazione devono trovarsi nella directory principale del repository. Il file workflow_settings.yaml di Dataform core 3.0 è compatibile con le versioni precedenti del file dataform.json. Puoi continuare a utilizzare il file dataform.json per archiviare le impostazioni del workflow. Come best practice, devi eseguire la migrazione delle impostazioni del workflow 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 workflow di 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
  dataformCoreVersion: 3.0.62
  preserveGovernanceControls: true

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

• defaultProject: l'ID progetto Google Cloud BigQuery.
• defaultDataset: il set di dati BigQuery in cui Dataform crea gli asset, denominato dataform per impostazione predefinita.

• defaultLocation (facoltativo): la località del set di dati BigQuery predefinito. Dataform utilizza questa località per elaborare il codice e archiviare i risultati. Questa località di elaborazione deve corrispondere a quella dei tuoi set di dati BigQuery. Tuttavia, non deve corrispondere alla posizione del repository Dataform.

  Se non imposti il parametro defaultLocation, Dataform determina la località 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 ad alcun 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 saperne di più, vedi Specificare le località.

• defaultAssertionDataset: il set di dati BigQuery in cui Dataform crea viste con i risultati delle asserzioni, chiamate dataform_assertions per impostazione predefinita.

• dataformCoreVersion: la versione del pacchetto Dataform core installato nel repository. Per saperne di più, consulta Gestisci il pacchetto Dataform Core.

• preserveGovernanceControls (facoltativo): un valore booleano che specifica se Dataform conserva automaticamente le policy dei dati e i tag di governance dei dati di BigQuery esistenti (anteprima) durante la ricreazione delle tabelle nelle esecuzioni del workflow. Per saperne di più, consulta Conserva i metadati dei controlli di accesso.

Per maggiori informazioni sulle proprietà workflow_settings.yaml, consulta WorkflowSettings su GitHub.

Puoi accedere alle proprietà definite in workflow_settings.yaml nel codice Dataform come proprietà dell'oggetto dataform.projectConfig.

Si applicano i seguenti mapping dalle opzioni workflow_settings.yaml alle opzioni accessibili tramite codice dataform.projectConfig:

• 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 workflow di 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: un puntatore a BigQuery, dove Dataform crea gli asset.
• defaultDatabase: l'ID progetto BigQuery Google Cloud .
• defaultSchema: il set di dati BigQuery in cui Dataform crea gli asset.

• defaultLocation (facoltativo): la località del set di dati BigQuery predefinito. Dataform utilizza questa località per elaborare il codice e archiviare i risultati. Questa località di elaborazione deve corrispondere a quella dei tuoi set di dati BigQuery. Tuttavia, non deve corrispondere alla posizione del repository Dataform.

  Se non imposti il parametro defaultLocation, Dataform determina la località 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 provenienti da 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 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 saperne di più, consulta Specifica le località.

• assertionSchema: il set di dati BigQuery in cui Dataform crea viste con i risultati delle asserzioni, chiamato dataform_assertions per impostazione predefinita.

Puoi accedere alle proprietà definite nel file dataform.json nel codice del progetto come proprietà dell'oggetto dataform.projectConfig.

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, segui questi passaggi:

workflow_settings.yaml

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

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

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

  ...
  defaultDataset: mytables
  ...

dataform.json

1. Nella tua area di lavoro di sviluppo, nel riquadro File, fai clic sul file dataform.json.

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

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

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

Crea variabili di compilazione personalizzate

Le variabili di compilazione contengono valori che puoi modificare con gli override di compilazione in una configurazione della release o in una richiesta 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 rilascio o override della compilazione dell'API Dataform per eseguire le tabelle in modo condizionale.

Per saperne di più sull'esecuzione condizionale delle tabelle utilizzando le 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, segui questi passaggi:

workflow_settings.yaml

1. Vai al tuo workspace di sviluppo Dataform.
2. Nel riquadro File, seleziona il file workflow_settings.yaml.

3. Inserisci il seguente snippet di codice:

   "vars": {
     "VARIABLE":"VALUE"
   }
   

   Sostituisci quanto segue:

   • VARIABLE: un nome per la variabile
   • VALUE: 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

1. Vai al tuo workspace di sviluppo Dataform.
2. Nel riquadro File, seleziona il file dataform.json.

3. Inserisci il seguente snippet di codice:

   "vars": {
     "VARIABLE":"VALUE"
   }
   

   Sostituisci quanto segue:

   • VARIABLE: un nome per la variabile
   • VALUE: 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"
}
}

Aggiungi una variabile di compilazione a una tabella

Per aggiungere una variabile di compilazione a un file di definizione della tabella SQLX:

1. Vai al tuo workspace di sviluppo Dataform.
2. Nel riquadro File, seleziona un file di definizione della tabella SQLX.

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

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

   Sostituisci quanto segue:

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

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 della gestione 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 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!"
  )}

Configura i valori predefiniti a livello di workflow per le tabelle Iceberg

Puoi fornire valori predefiniti a livello di workflow per le tabelle gestite di Apache Iceberg nel file workflow_settings.yaml. Puoi impostare i valori predefiniti per il nome del bucket, la radice della cartella della tabella e il percorso secondario della cartella della tabella.

Dataform utilizza questi valori predefiniti per creare l'URI di archiviazione per una tabella gestita Iceberg se non imposti questi valori nel blocco config del file di definizione della tabella.

Per configurare i valori predefiniti a livello di workflow per le tabelle, aggiungi il blocco defaultIcebergConfig con i seguenti campi al file workflow_settings.yaml:

• bucketName: (Facoltativo) Il nome predefinito del bucket Cloud Storage.
• tableFolderRoot: (Facoltativo) Il nome predefinito della cartella di primo livello all'interno del bucket Cloud Storage.
• tableFolderSubpath: (Facoltativo) Il nome predefinito di una sottocartella all'interno di tableFolderRoot.

Il seguente esempio di codice mostra un file workflow_settings.yaml con valori predefiniti a livello di flusso di lavoro per le tabelle gestite Iceberg:

defaultProject: "defaultProject"
defaultDataset: "defaultDataset"
defaultLocation: "us-central1"
defaultIcebergConfig:
  bucketName: "wsDefaultBucketName"
  tableFolderRoot: "wsDefaultTableFolderRoot"
  tableFolderSubpath: "wsDefaultTableFolderSubpath"

Puoi accedere a questi campi nel codice Dataform come proprietà dell'oggetto ProjectConfig:

dataform.ProjectConfig.defaultIcebergConfig.bucketName
dataform.ProjectConfig.defaultIcebergConfig.tableFolderRoot
dataform.ProjectConfig.defaultIcebergConfig.tableFolderSubpath

Per saperne di più, consulta Creare tabelle gestite Apache Iceberg e le proprietà del blocco iceberg.

Esegui la migrazione delle impostazioni del workflow a workflow_settings.yaml

Per garantire che il file delle impostazioni del workflow sia compatibile con le versioni future del framework Dataform Core, devi eseguire la migrazione delle impostazioni del workflow 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 repository, anche il file workflow_settings.yaml sostituisce il file package.json. Per saperne di più sulla sostituzione del file package.json con il file workflow_settings.yaml, consulta Gestisci il pacchetto Dataform Core.

La tabella seguente mostra il mapping delle proprietà delle impostazioni del flusso di lavoro dal file dataform.json al file workflow_settings.yaml:

Proprietà in dataform.json	Proprietà in 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	Facoltativo. La località BigQuery predefinita in cui Dataform crea le tabelle. Se non viene impostata, Dataform determina la località in base ai set di dati a cui fa riferimento la query SQL. Per saperne di più, consulta Specifica le località.
defaultSchema	defaultDataset	Obbligatorio. Il set di dati predefinito.
databaseSuffix	projectSuffix	Facoltativo. Il suffisso da aggiungere a tutti i riferimenti Google Cloud del progetto.
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 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 del flusso di lavoro a workflow_settings.yaml:

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

   Vai a Dataform

2. Seleziona un repository, quindi un workspace.

3. Nel riquadro File, fai clic su addAggiungi, quindi su Crea file.

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

5. Fai clic su Crea file.

6. Nel file workflow_settings.yaml, aggiungi le impostazioni del file dataform.json, mappate al formato YAML.

7. Nel riquadro File, fai clic sul menu Altro accanto a dataform.json, quindi 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"

Gestire il pacchetto principale Dataform

Questa sezione mostra come gestire il pacchetto di dipendenze del framework Dataform core e aggiornarlo all'ultima versione.

Dataform Core è il framework Dataform open source per lo sviluppo di workflow con SQL, SQLX e JavaScript. Come best practice, utilizza sempre l'ultima versione disponibile del framework Dataform Core. Per informazioni sulle release del framework Dataform core, consulta la pagina Release di Dataform su GitHub.

Gestisci la posizione del pacchetto principale Dataform

Quando inizializzi il primo workspace in un repository, Dataform imposta automaticamente Dataform Core come pacchetto di dipendenze. A partire da Dataform core 3.0.0, Dataform installa il pacchetto Dataform core nel file workflow_settings.yaml per impostazione predefinita. Nelle versioni precedenti di Dataform Core, Dataform Core era impostato nel file package.json.

In Dataform core 3.0.0 e versioni successive, se Dataform core è l'unico pacchetto nel tuo repository, devi impostarlo nel file workflow_settings.yaml. Per i repository creati con versioni precedenti di Dataform Core, sposta il pacchetto Dataform Core in workflow_settings.yaml.

Il file package.json è necessario per installare pacchetti aggiuntivi in Dataform. Se il tuo repository utilizza pacchetti aggiuntivi, imposta il pacchetto Dataform core in package.json in modo che tutti i pacchetti siano impostati in un unico posto. Se il repository non ha il file package.json, crea il file package.json e sposta il pacchetto principale Dataform per installare pacchetti aggiuntivi. Il file package.json deve trovarsi nella directory root del repository.

Sposta Dataform Core in workflow_settings.yaml

Per i repository creati con versioni di Dataform core precedenti alla 3.0.0, se non hai pacchetti di dipendenze diversi da Dataform core, devi spostare il pacchetto Dataform core dal file package.json al file workflow_settings.yaml ed eliminare il file package.json ridondante.

Per eseguire la migrazione del pacchetto Dataform Core dal file package.json al file workflow_settings.yaml, segui questi passaggi:

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

   Vai a Dataform

2. Seleziona un repository, quindi un workspace.

3. Nel riquadro File, seleziona il file workflow_settings.yaml.

4. Nel file workflow_settings.yaml, aggiungi il pacchetto principale di Dataform nel seguente formato:

   dataformCoreVersion: "VERSION"
   
   

   Sostituisci VERSION con l'ultima versione di Dataform, ad esempio 3.0.0.

5. Nel riquadro File, fai clic sul menu Altro accanto al file package.json e poi su Elimina.

6. Per confermare l'eliminazione del file dataform.json, fai clic su Elimina.

7. Fai clic su Installa pacchetti.

Sposta Dataform Core in package.json

Il file package.json è necessario per installare pacchetti aggiuntivi in un repository. Se il tuo repository utilizza pacchetti aggiuntivi, devi archiviare tutti i pacchetti, incluso il pacchetto Dataform core, nel file package.json.

Se il tuo repository non contiene il file package.json perché il pacchetto Dataform core è impostato nel file workflow_settings.yaml, devi creare il file package.json per installare pacchetti aggiuntivi, quindi spostare il pacchetto Dataform core dal file workflow_settings.yaml al file package.json appena creato.

Per creare il file package.json e spostare il pacchetto Dataform Core, segui questi passaggi:

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

   Vai a Dataform

2. Seleziona un repository, quindi un workspace.

3. Nel riquadro File, fai clic su AggiungiAggiungi, poi su Crea file.

4. Nel campo Aggiungi un percorso del file, inserisci package.json.

5. Fai clic su Crea file.

6. Nel file package.json, aggiungi il pacchetto principale di Dataform nel seguente formato:

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   Sostituisci VERSION con l'ultima versione di Dataform, ad esempio 3.0.0.

7. Fai clic su Installa pacchetti.

8. Nel riquadro File, seleziona workflow_settings.yaml.

9. Nel file workflow_settings.yaml, elimina la proprietà dataformCoreVersion.

Aggiorna Dataform Core

Testa sempre le nuove versioni dei pacchetti in un ambiente non di produzione prima di eseguirne il deployment nell'ambiente di produzione.

Per aggiornare il pacchetto di dipendenze principali di Dataform:

1. Cerca l'ultima versione di @dataform/core nella pagina delle release di Dataform su GitHub.

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

   Vai a Dataform

3. Seleziona un repository, poi un workspace.

4. Nel riquadro File, seleziona il file package.json o il file workflow_settings.yaml.

   La posizione in cui è impostato il pacchetto di dipendenze di Dataform Core dipende dalla versione di Dataform Core e dall'utilizzo dei pacchetti. Per saperne di più, vedi Gestire la posizione del pacchetto principale di Dataform.

5. Aggiorna il pacchetto di dipendenze principali di Dataform con l'ultima versione:

   package.json

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   Sostituisci VERSION con l'ultima versione di Dataform, ad esempio 3.0.0. Per evitare problemi con l'installazione del pacchetto, specifica esplicitamente la versione del pacchetto Dataform core. Non utilizzare altre opzioni dependencies del file package.json, ad esempio >version.

   workflow_settings.yaml

   dataformCoreVersion: "VERSION"
   

   Sostituisci VERSION con l'ultima versione di Dataform, ad esempio 3.0.0.

6. Fai clic su Installa pacchetti.

7. Esegui il commit delle modifiche.

8. Esegui il push delle modifiche nel repository.

Il seguente esempio di codice mostra la dipendenza @dataform/core aggiornata alla versione 3.0.0 nel file package.json:

{
    "dependencies": {
        "@dataform/core": "3.0.0"
    }
}

Controllo della versione del codice

Questa sezione mostra come utilizzare il controllo della versione in Dataform per tenere traccia dello sviluppo.

Dataform utilizza Git per tenere traccia di ogni modifica apportata ai file all'interno di un repository.

In un repository Dataform, interagisci direttamente con il repository Git.

In un repository connesso, interagisci con il branch di monitoraggio del repository remoto che hai configurato durante la connessione del repository.

Dataform visualizza le opzioni di controllo della versione in base allo stato delle modifiche nell'area di lavoro di sviluppo. Ad esempio, Dataform visualizza l'opzione di commit solo quando nel workspace sono presenti modifiche locali di cui non è stato eseguito il commit. Quando i file nel tuo workspace sono una copia esatta del ramo predefinito o di monitoraggio, Dataform mostra lo stato Workspace aggiornato.

Dataform visualizza le seguenti opzioni di controllo della versione:

Esegui il commit delle modifiche a X

Esegui il commit del numero X di modifiche locali nel tuo workspace o nei file modificati selezionati. Dataform mostra le modifiche non eseguite.

Esegui il push sul branch predefinito

Esegui il push delle modifiche di cui è stato eseguito il commit sul branch predefinito. Questa opzione è disponibile in un repository Dataform se non hai modifiche non commit nel tuo workspace.

Push a your-branch-name

Esegui il push delle modifiche di cui hai eseguito il commit in your-branch-name. Questa opzione è disponibile in un repository collegato a un repository Git di terze parti se non hai modifiche di cui non è stato eseguito il commit nel workspace.

Esegui il pull dal branch predefinito

Aggiorna i tuoi workspace con le modifiche recenti del branch predefinito. Questa opzione è disponibile in un repository Dataform se non hai modifiche di cui non è stato eseguito il commit o il push nel tuo workspace.

Pull da your-branch-name

Aggiorna il tuo workspace con le modifiche recenti di your-branch-name. Questa opzione è disponibile in un repository connesso a un repository Git di terze parti se non hai modifiche di cui non è stato eseguito il commit o il push nel tuo workspace.

Ripristina l'ultimo commit

Ripristina lo stato dei file nello spazio di lavoro in base all'ultimo commit.

Esegui il pull delle modifiche

Se il workspace di sviluppo non è sincronizzato con il repository, Dataform visualizza l'opzione Pull. Per estrarre le modifiche dal repository allo spazio di lavoro di sviluppo:

1. Nella pagina Dataform, seleziona un repository.
2. Nella scheda Aree di lavoro di sviluppo, seleziona un'area di lavoro di sviluppo.
3. Nella pagina dell'area di lavoro di sviluppo, segui questi passaggi:
   1. Se ti trovi in un repository Dataform, fai clic su Esegui il pull dal branch predefinito.
   2. Se ti trovi in un repository connesso a un repository Git di terze parti, fai clic su Pull da your-branch-name.

Esegui il commit delle modifiche

Dopo aver apportato una modifica in un workspace di sviluppo, Dataform visualizza l'opzione Commit. Puoi eseguire il commit di tutte le modifiche locali o dei file selezionati.

Nota: per impostazione predefinita, Dataform utilizza l'indirizzo email dell'utente autenticatoGoogle Cloud per l'autore del commit, ma l'API Dataform consente di impostare un indirizzo email personalizzato per l'autore del commit. Questo comportamento è simile al comando git commit --author e influisce solo sulla cronologia dei commit Git. L'identità dell'autore del commit non è verificata in modo crittografico.

Nella finestra di dialogo Nuovo commit, Dataform mostra le modifiche non sottoposte a commit.

Per eseguire il commit delle modifiche dal workspace di sviluppo al repository, segui questi passaggi:

1. Nella pagina Dataform, seleziona un repository.
2. Nella pagina del repository, seleziona un workspace di sviluppo.
3. Nella pagina dell'area di lavoro di sviluppo, fai clic su Commit.

4. Nel riquadro Nuovo commit, segui questi passaggi:

   1. Nel campo Aggiungi un messaggio di commit, inserisci una descrizione per il commit.

   2. Seleziona i file modificati di cui vuoi eseguire il commit.

      Se non selezioni alcun file, Dataform esegue il commit di tutte le modifiche locali. Puoi filtrare i file modificati in base allo stato, al nome file e al percorso.

   3. Fai clic su Esegui il commit di tutte le modifiche o su Esegui il commit di X modifiche.

      Il nome del pulsante dipende dalla selezione dei file da eseguire il commit.

Invia modifiche

Dataform visualizza l'opzione Push dopo il commit delle modifiche. Per eseguire il push delle modifiche dal workspace di sviluppo al repository, segui questi passaggi:

1. Nella pagina Dataform, seleziona un repository.
2. Nella pagina del repository, seleziona un workspace di sviluppo.
3. Esegui il commit delle modifiche.
4. Nella pagina dell'area di lavoro di sviluppo, segui questi passaggi:
   1. Se ti trovi in un repository Dataform, fai clic su Esegui il push sul branch predefinito.
   2. Se ti trovi in un repository connesso a un repository Git di terze parti, fai clic su Push to your-branch-name.

Annulla modifiche di cui non è stato eseguito il commit

Per ripristinare le modifiche di cui non è stato eseguito il commit:

1. Nella pagina Dataform, seleziona un repository.
2. Nella pagina del repository, seleziona un workspace di sviluppo.
3. Sopra il riquadro File, fai clic sul menu Altro e poi seleziona Ripristina ultimo commit.

Risolvi i conflitti di unione

Un conflitto di unione può verificarsi quando una modifica locale nel tuo workspace di sviluppo non è compatibile con una modifica apportata al branch di monitoraggio predefinito del tuo repository. I conflitti di unione si verificano in genere quando più utenti modificano contemporaneamente lo stesso file.

In genere, si verifica un conflitto di unione quando esegui un pull da un branch dopo che un altro utente ha eseguito un push di una modifica in conflitto nello stesso branch. Devi risolvere manualmente un conflitto di unione modificando il file interessato.

Il seguente esempio di codice mostra un conflitto di unione visualizzato in un file SQLX:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

Per risolvere un conflitto di unione:

1. Nel tuo workspace di sviluppo, nel riquadro File, seleziona un file interessato.
2. Modifica il file con le modifiche che hai scelto.
3. Esegui il commit delle modifiche.
4. (Facoltativo) Invia le modifiche.

Identificazione dei repository per gli asset BigQuery

I repository Dataform creati e gestiti automaticamente da un'altra funzionalità BigQuery, come i blocchi note o le query salvate, sono nascosti in Dataform nella console Google Cloud per ridurre il disordine e impedire la modifica accidentale della logica specifica della funzionalità. Questi repository potrebbero essere visualizzati nelle ricerche di Cloud Asset Inventory o nei controlli delle autorizzazioni IAM, ma non in Dataform nella console Google Cloud .

Puoi identificare l'origine di un repository Dataform esaminando le etichette delle risorse. La tabella seguente descrive le etichette utilizzate dalle varie funzionalità di BigQuery:

Funzionalità	Chiave di etichetta	Valore etichetta
Repository BigQuery	origin	bigquery-studio
Repository Git di BigQuery Studio	origin	bigquery-studio-git-folder
Data canvas	single-file-asset-type	data_canvas
Preparazione dei dati	single-file-asset-type	data_preparation o data_preparation_sqlx
Notebooks	single-file-asset-type	notebook
Pipeline	bigquery-workflow	(Qualsiasi valore)
Query salvate	single-file-asset-type	sql

Per recuperare le etichette da un repository che non viene visualizzato in Dataform, seleziona una delle seguenti opzioni:

Console

1. Nella console Google Cloud , vai alla pagina Inventario asset.

   Vai ad Asset Inventory

2. Fai clic sulla scheda Risorsa.

3. Nel riquadro Filtra i risultati, accanto a Tipo di risorsa, fai clic su Visualizza altro, quindi inserisci dataform.googleapis.com/Repository.

4. Seleziona dataform.Repository e poi fai clic su Applica.

5. Nella tabella dei risultati, individua il repository e controlla la colonna Etichette. Confronta le etichette trovate con la tabella che descrive le etichette utilizzate dalle varie funzionalità di BigQuery per identificare la funzionalità di origine.

API

Per recuperare le etichette, utilizza il metodo projects.locations.repositories.get. Esegui la richiesta API con le seguenti informazioni:

• Endpoint: GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID

In alternativa, nel terminale esegui il seguente comando curl:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID"

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto Google Cloud .
• LOCATION: la regione in cui si trovano le risorse Dataform.
• REPOSITORY_ID: l'identificatore univoco del repository Dataform su cui stai eseguendo la query.

La risorsa projects.locations.repositories restituita nella risposta contiene una mappa di etichette con i metadati utilizzati per identificare la funzionalità di origine.

gcloud

Esegui questo comando in Google Cloud CLI per recuperare le etichette di un repository specifico:

gcloud asset search-all-resources \
    --asset-types=dataform.googleapis.com/Repository \
    --query="name:projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID" \
    --format="yaml(labels)"

Sostituisci quanto segue:

• PROJECT_ID: l'identificatore univoco del tuo progettoGoogle Cloud .
• LOCATION: la Google Cloud regione in cui si trova il tuo repository.
• REPOSITORY_ID: l'identificatore univoco del nuovo repository Dataform.

Per individuare la risorsa corrispondente all'etichetta di output, vai alla pagina della funzionalità corrispondente nella console Google Cloud , ad esempio le cartelle Notebook o Canvas di dati nella scheda Explorer del riquadro a sinistra di BigQuery Studio.

Passaggi successivi

• Per scoprire di più sulle impostazioni progetto Dataform, consulta il riferimento IProjectConfig.
• Per scoprire come installare pacchetti aggiuntivi, consulta Installare un pacchetto in Dataform.
• Per scoprire come creare una tabella, consulta Creare una tabella.