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 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, includono 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 riuscita o errore, aggiornamento dei dati, test e risultati dei test.
  • Metadati di tracciabilità e relazione: includono grafi di trasformazione (DAG) e dipendenze tra risorse dbt, tracciabilità fisica che monitora e collega blocchi di trasformazione fisici, chiavi di join e join dinamici 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à:

  1. Concedi i ruoli e le autorizzazioni richiesti.
  2. Abilita l'API Knowledge Catalog.
  3. Soddisfare i prerequisiti di dbt.
  4. Crea il gruppo di voci di destinazione se non esiste già.
  5. Comprendi i ruoli Cloud Storage.

Ruoli e autorizzazioni IAM

Per creare e gestire un job del connettore Knowledge Catalog, devi disporre di ruoli Identity and Access Management (IAM) che concedono 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:

Inoltre, devi concedere al service agent Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) nel bucket Cloud Storage di staging dell'output (--storage-uri) in modo che il job di importazione possa leggere il file di metadati di staging.

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

Abilita API

Abilita l'API Knowledge Catalog.

Abilitare l'API

Prerequisiti dbt

Per importare l'intero set 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 viene eseguita senza problemi anche senza:

  • manifest.json (obbligatorio): struttura principale del progetto 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 non tipizzate.
  • run_results.json: Risultati del test e metadati di esecuzione.
  • sources.json: Aggiornamento della fonte.

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

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

Comprendere i ruoli di Cloud Storage

L'importazione dei metadati dbt prevede due diverse posizioni Cloud Storage che hanno scopi diversi e non devono essere confuse:

  • Input (artefatti di origine dbt): dove si trovano i file JSON dbt generati. Può essere un percorso di directory locale sulla tua 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/). Fornisci questo percorso 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. Il service agent Knowledge Catalog non ha bisogno dell'accesso al bucket degli artefatti di input.
  • Output (bucket 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 trasformato (dbt_metadata.jsonl) e da cui il job di importazione di Knowledge Catalog legge durante l'importazione. Fornisci questo URI 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, mentre 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, il processo di importazione esegue le seguenti azioni:

  1. Leggi artefatti di input: leggi gli artefatti JSON generati da dbt Core e MetricFlow dalla posizione di input (directory locale o URI Cloud Storage specificato in --artifacts-path).
  2. Trasforma metadati: trasforma i contenuti nel formato di importazione dei metadati di Knowledge Catalog (dbt_metadata.jsonl).
  3. Carica in staging: carica il file di importazione dei metadati trasformati nella posizione di staging di output di Cloud Storage specificata in --storage-uri.
  4. Attiva job di importazione: attiva un job di importazione dei metadati di Knowledge Catalog che indica al service agent di Knowledge Catalog di leggere e importare i metadati in staging da --storage-uri nelle risorse Knowledge Catalog.

Console

  1. Nella console Google Cloud , vai alla pagina Knowledge Catalog Connettori.

    Vai a Connettori

  2. Fai clic su Aggiungi connessione.

  3. Nell'elenco Connettori, seleziona la scheda dbt Core e MetricFlow.

  4. Per visualizzare gli asset dbt importati, vai alla pagina Cerca o visualizza la pagina Gruppi di voci di destinazione.

gcloud

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

  1. Assicurati che i file degli artefatti dei metadati dbt siano archiviati localmente o in un bucket Cloud Storage di input.
  2. Assicurati di aver configurato un bucket Cloud Storage gestione temporanea di output con le autorizzazioni appropriate sia per il chiamante sia per il service agent Knowledge Catalog.

  3. Da Cloud Shell, da un terminale locale o da 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: prefisso URI Cloud Storage (output/staging) (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 il service agent 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 alla 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 il risultato, senza attendere il completamento dell'operazione in corso.
    • --entry-group=ENTRY_GROUP: l'ID breve del gruppo di voci che riceve le voci dbt. Deve già esistere nel progetto e nella località (il valore predefinito è dbt-metadata-ingestion).
    • --aspects-only: aggiorna solo i metadati osservati durante l'esecuzione di dbt e lascia invariato il resto del gruppo di voci. Nessuna voce viene creata, eliminata o riassegnata e un aspetto il cui artefatto dbt era assente da questa esecuzione mantiene il valore assegnato da un'esecuzione precedente. Utilizza questo formato per l'importazione di routine e ripetuta. Vedi Esegui di nuovo l'importazione.
    • --validate-only: crea e carica il JSON e convalida il job dei metadati, ma non eseguire l'importazione.

  4. Verifica di aver ricevuto lo stato Creato.

REST

Per importare i metadati dbt utilizzando l'API REST:

  1. Genera gli artefatti dbt e trasformali nel file di importazione JSON di Knowledge Catalog (dbt_metadata.jsonl).
  2. Carica il file trasformato nel bucket di staging di Cloud Storage (gs://BUCKET_NAME/PATH/).

  3. Chiama il metodo projects.locations.metadataJobs.create:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

    Sostituisci quanto segue:

    • PROJECT_ID: l' Google Cloud ID progetto in cui si trova il gruppo di voci.
    • LOCATION: la regione del gruppo di voci (ad esempio us-central1).
    • JOB_ID: un identificatore univoco per il job di metadati.
    • BUCKET_NAME/PATH: il prefisso URI Cloud Storage in cui è stato caricato dbt_metadata.jsonl.
    • ENTRY_GROUP: l'ID breve del gruppo di voci di destinazione.

  4. Per monitorare lo stato del job di importazione, utilizza il metodo projects.locations.metadataJobs.get:

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

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 corse. Aggiorna solo ciò che l'esecuzione di dbt ha osservato e lascia tutto il resto nel gruppo di voci invariato, quindi è sicuro eseguire ripetutamente, in qualsiasi pianificazione e da più di un job.

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

  • La prima importazione in un gruppo di voci.
  • Una risorsa dbt viene aggiunta, rinominata o eliminata.
  • Modifica del nome visualizzato, della descrizione o delle etichette di una voce.
  • La gerarchia delle voci cambia.

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

Esegui --aspects-only per aggiornamenti di routine:

  • Dopo l'esecuzione del comando dbt della pipeline: dbt build, dbt test, dbt source freshness o una ricompilazione limitata a --select.
  • Una colonna viene aggiunta, rimossa, ridigitata o viene modificata la descrizione.
  • L'SQL del modello è stato modificato e l'esecuzione ha scritto anche catalog.json.
  • Nuovi risultati del test o aggiornamento della fonte.

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

Cercare e visualizzare i metadati di dbt

Console

  1. Nella console Google Cloud , vai alla pagina Knowledge Catalog Search.

    Vai a Cerca

  2. Nel riquadro Filtri, filtra gli asset dbt:

    • Nella sezione System (Sistema), seleziona Imported Context (Contesto importato).
    • Nella sottosezione Connettori gestiti visualizzata, seleziona dbt.

  3. Nel campo di ricerca, inserisci la query utilizzando la ricerca per parole chiave o in linguaggio naturale. Ad esempio, per visualizzare tutti gli asset dbt utilizzando la ricerca per parole chiave, inserisci system=DBT o system=DBT AND type=dbt-model.

  4. Nei risultati di ricerca, fai clic su una risorsa dbt per aprire la pagina dei dettagli della voce e visualizzare lo schema, la tracciabilità e gli aspetti tecnici.

gcloud

  1. Per cercare le voci dbt nel tuo progetto, utilizza il comando gcloud dataplex entries search:

    gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

    Per filtrare in base a un tipo di voce dbt specifico (ad esempio modelli o origini):

    gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

  2. Per visualizzare tutti i dettagli e gli aspetti di una voce dbt specifica, utilizza il comando gcloud dataplex entries lookup:

    gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • LOCATION: la posizione del gruppo di voci (ad esempio, us-central1).
    • ENTRY_GROUP: l'ID breve del gruppo di voci di destinazione (ad esempio, dbt-metadata-ingestion).
    • ENTRY_ID: l'ID breve o il nome della risorsa relativa della voce dbt.

REST

  1. Per cercare le voci dbt, chiama il metodo projects.locations:searchEntries:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

    Per filtrare in base a un tipo di risorsa dbt specifico:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

  2. Per recuperare i dettagli e gli aspetti completi dei metadati per una voce specifica, chiama il metodo projects.locations.entryGroups.entries.get:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

  3. Per recuperare il contesto LLM per risorse dbt specifiche, utilizza l'API projects.locations:lookupContext:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • LOCATION: la posizione del gruppo di voci (ad esempio, us-central1).
    • ENTRY_GROUP: l'ID breve del gruppo di voci di destinazione (ad esempio, dbt-metadata-ingestion).
    • ENTRY_ID: l'ID breve o il nome della risorsa relativa della voce dbt.

Per scoprire di più sulla ricerca delle risorse, consulta Cercare risorse in Knowledge Catalog. Per saperne di più su espressioni di query e filtri, consulta Sintassi di ricerca per Knowledge Catalog.

Limitazioni

  • Supporta le versioni recenti di dbt Core v1 (convalida 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 nidificati in profondità vengono troncati: un singolo aspetto non può superare il limite di dimensione per aspetto, quindi gli schemi nidificati in profondità potrebbero perdere i campi finali.
  • --aspects-only può aggiungere e aggiornare i metadati, ma non può rimuoverli. L'eliminazione di una risorsa dbt richiede un'esecuzione completa.
  • I link di accesso 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 esterne di terze parti non vengono acquisite nella derivazione dei dati.

Passaggi successivi