A partire dal 10 aprile 2026, Dataplex Universal Catalog si chiama Knowledge Catalog. I nomi di API, libreria client, CLI e IAM rimangono invariati. Per ulteriori informazioni, consulta Presentazione di Google Cloud Knowledge Catalog.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Importare i metadati da dbt Core

Questo documento descrive come importare i metadati da dbt Core e MetricFlow in Knowledge Catalog (in precedenza Dataplex Universal Catalog) utilizzando il comando gcloud.

I seguenti metadati vengono acquisiti dall'integrazione dbt:

Metadati tecnici: includono le risorse chiave (origini, seed, modelli) e le relative proprietà tecniche (nomi delle colonne, tipi di dati, conteggi delle righe).
Metadati aziendali e semantici: basati su dbt MetricFlow, questo include definizioni e logica aziendali come modelli semantici, metriche, e query salvate.
Metadati operativi e di qualità dei dati: includono metadati di esecuzione come tempistiche, stato di successo o errore, aggiornamento dei dati, test e risultati dei test.
Metadati di tracciabilità e relazione: includono grafi di trasformazione (DAG) e dipendenze tra le risorse dbt, tracciabilità fisica che monitora e collega i blocchi di trasformazione fisica, chiavi di join e join dinamiche e relazioni padre-figlio.
Metadati di consumo: includono i metadati acquisiti nelle esposizioni che mappano il modo in cui i dati vengono utilizzati al di fuori di dbt.

Prima di poter importare i metadati da dbt Core e MetricFlow, completa le seguenti attività:

Concedi i ruoli e le autorizzazioni richiesti.
Abilita l'API Knowledge Catalog.
Soddisfa i prerequisiti di dbt prerequisiti.
Crea il gruppo di voci di destinazione , se non esiste già.
Comprendi i ruoli di Cloud Storage.

Ruoli e autorizzazioni IAM

Per creare e gestire un job del connettore Knowledge Catalog, devi disporre dei ruoli Identity and Access Management (IAM) che concedono le autorizzazioni per Knowledge Catalog e Cloud Storage.

Per ottenere le autorizzazioni necessarie per configurare un connettore dbt, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per creare e gestire i gruppi di voci: Dataplex Catalog Admin (roles/dataplex.catalogAdmin), Dataplex Catalog Editor (roles/dataplex.catalogEditor), o Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) nel progetto.
Per eseguire il comando gcloud dbt e creare job di importazione dei metadati: per seguire il principio del privilegio minimo, concedi i seguenti ruoli:
- Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) nel progetto.
- Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) nel gruppo di voci di destinazione o nel progetto.
In alternativa, puoi concedere i ruoli Dataplex Catalog Admin (roles/dataplex.catalogAdmin) e Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) nel progetto.
Per caricare i metadati trasformati nel bucket di gestione temporanea di output (--storage-uri): Storage Object Creator (roles/storage.objectCreator) o Storage Object Admin (roles/storage.objectAdmin) nel bucket di gestione temporanea.
Per leggere gli artefatti dbt da un bucket Cloud Storage di input (--artifacts-path, se utilizzi Cloud Storage): Storage Object Viewer (roles/storage.objectViewer) o Storage Object Admin (roles/storage.objectAdmin) nel bucket degli artefatti di input. Se hai il ruolo Storage Object Admin, il ruolo Storage Object Viewer non è obbligatorio.
Per visualizzare i metadati dbt: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) nel progetto.
Per visualizzare i log in Cloud Logging: Logs Viewer (roles/logging.viewer) nel progetto.

Inoltre, devi concedere all'agente di servizio Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) il ruolo Storage Object Viewer (roles/storage.objectViewer) nel bucket Cloud Storage di gestione temporanea di output (--storage-uri) in modo che il job di importazione possa leggere il file di metadati di gestione temporanea.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso.

Abilita API

Abilita l'API Knowledge Catalog.

Abilita l'API

Prerequisiti di dbt

Per importare l'insieme completo di metadati dbt, ti consigliamo di produrre tutti e quattro i file di artefatti JSON dbt. È richiesto solo manifest.json; gli altri arricchiscono l'importazione e la trasformazione si degrada gradualmente senza di essi:

manifest.json (obbligatorio): struttura del progetto principale e grafico di esecuzione. Contiene anche i modelli semantici, le metriche e le query salvate di MetricFlow.
catalog.json: nomi delle colonne e tipi di dati. Senza catalog.json, l'aspetto dello schema viene importato con colonne senza tipo.
run_results.json: risultati dei test e metadati di esecuzione.
sources.json: aggiornamento dell'origine.

Per generare l'insieme completo di file JSON degli artefatti dei metadati dbt, puoi eseguire i seguenti comandi dbt in questo ordine:

dbt source freshness
dbt build
dbt docs generate --no-compile

Avviso: senza --no-compile, dbt docs generate sovrascrive run_results.json con lo stato success per ogni nodo. I risultati dei test del precedente dbt build vengono persi e il catalogo segnala che tutti i test di qualità dei dati sono superati.

Comprendi i ruoli di Cloud Storage

L'importazione dei metadati dbt coinvolge due località Cloud Storage distinte che hanno scopi diversi e non devono essere confuse:

Input (artefatti di origine dbt): dove risiedono i file JSON dbt generati. Può essere un percorso di directory locale sulla macchina o sul runner CI (ad esempio ./target/ o .) o un prefisso URI del bucket Cloud Storage di input (ad esempio gs://my-dbt-artifacts-bucket/target/). Questo percorso viene fornito utilizzando il flag --artifacts-path. Il comando gcloud legge questi file di input durante la preparazione del job. Il chiamante che esegue il comando gcloud deve disporre dell'accesso in lettura (roles/storage.objectViewer o roles/storage.objectAdmin) se utilizza Cloud Storage. L'agente di servizio Knowledge Catalog non ha bisogno dell'accesso al bucket degli artefatti di input.
Output (bucket di gestione temporanea di importazione di Knowledge Catalog): un prefisso URI del bucket Cloud Storage (ad esempio gs://my-staging-bucket/dbt-imports/) in cui il comando gcloud carica il file di importazione dei metadati trasformati (dbt_metadata.jsonl) e da cui il job di importazione di Knowledge Catalog legge durante l'importazione. Questo URI viene fornito utilizzando il flag --storage-uri. Il chiamante che esegue il comando gcloud deve disporre dell'accesso in scrittura (roles/storage.objectCreator o roles/storage.objectAdmin) per caricare il file e l'agente di servizio Knowledge Catalog deve disporre dell'accesso in lettura (roles/storage.objectViewer) per importarlo.

Configura la connettività dbt

Per stabilire la connettività dbt, devi prima eseguire i comandi dbt appropriati per generare gli artefatti dei metadati. Una volta archiviati e accessibili i file JSON, puoi utilizzare il comando gcloud alpha dataplex dbt metadata-jobs create per:

Leggi gli artefatti di input: leggi gli artefatti JSON generati da dbt Core e MetricFlow dalla località di input (directory locale o URI Cloud Storage specificato in --artifacts-path).
Trasforma i metadati: trasforma i contenuti nel formato di importazione dei metadati di Knowledge Catalog (dbt_metadata.jsonl).
Carica nella gestione temporanea: carica il file di importazione dei metadati trasformati nella località Cloud Storage di gestione temporanea di output specificata in --storage-uri.
Attiva il job di importazione: attiva un job di importazione dei metadati di Knowledge Catalog che indica all'agente di servizio Knowledge Catalog di leggere e importare i metadati di gestione temporanea da --storage-uri nelle risorse di Knowledge Catalog.

Per creare un job di metadati dbt, completa i seguenti passaggi:

Assicurati che i file degli artefatti dei metadati dbt siano archiviati localmente o in un bucket Cloud Storage di input.
Assicurati di aver configurato un bucket Cloud Storage di gestione temporanea di output con le autorizzazioni appropriate sia per il chiamante sia per l'agente di servizio Knowledge Catalog.
Da Cloud Shell, un terminale locale o uno strumento di workflow automatizzato, esegui il comando gcloud:
```
gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/
```
Flag obbligatori
- --storage-uri=STORAGE_URI: (Output/Gestione temporanea) Prefisso URI Cloud Storage (gs://bucket/path/) in cui viene caricato il file JSONL trasformato e da cui il job di importazione legge durante l'importazione. Il chiamante deve disporre dell'accesso in scrittura (roles/storage.objectCreator o roles/storage.objectAdmin) e l'agente di servizio Knowledge Catalog deve disporre dell'accesso in lettura (roles/storage.objectViewer).
Flag facoltativi
- --artifacts-path=ARTIFACTS_PATH: (Input) Percorso degli artefatti dbt di origine. Può essere un percorso di directory locale (ad esempio . o ./target) o un prefisso URI Cloud Storage (ad esempio gs://my-bucket/dbt-artifacts/). Può puntare alla radice del progetto dbt (la sottodirectory target/ viene rilevata automaticamente) o direttamente a la directory contenente manifest.json. Il valore predefinito è .. Se viene fornito un URI Cloud Storage, il chiamante deve disporre dell'accesso in lettura (roles/storage.objectViewer o roles/storage.objectAdmin) al bucket di input.
- --async: restituisce immediatamente, senza attendere il completamento dell'operazione in corso.
- --entry-group=ENTRY_GROUP: ID breve del gruppo di voci che riceve le voci dbt. Deve esistere già nel progetto e nella località (il valore predefinito è dbt-metadata-ingestion).
- --aspects-only: aggiorna solo i metadati osservati da questa esecuzione dbt e lascia intatto il resto del gruppo di voci. Non viene creata, eliminata o riassegnata alcuna voce e un aspetto il cui artefatto dbt era assente in questa esecuzione mantiene il valore assegnato da un'esecuzione precedente. Utilizza questa opzione per l'importazione di routine e ripetuta. Consulta Esegui di nuovo l'importazione.
- --validate-only: crea e carica il file JSON e convalida il job dei metadati, ma non esegue l'importazione.
Verifica di aver ricevuto lo stato Creato.
Dopo aver creato il job, Knowledge Catalog pianifica la prima esecuzione in base alla configurazione oppure puoi avviarla manualmente.

Esegui di nuovo l'importazione

Dopo la prima importazione, la maggior parte delle esecuzioni deve solo aggiornare i metadati delle risorse già esistenti. Utilizza --aspects-only per queste esecuzioni. Aggiorna solo ciò che è stato osservato dall'esecuzione dbt e lascia intatto il resto del gruppo di voci, quindi è sicuro eseguirlo ripetutamente, in qualsiasi pianificazione e da più di un job.

Esegui un'importazione completa (ometti --aspects-only) quando l'insieme di voci cambia:

La prima importazione in un gruppo di voci.
Una risorsa dbt viene aggiunta, rinominata o eliminata.
Il nome visualizzato, la descrizione o le etichette di una voce cambiano.
La gerarchia delle voci cambia.

Un'esecuzione completa riscrive gli aspetti obbligatori di ogni voce dagli artefatti sul disco, quindi eseguila da un insieme di artefatti il più completo possibile che la pipeline può produrre.

Esegui --aspects-only per gli aggiornamenti di routine:

Dopo qualsiasi comando dbt eseguito dalla pipeline: dbt build, dbt test, dbt source freshness o una ricompilazione ristretta con --select.
Una colonna viene aggiunta, rimossa, digitata o descritta di nuovo.
Il modello SQL è stato modificato e l'esecuzione ha scritto anche catalog.json.
Nuovi risultati dei test o aggiornamento dell'origine.

--aspects-only può aggiungere e aggiornare i metadati, ma non può rimuoverli.

Cerca e visualizza i metadati dbt

Nella Google Cloud console, vai alla pagina Knowledge Catalog Cerca.

Vai a Cerca
Nel riquadro Filtri, puoi filtrare gli asset dbt utilizzando le sezioni Progetto, Sistema e Alias di tipo. Nella sezione Sistema, seleziona Contesto importato. Se selezioni questo filtro, si apre una sottosezione Connettori gestiti. Seleziona dbt per filtrare tutti i metadati dbt.
Puoi utilizzare il campo di ricerca per eseguire query di ricerca. Puoi eseguire una ricerca per parole chiave o in linguaggio naturale. Ad esempio, per visualizzare tutti gli asset dbt tramite la ricerca per parole chiave, inserisci system=DBT.

Per scoprire di più sulla ricerca delle risorse, consulta Cercare le risorse in Knowledge Catalog. Per scoprire di più sulle espressioni che puoi utilizzare nel campo di ricerca, consulta Sintassi di ricerca per Knowledge Catalog.
Puoi anche utilizzare l' LookupContext per recuperare il contesto LLM per risorse dbt specifiche.

Limitazioni

Supporta le versioni recenti di dbt Core v1 (convalidate rispetto alle versioni 1.11 e 1.12). dbt Core v2 e dbt Fusion non sono supportati.
I modelli dbt che utilizzano il controllo delle versioni dei modelli non sono supportati.
dbt Cloud non è supportato.
Gli schemi molto grandi o con nidificazione profonda vengono troncati: un singolo aspetto non può superare il limite di dimensioni per aspetto, quindi gli schemi con nidificazione profonda potrebbero perdere i campi finali.
--aspects-only può aggiungere e aggiornare i metadati, ma non può rimuoverli. Per eliminare una risorsa dbt è necessaria un'esecuzione completa.
I link alle voci non sono supportati.
Questa integrazione supporta solo gli eventi di derivazione dbt sulle risorse BigQuery nell'API e nel grafico Data Lineage. Le voci dbt (origine, seed, modelli) per le origini di terze parti esterne non vengono acquisite nella derivazione dei dati.
- Per importare tutti gli eventi di derivazione dbt nell'API Data Lineage, utilizza l' integrazione OpenLineage dbt. Poi, integra OpenLineage con Knowledge Catalog per importare e visualizzare la tracciabilità dei dati da dbt.

Passaggi successivi

Scopri come gestire i job dei connettori.