Gestisci pipeline

Le pipeline BigQuery ti consentono di ispezionare la cronologia delle esecuzioni, configurare gli avvisi di errore e controllare gli asset di codice basati su Dataform. Puoi anche arricchire i metadati del workflow in Knowledge Catalog per monitorare la qualità dei dati ed eliminare i workflow obsoleti per mantenere organizzato il progetto. A seconda di dove il tuo team archivia il codice, puoi accedere alle pipeline in File e cartelle, incluse le cartelle utente e le cartelle del team, o nei repository Git di BigQuery Studio (cartelle Git) (anteprima).

Prima di iniziare

1. Crea una pipeline BigQuery.
2. Per gestire i metadati della pipeline in Knowledge Catalog, assicurati che l'API Dataplex sia abilitata nel tuo progetto Google Cloud .

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire le pipeline, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Per visualizzare ed eseguire le pipeline:
  • Dataform Viewer (roles/dataform.Viewer) sul progetto
  • Utente job BigQuery (roles/bigquery.jobUser) sul progetto
• Per eseguire pipeline con le credenziali utente per un Account Google: BigQuery Data Editor (roles/bigquery.dataEditor) sul progetto o su set di dati BigQuery specifici
• Per eliminare le pipeline: Dataform Admin (roles/dataform.Admin) sulla pipeline
• Per gestire le pipeline nelle cartelle utente:
  • Code Owner (roles/dataform.codeOwner) sulla cartella
  • Editor di codice (roles/dataform.codeEditor) sulla cartella
  • Code Viewer (roles/dataform.codeViewer) nella cartella
• Per gestire le pipeline nelle cartelle del team:
  • Team Folder Owner (roles/dataform.teamFolderOwner) sulla cartella del team
  • Team Folder Contributor (roles/dataform.teamFolderContributor) sulla cartella del team
  • Team Folder Viewer (roles/dataform.teamFolderViewer) sulla cartella del team
• Per gestire le pipeline nei repository Git: Developer Connect OAuth User (roles/developerconnect.oauthUser) sul progetto
• Per visualizzare e gestire i metadati in Knowledge Catalog: Dataplex Catalog Editor (roles/dataplex.catalogEditor) sul progetto o sul gruppo di voci @bigquery
• Per visualizzare la derivazione dei dati per le pipeline: Data Lineage Viewer (roles/datalineage.viewer) sul progetto
• Per aprire le pipeline dal grafico di derivazione: Dataform Viewer (roles/dataform.viewer) nel progetto che contiene la pipeline

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.

Per saperne di più su IAM di Dataform, consulta Controlla l'accesso con IAM. Per saperne di più sui ruoli per le cartelle, consulta Crea e gestisci le cartelle. Per ulteriori informazioni sui ruoli per i repository Git, consulta Gestisci il codice con i repository Git di BigQuery Studio.

Se utilizzi un account di servizio personalizzato per eseguire le pipeline, devi concedere i seguenti ruoli a quel account di servizio:

• Utente job BigQuery (roles/bigquery.jobUser) sul progetto
• BigQuery Data Editor (roles/bigquery.dataEditor) sul progetto o su set di dati BigQuery specifici
• Dataplex Catalog Editor (roles/dataplex.catalogEditor) sul progetto o sul gruppo di voci @bigquery
• Producer di eventi di derivazione dei dati (roles/datalineage.producer) nel progetto che contiene la pipeline, per segnalare la derivazione dei dati

Visualizza le pipeline

Puoi visualizzare e ispezionare le pipeline archiviate in cartelle o cartelle Git nel riquadro File. Puoi visualizzare le pipeline autonome e quelle archiviate nelle cartelle nel riquadro Explorer. Le pipeline archiviate nelle cartelle Git non vengono visualizzate nel riquadro Explorer.

Visualizza le pipeline nel riquadro File

Le pipeline archiviate in cartelle o in cartelle Git vengono visualizzate direttamente nel riquadro File.

Per visualizzare una pipeline archiviata in una cartella o in una cartella Git, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su folder File per aprire il browser di file.

   Se non vedi il riquadro a sinistra, fai clic su last_page Espandi riquadro sinistro per aprirlo.

3. Espandi la cartella Utente, una cartella del team o una cartella del repository Git connesso.

   Le pipeline vengono visualizzate con un'icona Pipeline anziché con un'icona di cartella standard.

4. Fai clic su una cartella della pipeline per aprire il visualizzatore della pipeline.

   Il visualizzatore di pipeline mostra il grafo diretto aciclico (DAG) compilato delle attività della pipeline, lo stato di esecuzione e le schede di configurazione.

5. Espandi la directory della pipeline nel browser dei file per sfogliare le directory nidificate (come definitions/) e i singoli file delle attività.

Visualizza le pipeline nel riquadro Explorer

Per visualizzare un elenco di pipeline autonome e pipeline archiviate in cartelle, procedi nel seguente modo:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su explore Spazio di esplorazione:

   

   Se non vedi il riquadro a sinistra, fai clic su last_page Espandi riquadro sinistro per aprirlo.

3. Nel riquadro Explorer, espandi il progetto e fai clic su Pipeline.

4. Seleziona una pipeline per aprirla nel visualizzatore di pipeline.

Visualizza le esecuzioni manuali precedenti

Per visualizzare le esecuzioni manuali precedenti di una pipeline selezionata, segui questi passaggi:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su explore Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto, fai clic su Pipeline e seleziona una pipeline.

4. Fai clic su Esecuzioni.

5. (Facoltativo) Per aggiornare l'elenco delle esecuzioni precedenti, fai clic su Aggiorna.

Configura gli avvisi per le esecuzioni delle pipeline non riuscite

Ogni pipeline ha un ID repository Dataform corrispondente. Ogni esecuzione della pipeline BigQuery viene registrata in Cloud Logging utilizzando l'ID repository Dataform corrispondente. Puoi utilizzare Cloud Monitoring per osservare le tendenze nei log di Cloud Logging per le esecuzioni delle pipeline BigQuery e per ricevere notifiche quando si verificano le condizioni descritte.

Per ricevere avvisi quando l'esecuzione di una pipeline BigQuery non va a buon fine, puoi creare una criterio di avviso basata su log per l'ID repository Dataform corrispondente. Per istruzioni, consulta Configura gli avvisi per le esecuzioni dei flussi di lavoro non riuscite.

Per trovare l'ID repository Dataform della pipeline:

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

   Vai a BigQuery

2. Nel riquadro a sinistra, fai clic su explore Spazio di esplorazione:

   

3. Nel riquadro Explorer, espandi il progetto, fai clic su Pipeline e seleziona una pipeline.

4. Fai clic su Impostazioni.

   L'ID repository Dataform della pipeline viene visualizzato nella parte inferiore della scheda Impostazioni.

Elimina una pipeline

Per eliminare definitivamente una pipeline:

1. Nella console Google Cloud , vai alla pagina BigQuery. Vai a BigQuery

• Per eliminare una pipeline archiviata in una cartella o in una cartella Git, segui questi passaggi:

  1. Nel riquadro a sinistra, fai clic su folder File.

  2. Nell'albero dei file, trova la cartella della pipeline che vuoi eliminare.

  3. Fai clic su more_vert Visualizza azioni accanto alla cartella della pipeline, quindi fai clic su Elimina.

  4. Nella finestra di dialogo di conferma, fai clic su Elimina.

     La cartella della pipeline e tutte le attività e i file contenuti al suo interno vengono eliminati dal tuo workspace.

• Per eliminare una pipeline elencata nel riquadro Explorer, segui questi passaggi:

  1. Nel riquadro a sinistra, fai clic su explore Spazio di esplorazione:

     

  2. Nel riquadro Explorer, espandi il progetto e fai clic su Pipeline.

  3. Trova la pipeline che vuoi eliminare.

  4. Fai clic su more_vert Visualizza azioni accanto alla pipeline, quindi fai clic su Elimina.

  5. Fai clic su Elimina.

Gestisci i metadati in Knowledge Catalog

Knowledge Catalog consente di archiviare e gestire i metadati per le pipeline. Le pipeline sono disponibili in Knowledge Catalog per impostazione predefinita, senza ulteriori configurazioni.

Puoi utilizzare Knowledge Catalog per gestire le pipeline in tutte le località delle pipeline. La gestione delle pipeline in Knowledge Catalog è soggetta a quote e limiti di Knowledge Catalog e ai prezzi di Knowledge Catalog.

Knowledge Catalog recupera automaticamente i seguenti metadati dalle pipeline:

• Nome dell'asset di dati
• Asset di dati padre
• Posizione dell'asset di dati
• Tipo di asset di dati
• Progetto Google Cloud corrispondente

Knowledge Catalog registra le pipeline come voci con i seguenti valori:

Gruppo di voci di sistema

Il gruppo di voci di sistema per le pipeline è @dataform. Per visualizzare i dettagli delle voci della pipeline in Knowledge Catalog, devi visualizzare il gruppo di voci di sistema dataform. Per istruzioni su come visualizzare un elenco di tutte le voci di un gruppo di voci, consulta Visualizza i dettagli di un gruppo di voci nella documentazione di Knowledge Catalog.

Tipo di voce di sistema

Il tipo di voce di sistema per le pipeline è dataform-code-asset. Per visualizzare i dettagli delle pipeline, devi visualizzare il tipo di voce di sistema dataform-code-asset, filtrare i risultati con un filtro basato sugli aspetti e impostare il campo type all'interno dell'aspetto dataform-code-asset su WORKFLOW. Quindi, seleziona una voce della pipeline selezionata. Per istruzioni su come visualizzare i dettagli di un tipo di voce selezionato, consulta Visualizza i dettagli di un tipo di voce nella documentazione di Knowledge Catalog. Per istruzioni su come visualizzare i dettagli di una voce selezionata, consulta Visualizza i dettagli di una voce nella documentazione di Knowledge Catalog.

Tipo di aspetto del sistema

Il tipo di aspetto di sistema per le pipeline è dataform-code-asset. Per fornire un contesto aggiuntivo alle pipeline in Knowledge Catalog annotando le voci della pipeline di dati con gli aspetti, visualizza il tipo di aspetto dataform-code-asset, filtra i risultati con un filtro basato sugli aspetti e imposta il campo type all'interno dell'aspetto dataform-code-asset su WORKFLOW. Per istruzioni su come annotare le voci con gli aspetti, consulta Gestisci gli aspetti e arricchisci i metadati nella documentazione di Knowledge Catalog.

Tipo

Il tipo per i data canvas è WORKFLOW. Questo tipo consente di filtrare le pipeline nel tipo di voce di sistema dataform-code-asset e nel tipo di aspetto dataform-code-asset utilizzando la query aspect:dataplex-types.global.dataform-code-asset.type=WORKFLOW in un filtro basato sugli aspetti.

Per istruzioni su come cercare asset in Knowledge Catalog, consulta Cerca asset di dati in Knowledge Catalog nella documentazione di Knowledge Catalog.

Integrazione dell'arricchimento dei metadati e della scheda di valutazione della qualità dei dati

Dataform può pubblicare i seguenti metadati in Knowledge Catalog:

• Tipo di aspetto della panoramica
• Tipo di aspetto generico
• Tipo di aspetto della scheda di valutazione della qualità dei dati

Le asserzioni di Dataform vengono integrate automaticamente con lo scorecard della qualità dei dati di Knowledge Catalog. Durante l'esecuzione della pipeline, i risultati di tutte le asserzioni di Dataform vengono pubblicati automaticamente in Knowledge Catalog. Questi risultati compilano lo scorecard della qualità dei dati di Knowledge Catalog con uno stato di superamento o mancato superamento.

Per controllare lo stato di un aggiornamento dei metadati, segui le istruzioni riportate in Visualizza le esecuzioni manuali precedenti.

Una volta sincronizzati i metadati, puoi cercare e visualizzare la voce in Knowledge Catalog. Per saperne di più, consulta Cerca risorse.

Monitora la derivazione dei dati

BigQuery segnala la provenienza dei dati a livello di tabella a Knowledge Catalog per le azioni eseguite nella pipeline BigQuery. Per ogni azione eseguita, il grafico di derivazione in BigQuery e Knowledge Catalog mostra un processo tra le tabelle lette dall'azione e la tabella scritta dall'azione. Non è necessario modificare i file SQLX per generare report sulla derivazione.

Tabelle, viste, tabelle incrementali, viste materializzate, asserzioni, grafici delle proprietà, preparazioni dei dati e operazioni con derivazione da tabella a tabella del hasOutput: true tabella report. Le operazioni senza hasOutput: true segnalano solo il processo e l'esecuzione. Dichiarazioni, notebook e test delle unità SQL non segnalano la derivazione. Le dichiarazioni vengono visualizzate solo come input per altre azioni.

La segnalazione della derivazione non causa mai l'errore di un'esecuzione della pipeline. Se l'API Data Lineage è disabilitata, manca un'autorizzazione o viene superata una quota, l'esecuzione della pipeline continua senza segnalare la derivazione.

L'importazione della derivazione dei dati viene fatturata in base allo SKU di elaborazione premium di Knowledge Catalog e vengono fatturati solo gli eventi che scrivono link di derivazione da tabella a tabella. L'archiviazione della derivazione dei dati viene fatturata in base allo SKU di archiviazione dei metadati. Per saperne di più, consulta i prezzi di Knowledge Catalog.

Limitazioni della derivazione dei dati

La derivazione dei dati per le pipeline è soggetta alle seguenti limitazioni:

• Viene riportata solo la derivazione a livello di tabella. La derivazione a livello di colonna non viene registrata.

• I report sulla derivazione dei dati sono soggetti alle quote dell'API Data Lineage per le scritture per progetto, identità e regione.

Abilita la derivazione dei dati

Per abilitare la derivazione dei dati per la pipeline, segui questi passaggi:

1. Abilita l'API Data Lineage (datalineage.googleapis.com) nel progetto che contiene la pipeline e nel progetto in cui gli utenti visualizzano la derivazione.

2. Nel progetto che contiene la pipeline, concedi il ruolo Producer di eventi di derivazione dei dati (roles/datalineage.producer) all'identità che esegue la pipeline. Questa identità è il account di servizio personalizzato della pipeline o l'agente di servizio Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) se non è impostato alcun account di servizio personalizzato.

3. Nel file workflow_settings.yaml della pipeline, aggiungi il seguente blocco lineage:

   lineage:
     enabled: true
   

Le esecuzioni di pipeline che utilizzano le credenziali dell'utente finale per un Account Google non segnalano la derivazione. Per segnalare la derivazione, esegui la pipeline con un account di servizio personalizzato.

Per interrompere i report sulla derivazione dei dati per una pipeline, imposta enabled su false nel blocco lineage. Per interrompere i report sulla derivazione dei dati per un intero progetto, disabilita l'API Data Lineage nel progetto. La disattivazione dell'API interrompe anche i report sulla derivazione dei dati di altri servizi nel progetto.

Visualizza la derivazione dei dati

Per visualizzare la derivazione dei dati per una tabella prodotta da un'azione della pipeline, segui questi passaggi:

1. Nella console Google Cloud , vai a BigQuery Studio.

   Vai a BigQuery Studio

2. Nel riquadro Explorer, espandi il progetto e il set di dati, quindi seleziona una tabella prodotta da un'azione della pipeline.

3. Fai clic sulla scheda Derivazione.

4. Per visualizzare l'azione, la pipeline e le esecuzioni, seleziona il nodo del processo.

5. Per aprire la pipeline, fai clic su Apri in Dataform.

Per saperne di più sulla navigazione nei grafici di derivazione, consulta Visualizza la derivazione dei dati in Knowledge Catalog.

Risolvi i problemi relativi alla derivazione dei dati

La tabella seguente descrive i problemi comuni relativi alla derivazione dei dati per le pipeline e come risolverli:

Dopo il primo errore di autorizzazione o API in un'esecuzione della pipeline, BigQuery interrompe la generazione di report sulla derivazione per il resto dell'esecuzione. La successiva esecuzione della pipeline tenta di segnalare nuovamente la derivazione.

Per verificare se un'esecuzione della pipeline ha segnalato la derivazione, visualizza le voci di log dataform.googleapis.com/lineage_emission in Cloud Logging. Per filtrare i report sulla derivazione ignorati o non riusciti in Esplora log, esegui la seguente query:

log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")

Passaggi successivi

• Scopri di più sulle pipeline BigQuery.
• Scopri come creare pipeline.
• Scopri come pianificare le pipeline.
• Scopri come gestire il codice con i repository Git di BigQuery Studio.
• Scopri come organizzare gli asset di codice con le cartelle.
• Scopri di più sui deployment di Dataform.