Gestisci i metadati e la derivazione dei dati di Dataform con Knowledge Catalog

Knowledge Catalog consente di archiviare e gestire i metadati. I repository Dataform sono disponibili in Knowledge Catalog per impostazione predefinita, senza alcuna configurazione aggiuntiva. Knowledge Catalog recupera automaticamente i seguenti metadati dai repository Dataform:

• Nome dell'asset di dati

• Asset di dati padre

• Posizione dell'asset di dati

• Tipo di asset di dati

• Progetto Google Cloud corrispondente

• Origine repository di terze parti

• Service account

Prima di iniziare

1. Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

   Ruoli richiesti per selezionare o creare un progetto

   • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
   • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

   Vai al selettore di progetti

2. Abilita le API Dataplex e Data Lineage, se non sono già abilitate.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilita le API

3. Assicurati di disporre delle autorizzazioni Identity and Access Management (IAM) necessarie.

Ruoli obbligatori

Per gestire i repository Dataform e visualizzare la derivazione dei dati in Knowledge Catalog, devi disporre dei ruoli Dataform predefiniti che ti consentono di accedere alle risorse Dataform e dei ruoli Knowledge Catalog richiesti.

La tabella seguente elenca i ruoli necessari a ciascuna entità per registrare e visualizzare la derivazione dei dati di Dataform:

Il ruolo Producer di eventi di derivazione dei dati contiene l'autorizzazione datalineage.locations.processOpenLineageMessage, necessaria per registrare la derivazione.

Gestisci i metadati in Knowledge Catalog

Knowledge Catalog registra i repository Dataform come voci con i seguenti valori:

Gruppo di voci di sistema

Il gruppo di voci di sistema per i repository Dataform è @dataform. Per visualizzare i dettagli delle voci del repository 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 i repository Dataform è dataform-repository. Per visualizzare i dettagli dei repository Dataform, devi visualizzare il tipo di voce di sistema dataform-repository. 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.

Cerca asset

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

Annota i repository

Per fornire un contesto aggiuntivo ai repository Dataform in Knowledge Catalog, puoi annotare le voci Dataform con aspetti.

Il tipo di aspetto di sistema per i repository Dataform è dataform-repository.

Per istruzioni su come annotare le voci con gli aspetti, consulta Gestisci gli aspetti e arricchisci i metadati nella documentazione di Knowledge Catalog.

Monitora la derivazione dei dati in Knowledge Catalog

Dataform segnala la provenienza dei dati a Knowledge Catalog per le azioni eseguite nei workflow di Dataform e nelle pipeline di BigQuery. Per ogni azione eseguita, il grafico della derivazione in Knowledge Catalog e BigQuery mostra un processo Dataform tra le tabelle lette dall'azione e la tabella in cui scrive. Non è necessario modificare i file SQLX per segnalare la derivazione.

Puoi utilizzare la derivazione dei dati di Dataform per le seguenti attività:

• Analisi dell'impatto: identifica ogni azione e tabella downstream prima di modificare una tabella.

• Analisi delle cause principali: risalire ai dati errati fino all'azione e alla chiamata del workflow che li ha scritti.

• Governance: mostra come i dati fluiscono tra i progetti e quale pipeline li ha spostati.

• Lineage end-to-end: visualizza il lineage di Dataform in un unico grafico insieme al lineage di BigQuery, Managed Service for Apache Airflow, Managed Service for Apache Spark e Dataflow.

Come funziona la derivazione dei dati

Dataform invia un evento OpenLineage START all'API Data Lineage quando inizia un'azione. Al termine dell'azione, Dataform invia un evento COMPLETE, FAIL o ABORT. Ogni azione Dataform viene visualizzata in Knowledge Catalog come un processo con il tipo di origine BIGQUERY_PIPELINES e ogni esecuzione dell'azione viene visualizzata come un'esecuzione del processo.

La tabella seguente descrive i tipi di azioni Dataform che segnalano la derivazione:

La generazione di report sulla derivazione non causa mai l'errore di un'invocazione del workflow. Se l'API Data Lineage è disabilitata, manca un'autorizzazione o viene superata una quota, Dataform salta i report sulla derivazione e l'invocazione del workflow continua senza modifiche.

Dataform scrive la derivazione nell'endpoint regionale della località di elaborazione BigQuery di ogni azione. Se l'endpoint regionale non è disponibile, Dataform scrive la derivazione nell'endpoint globale.

Come i workflow di Dataform vengono mappati alla derivazione dei dati

La seguente tabella descrive come le entità di esecuzione di Dataform vengono mappate al modello di informazioni sulla derivazione dei dati di Knowledge Catalog:

Configura la derivazione dei dati

Per configurare Dataform in modo che generi report sulla derivazione dei dati, segui questi passaggi:

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

2. Nel progetto che contiene il repository, concedi il ruolo Producer di eventi di derivazione dei dati (roles/datalineage.producer) all'identità che esegue i workflow:

   • Se il repository, la configurazione della release o la configurazione del workflow utilizza un service account personalizzato, concedi il ruolo al account di servizio personalizzato.

   • Se non è impostato un account di servizio personalizzato, concedi il ruolo all'agente di servizio Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com).

Le esecuzioni di workflow eseguite con le credenziali utente di un Account Google non segnalano la derivazione.

Attiva o disattiva la derivazione dei dati

Durante il periodo di implementazione iniziale, i report sulla derivazione dei dati sono facoltativi.

Per controllare i report sulla derivazione dei dati per un repository o una pipeline BigQuery, imposta la proprietà lineage.enabled nel file workflow_settings.yaml:

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

   Vai a Dataform

2. Seleziona un repository, quindi seleziona un workspace di sviluppo.

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

4. Per attivare i report sulla derivazione dei dati, aggiungi il seguente blocco lineage:

   lineage:
     enabled: true
   

   Per disattivare i report sulla derivazione dei dati per il repository dopo che la derivazione è stata attivata per impostazione predefinita, imposta enabled su false:

   lineage:
     enabled: false
   

5. Fai il commit e il push delle modifiche nel repository.

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

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

   Vai a BigQuery

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

3. Fai clic sulla scheda Derivazione.

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

5. Per aprire il repository in Dataform, 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.

Segnala la derivazione dei dati dall'interfaccia a riga di comando di Dataform

Per segnalare la derivazione dei dati dalle esecuzioni locali o CI dell'interfaccia a riga di comando di Dataform, imposta lineage.enabled: true in workflow_settings.yaml o esegui il seguente comando:

dataform run --emit-lineage

I flag --emit-lineage e --no-emit-lineage sostituiscono l'impostazione lineage.enabled per una singola esecuzione.

L'interfaccia a riga di comando di Dataform utilizza le credenziali predefinite dell'applicazione e registra la derivazione nel progetto di ogni tabella di output. In ciascuno di questi progetti, abilita l'API Data Lineage e concedi alla credenziale il ruolo Producer di eventi di derivazione dei dati (roles/datalineage.producer). La CLI scrive i messaggi di derivazione in stderr con il prefisso [lineage].

Per saperne di più sulla generazione di report sulla derivazione dalla CLI, consulta il riferimento alla CLI di Dataform su GitHub.

Risolvi i problemi relativi alla derivazione dei dati

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

Dopo il primo errore di autorizzazione o API in una chiamata del workflow, Dataform interrompe la generazione di report sulla derivazione per il resto della chiamata del workflow. La successiva chiamata del workflow tenta di segnalare nuovamente la derivazione.

Quando contatti l'assistenza per un problema di derivazione dei dati, includi l'ID di chiamata del workflow, l'ID progetto e la regione.

Visualizza i log di derivazione per un'esecuzione del workflow

In Cloud Logging, Dataform scrive le voci di log della derivazione nel log dataform.googleapis.com/lineage_emission. Ogni voce include i campi workflowInvocationId, actionTarget e eventType.

Per visualizzare i log di derivazione per un'esecuzione del workflow, segui questi passaggi:

1. Nella console Google Cloud , apri la pagina dei dettagli dell'esecuzione del workflow.

2. Fai clic su Visualizza log.

   Logging si apre con i log filtrati in base all'esecuzione del workflow da jsonPayload.workflowInvocationId.

Il campo outcome in ogni voce di log della derivazione ha uno dei seguenti valori:

• SUCCEEDED: l'API Data Lineage ha accettato l'evento. Queste voci hanno gravità DEBUG e eventType è START, COMPLETE, FAIL o ABORT.

• SKIPPED: Dataform ha saltato il reporting della derivazione. Queste voci hanno gravità INFO e vengono registrate una volta per ogni motivo in un'esecuzione del workflow. Il campo skipReason è API_DISABLED, PERMISSION_DENIED, EUC_UNSUPPORTED o AUTHORITY_UNAVAILABLE e il campo errorMessage contiene i passaggi di correzione.

• FAILED: il reporting della derivazione non è riuscito dopo i nuovi tentativi. Queste voci hanno gravità WARNING e includono i campi errorCode e errorMessage.

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")

Messaggi di derivazione dei dati dall'interfaccia a riga di comando di Dataform

L'interfaccia a riga di comando di Dataform scrive i seguenti messaggi di derivazione in stderr:

• skip_reason=workflow_opt_out: lineage.enabled è impostato su false.

• skip_reason=invocation_override: i report sulla derivazione sono disattivati per questa esecuzione con --no-emit-lineage o --emit-lineage=false.

• skip_reason=dry_run: i dry run non segnalano la derivazione.

• skip_reason=api_disabled: l'API Data Lineage non è abilitata. La CLI non invia altre richieste di derivazione in questa esecuzione.

• skip_reason=permission_denied: la credenziale non ha il ruolo Producer di eventi di derivazione dei dati (roles/datalineage.producer). L'interfaccia a riga di comando non invia altre richieste di derivazione in questa esecuzione.

• Failed to emit lineage for action ...: generazione di report sulla derivazione non riuscita per un'azione. I report sulla derivazione per le altre azioni continuano.

Limitazioni

La gestione dei repository Dataform e il monitoraggio della derivazione dei dati in Knowledge Catalog sono soggetti alle seguenti limitazioni:

• In Knowledge Catalog sono disponibili solo le voci a livello di repository e di workflow. I singoli asset di codice a livello di file in Dataform, come i file di definizione SQLX, non vengono catalogati come voci separate.

• Dataform segnala solo la derivazione a livello di tabella. La derivazione a livello di colonna non viene registrata.

• Dichiarazioni, notebook e test delle unità SQL non segnalano la derivazione. Le dichiarazioni vengono visualizzate solo come input per altre azioni. Le operazioni senza hasOutput: true riportano solo il processo e l'esecuzione, senza link di derivazione da tabella a tabella.

• Le esecuzioni del workflow eseguite con le credenziali utente di un Account Google non segnalano la derivazione. Per segnalare la derivazione, utilizza un account di servizio personalizzato.

• I report sulla derivazione dei dati sono soggetti alle quote dell'API Data Lineage per le scritture per progetto, identità e regione. Nel livello Standard, la quota è di circa 1000 azioni al minuto.

Località

Puoi utilizzare Knowledge Catalog per gestire i repository Dataform da tutte le località di Dataform.

Quote

La gestione dei repository Dataform in Knowledge Catalog è soggetta a quote e limiti di Knowledge Catalog.

Prezzi

La gestione dei repository Dataform in Knowledge Catalog è soggetta ai prezzi di Knowledge Catalog.

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 controllare i costi della derivazione dei dati, disattiva i workflow in workflow_settings.yaml o disabilita l'API Data Lineage.

Passaggi successivi

• Per scoprire di più su Knowledge Catalog, consulta la panoramica di Knowledge Catalog nella documentazione di Knowledge Catalog.