Importare i metadati da dbt Core

Knowledge Catalog (in precedenza Dataplex Universal Catalog) ti consente di importare metadati operativi, semantici e di derivazione da dbt Core, dbt Cloud e MetricFlow utilizzando Google Cloud CLI e i file degli artefatti dbt. Anziché lasciare i metadati di trasformazione isolati nell'ecosistema dbt, puoi centralizzarli per aiutare i data engineer, gli analytics engineer e i data steward a scoprire e gestire i dati aziendali.

Metadati importati e casi d'uso

Poiché dbt Core funziona come un motore di trasformazione anziché come un sistema di archiviazione come Oracle o PostgreSQL, l'importazione dei suoi metadati supporta diversi casi d'uso. Importi i metadati Oracle o PostgreSQL per rispondere alla domanda "Quali dati non elaborati abbiamo?" e importi i metadati dbt Core per rispondere alla domanda "Come vengono trasformati i nostri dati, sono affidabili e cosa significano per l'azienda?"

Quando esegui l'integrazione di dbt, acquisisci i seguenti metadati:

  • Metadati tecnici: scopri i dati aziendali esplorando le risorse chiave (origini, seed, modelli) e le relative proprietà tecniche (nomi delle colonne, tipi di dati, conteggi delle righe).
  • Metadati aziendali e semantici: forniscono il contesto per gli strumenti di BI e gli agenti AI esplorando le definizioni e la logica aziendali basate su dbt MetricFlow, come modelli semantici, metriche e query salvate.
  • Metadati operativi e di qualità dei dati: monitora lo stato della pipeline e risolvi i problemi relativi ai dati esplorando i metadati di esecuzione, come tempistiche, stato di esito positivo o negativo, aggiornamento dei dati e risultati dei test.
  • Metadati di derivazione e relazione: esegui l'analisi dell'impatto a valle e il tracciamento della causa principale esplorando i grafici di trasformazione (DAG) e le dipendenze tra le risorse dbt, la derivazione fisica che monitora e collega i blocchi di trasformazione fisica, le chiavi di join e i join dinamici e le relazioni padre-figlio.
  • Metadati di consumo: risolvi i problemi relativi al modo in cui le applicazioni downstream utilizzano i dati trasformati esplorando i metadati acquisiti nelle esposizioni che mappano il modo in cui i dati vengono utilizzati al di fuori di dbt.

Limitazioni

  • Supporta dbt Core v1 (convalidato con le versioni 1.11 e 1.12), dbt Core v2 e dbt Fusion.
  • La versione 586.0.0 e successive di gcloud CLI supportano l'integrazione di dbt e Knowledge Catalog. Per installare o aggiornare l'interfaccia a riga di comando, consulta Installa Google Cloud CLI.
  • Non esiste una connessione diretta a dbt Cloud. Per importare i metadati da un job dbt Cloud, recupera prima gli artefatti del job. Consulta Importa i metadati dalle esecuzioni di dbt Cloud.
  • Gli schemi molto grandi o con nidificazione profonda vengono troncati: un singolo aspetto non può superare il limite di dimensioni per aspetto, pertanto gli schemi con nidificazione profonda 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.
  • Questa integrazione supporta solo gli eventi di derivazione dbt sulle risorse BigQuery nell'API Data Lineage e nel grafico. Le voci dbt (origini, seed, modelli) per origini di terze parti esterne non vengono acquisite nella derivazione dei dati.

Prima di iniziare

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 Dataplex.
  3. Soddisfa i prerequisiti di dbt.
  4. Crea il gruppo di voci di destinazione se non esiste già.
  5. 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 gruppi di voci e link alle 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 dbt gcloud e creare job di importazione dei metadati: Segui il principio del privilegio minimo e concedi i seguenti ruoli:

    • Dataplex Metadata Job Owner (roles/dataplex.metadataJobOwner) sul progetto.
    • Dataplex Entry Group Importer (roles/dataplex.entryGroupImporter) sul gruppo di voci di destinazione o sul progetto. Se importi anche i link alle voci, concedi invece il ruolo Dataplex Entry Group Owner (roles/dataplex.entryGroupOwner) al progetto. Concedi anche il ruolo Dataplex Entry Owner (roles/dataplex.entryOwner) su ogni progetto che contiene le tabelle BigQuery in cui scrivono i tuoi modelli dbt. Per i ruoli personalizzati, le autorizzazioni per i link di accesso sono dataplex.entryGroups.useReferenceEntryLink, dataplex.entryGroups.useSchemaJoinEntryLink e dataplex.entryLinks.reference.

    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) sul 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) sul bucket degli artefatti di input. Se hai il ruolo Storage Object Admin, il ruolo Storage Object Viewer non è richiesto.

  • Per visualizzare i metadati dbt: Dataplex Catalog Viewer (roles/dataplex.catalogViewer) nel progetto.

  • Per visualizzare i log in Cloud Logging: Visualizzatore log (roles/logging.viewer) nel progetto.

Se disponi delle autorizzazioni necessarie per gestire l'accesso IAM nel tuo progetto, puoi concedere questi ruoli al tuo account utente eseguendo i seguenti comandi gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

Se esegui l'importazione utilizzando un account di servizio, ad esempio in una pipeline CI/CD automatizzata, puoi concedere questi ruoli al account di servizio eseguendo i seguenti comandi gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

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) sul 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:

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • USER_EMAIL: l'indirizzo email del tuo account utente.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del tuo account di servizio.
  • STAGING_BUCKET: il nome del bucket Cloud Storage di gestione temporanea di output (--storage-uri).
  • PROJECT_NUMBER: il tuo numero di progetto Google Cloud .

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

Abilita API

Abilitare l'API Dataplex.

Abilitare l'API

Prerequisiti dbt

Per importare l'intero set di metadati dbt, ti consigliamo di generare tutti e quattro i file degli artefatti JSON dbt. Solo manifest.json è obbligatorio; gli altri arricchiscono l'importazione e la trasformazione si degrada correttamente 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 non tipizzate.
  • run_results.json: risultati dei test e metadati di esecuzione.
  • sources.json: aggiornamento dell'origine.

Nel terminale locale, in Cloud Shell o nell'ambiente CI/CD automatizzato in cui è installato dbt, vai alla directory root del progetto dbt ed esegui i seguenti comandi dbt in ordine su un singolo profilo e target per generare il set completo di file JSON degli artefatti dei metadati dbt:

  • Per dbt Core 2.x e dbt Fusion:

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • Per dbt Core 1.x (dove dbt parse non scrive un catalogo):

    1. dbt source freshness
    2. dbt build

    3. dbt docs generate --no-compile

Informazioni sui ruoli di Cloud Storage

L'importazione dei metadati dbt prevede due posizioni Cloud Storage distinte 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/). Specifica 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. L'agente di servizio Knowledge Catalog non ha bisogno di accedere al bucket degli artefatti di input.
  • Output (bucket di gestione temporanea dell'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. Puoi fornire 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.

Importa i metadati dalle esecuzioni di dbt Cloud

Knowledge Catalog non si connette direttamente a dbt Cloud. Poiché un job dbt Cloud genera gli stessi file degli artefatti di dbt Core, puoi importare i metadati da dbt Cloud recuperando i file degli artefatti in una directory locale o in un bucket Cloud Storage di input ed eseguendo il comando gcloud.

Prima di recuperare gli artefatti, configura il job dbt Cloud per generare il set completo di artefatti. Puoi quindi recuperare i file degli artefatti da un'esecuzione di un job dbt Cloud utilizzando uno dei seguenti metodi:

Configura il job dbt Cloud

Nella console dbt Google Cloud , configura le impostazioni del job per generare l'insieme completo di artefatti dei metadati:

  1. Nella sezione Impostazioni di esecuzione, seleziona Esegui aggiornamento origine. dbt Cloud esegue dbt source freshness prima dei comandi del job per generare sources.json.
  2. Nella sezione Comandi, aggiungi dbt build.
  3. Aggiungi un comando per generare catalog.json in base al tuo canale di rilascio:
    • Per i canali di rilascio dbt Core 2.x e dbt Fusion: aggiungi dbt parse --write-catalog come comando del job.
    • Per i canali di rilascio dbt Core 1.x: aggiungi dbt docs generate --no-compile come comando del job anziché selezionare l'opzione Genera documenti durante l'esecuzione. La casella di controllo Genera documenti durante l'esecuzione esegue dbt docs generate senza --no-compile, il che sovrascrive i risultati del test da dbt build, come descritto in Prerequisiti di dbt. Tieni presente che se un passaggio del comando non va a buon fine, anche il job non va a buon fine, mentre il passaggio della casella di controllo non causa l'errore del job.

Se dbt build non va a buon fine, ad esempio perché un test non riesce, dbt Cloud salta i comandi successivi e l'esecuzione non ha catalog.json. Per produrne sempre uno, aggiungi il comando catalog prima di dbt build. Il catalogo descrive quindi le tabelle come erano prima della build.

Per saperne di più, consulta Comandi dei job e Canali di rilascio nella documentazione di dbt.

Scarica gli artefatti dalla console dbt Google Cloud

Per scaricare manualmente gli artefatti da un'esecuzione completata nella console dbtGoogle Cloud :

  1. Nella console dbt Google Cloud , apri l'esecuzione del job completata.
  2. Vai alla scheda Artefatti per visualizzare i file degli artefatti generati.
  3. Scarica manifest.json, catalog.json, run_results.json e sources.json in una directory locale.
  4. Nel terminale locale o in Cloud Shell, esegui il comando di importazione gcloud descritto in Configura la connettività dbt e imposta --artifacts-path sulla directory contenente i file scaricati.

Per saperne di più, consulta Visibilità dell'esecuzione nella documentazione di dbt.

Scarica gli artefatti utilizzando l'interfaccia a riga di comando della piattaforma dbt

La dbt platform CLI (in precedenza dbt Cloud CLI) esegue i comandi dbt sulla piattaforma dbt Cloud dal tuo terminale locale e scarica automaticamente gli artefatti generati nella directory target/ del tuo progetto dbt locale.

  1. Nel terminale locale, vai alla directory root del progetto dbt ed esegui i tre comandi elencati in Prerequisiti di dbt.
  2. Esegui il comando di importazione gcloud descritto in Configura la connettività dbt e imposta --artifacts-path sulla directory principale del progetto o sulla directory target/.

L'interfaccia a riga di comando viene eseguita all'interno del tuo ambiente di sviluppo utilizzando le tue credenziali personali del data warehouse, pertanto i metadati generati riflettono lo schema di sviluppo anziché le tabelle di produzione create da un job pianificato. Utilizza l'interfaccia a riga di comando per i flussi di lavoro di test o sviluppo e un job di deployment per le importazioni di produzione pianificate.

Per saperne di più, consulta Install the dbt platform CLI nella documentazione di dbt.

Scarica gli artefatti utilizzando l'API dbt Administrative

Puoi utilizzare l'API dbt Administrative per recuperare in modo programmatico gli artefatti da qualsiasi esecuzione di job completata. L'endpoint List Run Artifacts restituisce i percorsi dei file generati da un'esecuzione, mentre l'endpoint Retrieve Run Artifact scarica un file di artefatto specifico dal seguente URL:

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL dipende dalla regione che ospita il tuo account dbt Cloud. Autentica le richieste utilizzando un token del servizio dbt Cloud. Per saperne di più, consulta le seguenti pagine della documentazione di dbt:

Dal terminale locale, da Cloud Shell o dall'ambiente del workflow automatizzato, scarica manifest.json, catalog.json, run_results.json e sources.json in una directory locale o in un bucket Cloud Storage, quindi esegui il comando gcloud descritto in Configura la connettività dbt in quel percorso.

Per impostazione predefinita, l'endpoint degli artefatti restituisce gli artefatti del passaggio finale dell'esecuzione, a meno che non specifichi il parametro di query step. Quando configuri il job come descritto in Configura il job dbt Cloud, il passaggio finale è dbt parse --write-catalog o dbt docs generate --no-compile, che scrive solo catalog.json e lascia invariati gli altri tre artefatti nel passaggio predefinito.

Recupera l'ID esecuzione

Per scaricare gli artefatti di un'esecuzione specifica, devi avere il relativo ID esecuzione. Puoi copiare l'ID esecuzione dall'URL di esecuzione nella console dbt Google Cloud o eseguire una query sull'API dal terminale o dallo script del workflow per l'esecuzione riuscita più recente di un job:

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

Nei parametri di ricerca, status=10 filtra le esecuzioni completate con uno stato Success. Puoi eseguire il polling di questo endpoint in base a una pianificazione per identificare l'ultima esecuzione riuscita, scaricare i relativi artefatti ed eseguire il comando di importazione gcloud.

Attiva l'importazione utilizzando un webhook

Anziché eseguire il polling dell'API, puoi configurare un webhook dbt Cloud per attivare un'importazione automatica dei metadati ogni volta che viene completata l'esecuzione di un job. Il webhook invia un payload a un endpoint HTTP che fornisci:

  1. Nella console dbt Google Cloud , vai a Account settings (Impostazioni account) > Webhooks (Webhook) e fai clic su Create webhook (Crea webhook) (o Create new webhook (Crea nuovo webhook)). Configura la sottoscrizione al webhook:
    • Eventi: seleziona Esecuzione completata (job.run.completed), che si attiva solo al termine dell'esecuzione e quando i relativi artefatti sono disponibili per il download.
    • Job: seleziona i job di deployment dbt Cloud che vuoi monitorare.
    • Endpoint: inserisci l'URL HTTPS di un servizio che esegui (ad esempio un servizio Cloud Run o una funzione Cloud Run).
  2. Salva il token secret del webhook visualizzato da dbt Cloud. Il tuo servizio utilizza questo secret per verificare l'intestazione Authorization, che contiene una firma HMAC-SHA256 del corpo della richiesta.
  3. Nel tuo servizio, leggi data.runId dal payload JSON, scarica gli artefatti dell'esecuzione utilizzando l'API amministrativa come descritto in precedenza ed esegui il comando gcloud dataplex dbt metadata-jobs create.

Quando implementi il gestore del webhook, tieni presente quanto segue:

  • dbt Cloud attende al massimo 10 secondi per una risposta. Poiché l'importazione dei metadati richiede diversi minuti, restituisci prima una risposta HTTP ed esegui l'importazione in background (ad esempio, come job Cloud Run o con il flag --async).
  • job.run.completed si attiva anche per le esecuzioni non riuscite, quindi le esecuzioni con test non riusciti vengono comunque importate. Non sottoscrivere job.run.errored, perché può attivarsi prima che gli artefatti dell'esecuzione siano disponibili.

Per ulteriori informazioni sui payload dei webhook e sulla verifica della firma, consulta Webhook per i job nella documentazione di dbt.

Configura la connettività dbt

Per stabilire la connettività dbt, devi prima eseguire i comandi dbt appropriati per generare gli artefatti dei metadati. Una volta che i file JSON sono archiviati e accessibili, il processo di importazione esegue le seguenti azioni:

  1. Leggi gli 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 i metadati: trasforma i contenuti nel formato di importazione dei metadati di Knowledge Catalog (dbt_metadata.jsonl).
  3. Carica in gestione temporanea: carica il file di importazione dei metadati trasformati nella posizione Cloud Storage di gestione temporanea di output specificata in --storage-uri.
  4. Attiva il job di importazione: attiva un job di importazione dei metadati di Knowledge Catalog che indica all'agente di servizio di Knowledge Catalog di leggere e importare i metadati di gestione temporanea da --storage-uri nelle risorse di Knowledge Catalog.

Console

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

    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 di gestione temporanea dell'output con le autorizzazioni appropriate sia per il chiamante sia per l'agente di servizio Knowledge Catalog.

  3. Da Cloud Shell, da un terminale locale o da uno strumento di workflow automatico, esegui il comando gcloud:

    gcloud 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 avere l'accesso in scrittura (roles/storage.objectCreator o roles/storage.objectAdmin) e l'agente di servizio Knowledge Catalog deve avere l'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 directory root 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 da questa esecuzione dbt e lascia invariato il resto del gruppo di voci. Non viene creata, eliminata o ricollegata alcuna voce, non viene emesso alcun link alla voce e un aspetto il cui artefatto dbt era assente da questa esecuzione mantiene il valore assegnato da un'esecuzione precedente. Utilizza questa opzione per l'importazione di routine ripetuta. Consulta Esegui nuovamente l'importazione.
    • --include-entry-links: genera link di voci per le relazioni dbt. Questa opzione è attiva per impostazione predefinita. Per disattivarlo, utilizza --no-include-entry-links. Il comando genera i seguenti tipi di link di voci:
      • reference: una risorsa dipende da un'altra, la descrive o la utilizza. Sono incluse le dipendenze dbt tra i nodi, un test e la risorsa che testa, un modello semantico o una metrica e la risorsa su cui si basa, un nodo e le macro del progetto che chiama, nonché un nodo e la tabella BigQuery in cui si materializza.
      • schema-join: colonne unibili dichiarate da un test dbt relationships.
    • --skip-bigquery-link: salta i link reference (nodo dbt → tabella BigQuery fisica). Per impostazione predefinita, viene generato un link reference per ogni nodo dbt materializzato (modello, seed, snapshot) il cui set di dati BigQuery si trova nella località di importazione (--location). Le origini dbt non ricevono un link reference alla relativa tabella BigQuery. I link alle voci possono fare riferimento solo alle voci @bigquery nella stessa regione, quindi i set di dati in un'altra regione vengono ignorati automaticamente. Per determinare la regione di ogni set di dati, il comando chiama l'API BigQuery, pertanto il chiamante deve disporre dell'autorizzazione bigquery.datasets.get su questi set di dati. In caso contrario, il comando non può saltare i set di dati in altre regioni e i relativi link non vengono risolti. Quando le tabelle BigQuery non sono catalogate in Knowledge Catalog, utilizza --skip-bigquery-link.
    • --validate-only: crea e carica il JSON e convalida il job dei metadati, ma non esegue 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 gestione temporanea 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'ID progetto Google Cloud 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 dell'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 per le risorse che esistono già. Utilizza --aspects-only per queste esecuzioni. Aggiorna solo ciò che è stato osservato dall'esecuzione di dbt e lascia invariato tutto il resto nel gruppo di voci, quindi è sicuro eseguirlo ripetutamente, in base a qualsiasi pianificazione e da più di un job.

Esegui un'importazione completa (omettere --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.
  • Le dipendenze dbt cambiano, ad esempio quando viene aggiunta o rimossa una chiamata ref(), source(), test o macro. Le esecuzioni di --aspects-only non creano o aggiornano i link delle voci.
  • Modifichi --include-entry-links o --skip-bigquery-link.

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

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

  • Dopo l'esecuzione di un comando dbt della pipeline: dbt build, dbt test, dbt source freshness o una ricostruzione limitata a --select.
  • Una colonna viene aggiunta, rimossa, ridigitata o descritta nuovamente.
  • L'SQL del modello è 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

Console

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

    Vai alla Ricerca

  2. Nel riquadro Filtri, filtra in base agli asset dbt:

    • Nella sezione Sistema, seleziona 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 un asset dbt per aprire la relativa pagina dei dettagli della voce e visualizzarne lo schema, la derivazione e gli aspetti tecnici.

gcloud

  1. Per cercare voci dbt nel 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 i dettagli e gli aspetti completi 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 località 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 relativo alla 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 località 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 relativo alla voce dbt.

Per elencare i link di una voce dbt, chiama il metodo projects.locations:lookupEntryLinks. Ad esempio, per recuperare la tabella BigQuery in cui viene materializzato un modello dbt:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME è il nome completo della risorsa della voce dbt. I risultati sono impaginati, con un massimo di 10 link per pagina.

Per scoprire di più sulla ricerca di risorse, consulta Cerca risorse in Knowledge Catalog. Per scoprire di più sulle espressioni di query e sui filtri, consulta Sintassi di ricerca per Knowledge Catalog.

Passaggi successivi