Importar metadados do dbt Core

Para engenheiros de dados, engenheiros de análise e gestores de dados, a centralização de metadados é essencial para a descoberta e a governança de dados empresariais. Quando as equipes usam o dbt para transformação de dados, metadados operacionais, semânticos e de linhagem valiosos são gerados, mas geralmente permanecem isolados no ecossistema do dbt.

Para integrar essas informações ao seu catálogo centralizado, importe metadados do dbt Core, do dbt Cloud e do MetricFlow para o Knowledge Catalog (antigo Dataplex Universal Catalog).

Como o dbt Core opera como um mecanismo de transformação em vez de um sistema de armazenamento, como o Oracle ou o PostgreSQL, a importação dos metadados dele permite diferentes casos de uso. Você importa metadados do Oracle ou do PostgreSQL para responder a "Quais dados brutos temos?" e metadados do dbt Core para responder a "Como nossos dados são transformados, são confiáveis e o que isso significa para a empresa?"

Neste documento, descrevemos como importar metadados usando o comando da Google Cloud CLI e seus arquivos de artefato do dbt.

Ao executar a integração do dbt, você captura os seguintes metadados:

  • Metadados técnicos: descubra dados corporativos explorando recursos principais (fontes, seeds, modelos) e propriedades técnicas (nomes de colunas, tipos de dados, contagens de linhas).
  • Metadados semânticos e de negócios: forneça contexto para ferramentas de BI e agentes de IA explorando definições e lógica de negócios com tecnologia dbt MetricFlow, como modelos semânticos, métricas e consultas salvas.
  • Metadados operacionais e de qualidade de dados: monitore a integridade do pipeline e resolva problemas de dados explorando metadados de execução, como tempo, status de sucesso ou falha, atualização de dados e resultados de testes.
  • Metadados de linhagem e relacionamento: permitem a análise de impacto downstream e o rastreamento da causa raiz ao explorar gráficos de transformação (DAGs) e dependências entre recursos do dbt, linhagem física que rastreia e vincula blocos de transformação física, chaves de junção e junções dinâmicas, além de relações pai-filho.
  • Metadados de consumo: resolva problemas com a forma como os aplicativos downstream consomem dados transformados analisando os metadados capturados em exposições que mapeiam como os dados são usados fora do dbt.

Limitações

  • Compatível com o dbt Core v1 (validado nas versões 1.11 e 1.12), o dbt Core v2 e o dbt Fusion.
  • A CLI gcloud versão 586.0.0 e mais recentes são compatíveis com a integração do dbt e do BigQuery. Para instalar ou atualizar a CLI, consulte Instalar a CLI do Google Cloud.
  • Não há conexão direta com o dbt Cloud. Para importar metadados de um job do dbt Cloud, primeiro extraia os artefatos do job. Consulte Importar metadados de execuções do dbt Cloud.
  • Esquemas muito grandes ou aninhados são truncados: um único aspecto não pode exceder o limite de tamanho por aspecto. Portanto, esquemas aninhados podem perder campos finais.
  • --aspects-only pode adicionar e atualizar metadados, mas não remover. A exclusão de um recurso do dbt exige uma execução completa.
  • Essa integração só é compatível com eventos de linhagem do dbt em recursos do BigQuery na API e no gráfico Data Lineage. As entradas do dbt (fontes, seeds, modelos) de fontes externas de terceiros não são capturadas na linhagem de dados.

Antes de começar

Antes de importar metadados do dbt Core e do MetricFlow, conclua as tarefas a seguir:

  1. Conceda os papéis e permissões necessários.
  2. Ative a API Knowledge Catalog.
  3. Atenda aos pré-requisitos do dbt.
  4. Crie o grupo de entrada de destino se ele ainda não existir.
  5. Entenda os papéis do Cloud Storage.

Permissões e papéis do IAM

Para criar e gerenciar um job de conector do Knowledge Catalog, você precisa de papéis do Identity and Access Management (IAM) que concedam permissões para o Knowledge Catalog e o Cloud Storage.

Para receber as permissões necessárias para configurar um conector do dbt, peça ao administrador para conceder a você os seguintes papéis do IAM:

Se você tiver as permissões necessárias para gerenciar o acesso do IAM no seu projeto, conceda esses papéis à sua conta de usuário executando os seguintes comandos 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 você executar a importação usando uma conta de serviço, como em um pipeline de CI/CD automatizado, conceda essas funções à conta de serviço executando os seguintes comandos 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"

Além disso, conceda ao agente de serviço do Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) o papel de Leitor de objetos do Storage (roles/storage.objectViewer) no bucket de preparação de saída do Cloud Storage (--storage-uri) para que o job de importação possa ler o arquivo de metadados preparado:

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"

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • USER_EMAIL: o endereço de e-mail da sua conta de usuário.
  • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da sua conta de serviço.
  • STAGING_BUCKET: o nome do bucket do Cloud Storage de preparo de saída (--storage-uri).
  • PROJECT_NUMBER: o número do projeto do Google Cloud .

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Ativar APIs

Ative a API Knowledge Catalog.

Ativar a API

Pré-requisitos do dbt

Para importar o conjunto completo de metadados do dbt, recomendamos gerar todos os quatro arquivos de artefato JSON do dbt. Apenas manifest.json é obrigatório. Os outros enriquecem a importação e a transformação é reduzida gradualmente sem eles:

  • manifest.json (obrigatório): estrutura principal do projeto e gráfico de execução. Também carrega os modelos semânticos, as métricas e as consultas salvas do MetricFlow.
  • catalog.json: nomes de colunas e tipos de dados. Sem catalog.json, o aspecto do esquema é importado com colunas sem tipo.
  • run_results.json: Resultados do teste e metadados de execução.
  • sources.json: Atualização da fonte.

No terminal local, no Cloud Shell ou no ambiente automatizado de CI/CD em que o dbt está instalado, acesse o diretório raiz do projeto dbt e execute os seguintes comandos em ordem em um único perfil e destino para gerar o conjunto completo de arquivos JSON de artefato de metadados do dbt:

  • Para dbt Core 2.x e dbt Fusion:

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • Para o dbt Core 1.x (em que dbt parse não grava um catálogo):

    1. dbt source freshness
    2. dbt build

    3. dbt docs generate --no-compile

Entender os papéis do Cloud Storage

A importação de metadados do dbt envolve dois locais distintos do Cloud Storage que têm finalidades diferentes e não devem ser confundidos:

  • Entrada (artefatos de origem do dbt): onde seus arquivos JSON do dbt gerados estão localizados. Pode ser um caminho de diretório local na sua máquina ou no executor de CI (como ./target/ ou .) ou um prefixo de URI de bucket do Cloud Storage de entrada (como gs://my-dbt-artifacts-bucket/target/). Você fornece esse caminho usando a flag --artifacts-path. O comando gcloud lê esses arquivos de entrada durante a preparação do job. O usuário que executa o comando gcloud precisa de acesso de leitura (roles/storage.objectViewer ou roles/storage.objectAdmin) se estiver usando o Cloud Storage. O agente de serviço do Knowledge Catalog não precisa de acesso ao bucket de artefatos de entrada.
  • Saída (bucket de preparo da importação do Knowledge Catalog): um prefixo de URI de bucket do Cloud Storage (como gs://my-staging-bucket/dbt-imports/) em que o comando gcloud faz upload do arquivo de importação de metadados transformados (dbt_metadata.jsonl) e de onde o job de importação do Knowledge Catalog lê durante a ingestão. Você fornece esse URI usando a flag --storage-uri. O usuário que executa o comando gcloud precisa de acesso de gravação (roles/storage.objectCreator ou roles/storage.objectAdmin) para fazer upload do arquivo, e o agente de serviço do Knowledge Catalog precisa de acesso de leitura (roles/storage.objectViewer) para importar.

Importar metadados de execuções do dbt Cloud

O Knowledge Catalog não se conecta diretamente ao dbt Cloud. Como um job do dbt Cloud gera os mesmos arquivos de artefato do dbt Core, é possível importar metadados do dbt Cloud recuperando esses arquivos para um diretório local ou um bucket do Cloud Storage de entrada e executando o comando gcloud.

Antes de recuperar os artefatos, configure o job do dbt Cloud para gerar o conjunto completo de artefatos. Em seguida, recupere os arquivos de artefato de uma execução de job do dbt Cloud usando um dos seguintes métodos:

Configurar o job do dbt Cloud

No console dbt Google Cloud , configure as definições do job para gerar o conjunto completo de artefatos de metadados:

  1. Na seção Configurações de execução, selecione Executar atualização da origem. O dbt Cloud executa dbt source freshness antes dos comandos de job para gerar sources.json.
  2. Na seção Comandos, adicione dbt build.
  3. Adicione um comando para gerar catalog.json com base na sua faixa de lançamento:
    • Para as faixas de lançamento do dbt Core 2.x e do dbt Fusion: adicione dbt parse --write-catalog como um comando de job.
    • Para faixas de lançamento do dbt Core 1.x: adicione dbt docs generate --no-compile como um comando de job em vez de selecionar a opção Gerar documentos na execução. A caixa de seleção Gerar documentos na execução executa dbt docs generate sem --no-compile, o que substitui os resultados do teste de dbt build, conforme descrito em pré-requisitos do dbt. Observação: se uma etapa de comando falhar, o job também vai falhar. Já a etapa de caixas de seleção não causa falha no job.

Se dbt build falhar, por exemplo, porque um teste falhou, o dbt Cloud vai pular os comandos depois dele, e a execução não terá catalog.json. Para sempre produzir um, adicione o comando do catálogo antes de dbt build. Em seguida, o catálogo descreve as tabelas como eram antes do build.

Para mais informações, consulte Comandos de job e Rastreamentos de lançamento na documentação do dbt.

Baixar artefatos do console dbt Google Cloud

Para fazer o download manual de artefatos de uma execução concluída no console Google Cloud do dbt:

  1. No console do dbt Google Cloud , abra a execução do job concluída.
  2. Acesse a guia Artefatos para conferir os arquivos de artefato gerados.
  3. Faça o download de manifest.json, catalog.json, run_results.json e sources.json para um diretório local.
  4. No terminal local ou no Cloud Shell, execute o comando de importação gcloud descrito em Configurar a conectividade do dbt e defina --artifacts-path como o diretório que contém os arquivos baixados.

Para mais informações, consulte Visibilidade de execução na documentação do dbt.

Baixar artefatos usando a CLI da plataforma dbt

A CLI da plataforma dbt (antiga CLI do dbt Cloud) executa comandos dbt na plataforma dbt Cloud do seu terminal local e baixa automaticamente os artefatos gerados no diretório target/ do seu projeto dbt local.

  1. No terminal local, acesse o diretório raiz do projeto dbt e execute os três comandos listados em Pré-requisitos do dbt.
  2. Execute o comando de importação gcloud descrito em Configurar a conectividade do dbt e defina --artifacts-path como a raiz do projeto ou o diretório target/.

A CLI é executada no seu ambiente de desenvolvimento usando suas credenciais pessoais do data warehouse. Assim, os metadados gerados refletem seu esquema de desenvolvimento, e não as tabelas de produção criadas por um job programado. Use a CLI para fluxos de trabalho de teste ou desenvolvimento e um job de implantação para importações de produção programadas.

Para mais informações, consulte Instalar a CLI da plataforma dbt na documentação do dbt.

Fazer o download de artefatos usando a API administrativa do dbt

Você pode usar a API administrativa do dbt para recuperar artefatos de maneira programática de qualquer execução de job concluída. O endpoint List Run Artifacts retorna os caminhos de arquivo gerados por uma execução, e o endpoint Retrieve Run Artifact faz o download de um arquivo de artefato específico do seguinte URL:

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

ACCESS_URL depende da região que hospeda sua conta do dbt Cloud. Autenticar solicitações usando um token de serviço do dbt Cloud. Para mais informações, consulte as seguintes páginas na documentação do dbt:

No terminal local, no Cloud Shell ou no ambiente de fluxo de trabalho automatizado, faça o download de manifest.json, catalog.json, run_results.json e sources.json para um diretório local ou um bucket do Cloud Storage e execute o comando gcloud descrito em Configurar a conectividade do dbt nesse caminho.

Por padrão, o endpoint de artefato retorna artefatos da etapa final da execução, a menos que você especifique o parâmetro de consulta step. Ao configurar o job conforme descrito em Configurar o job do dbt Cloud, a etapa final é dbt parse --write-catalog ou dbt docs generate --no-compile, que apenas grava catalog.json e deixa os outros três artefatos intactos na etapa padrão.

Recuperar o ID da execução

Para fazer o download dos artefatos de uma execução específica, você precisa do ID dela. Copie o ID da execução do URL no console do dbt Google Cloud ou consulte a API no terminal ou script de fluxo de trabalho para a execução mais recente de um job:

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

Nos parâmetros de consulta, status=10 filtra execuções concluídas com um status Success. É possível pesquisar esse endpoint em uma programação para identificar a última execução bem-sucedida, fazer o download dos artefatos e executar o comando de importação gcloud.

Acionar a importação usando um webhook

Em vez de fazer polling da API, configure um webhook do dbt Cloud para acionar uma importação automatizada de metadados sempre que uma execução de job for concluída. O webhook envia uma carga útil para um endpoint HTTP fornecido por você:

  1. No console do dbt Google Cloud , acesse Configurações da conta > Webhooks e clique em Criar webhook ou Criar novo webhook. Configure a inscrição no webhook:
    • Eventos: selecione Execução concluída (job.run.completed), que é acionada somente depois que a execução termina e os artefatos ficam disponíveis para download.
    • Jobs: selecione os jobs de implantação do dbt Cloud que você quer monitorar.
    • Endpoint: insira o URL HTTPS de um serviço que você executa (por exemplo, um serviço ou uma função do Cloud Run).
  2. Salve o token secreto do webhook que o dbt Cloud mostra. Seu serviço usa esse segredo para verificar o cabeçalho Authorization, que contém uma assinatura HMAC-SHA256 do corpo da solicitação.
  3. No seu serviço, leia data.runId do payload JSON, faça o download dos artefatos da execução usando a API administrativa, conforme descrito anteriormente, e execute o comando gcloud alpha dataplex dbt metadata-jobs create.

Ao implementar seu gerenciador de webhook, considere o seguinte:

  • O dbt Cloud aguarda no máximo 10 segundos por uma resposta. Como a importação de metadados leva vários minutos, retorne uma resposta HTTP primeiro e execute a importação em segundo plano (por exemplo, como um job do Cloud Run ou com a flag --async).
  • O job.run.completed também é acionado para execuções com falha. Portanto, as execuções com testes com falha ainda são importadas. Não se inscreva no job.run.errored, porque ele pode ser acionado antes que os artefatos da execução estejam disponíveis.

Para mais informações sobre payloads de webhook e verificação de assinatura, consulte Webhooks para seus jobs na documentação do dbt.

Configurar a conectividade do dbt

Para estabelecer a conectividade do dbt, primeiro execute os comandos apropriados do dbt para gerar os artefatos de metadados. Depois que os arquivos JSON são armazenados e ficam acessíveis, o processo de importação realiza as seguintes ações:

  1. Ler artefatos de entrada: leia os artefatos JSON gerados pelo dbt Core e pela MetricFlow do local de entrada (diretório local ou URI do Cloud Storage especificado em --artifacts-path).
  2. Transformar metadados: transforme o conteúdo no formato de importação de metadados do Knowledge Catalog (dbt_metadata.jsonl).
  3. Fazer upload para a área de teste: faça upload do arquivo de importação de metadados transformados para o local de teste de saída do Cloud Storage especificado em --storage-uri.
  4. Acionar job de importação: acione um job de importação de metadados do Knowledge Catalog que instrui o agente de serviço do Knowledge Catalog a ler e ingerir os metadados armazenados em --storage-uri nos recursos do Knowledge Catalog.

Console

  1. No console Google Cloud , acesse a página Conectores do Knowledge Catalog.

    Acessar "Conectores"

  2. Clique em Adicionar conexão.

  3. Na lista Conectores, selecione o card dbt Core e MetricFlow.

  4. Para conferir os recursos importados do dbt, acesse a página Pesquisar ou a página de Grupos de entradas de destino.

gcloud

Para criar um job de metadados do dbt, siga estas etapas:

  1. Verifique se os arquivos de artefato de metadados do dbt estão armazenados localmente ou em um bucket de entrada do Cloud Storage.
  2. Verifique se você tem um bucket do Cloud Storage de preparação de saída configurado com as permissões adequadas para o autor da chamada e o agente de serviço do Knowledge Catalog.

  3. No Cloud Shell, em um terminal local ou em uma ferramenta de fluxo de trabalho automatizado, execute o 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/

    Flags obrigatórias

    • --storage-uri=STORAGE_URI: prefixo do URI do Cloud Storage (saída/preparação) (gs://bucket/path/) em que o JSONL transformado é enviado e de onde o job de importação lê durante a ingestão. O autor da chamada precisa ter acesso de gravação (roles/storage.objectCreator ou roles/storage.objectAdmin), e o agente de serviço do Knowledge Catalog precisa ter acesso de leitura (roles/storage.objectViewer).

    Flags opcionais

    • --artifacts-path=ARTIFACTS_PATH: (entrada) caminho para os artefatos dbt de origem. Pode ser um caminho de diretório local (como . ou ./target) ou um prefixo de URI do Cloud Storage (como gs://my-bucket/dbt-artifacts/). Pode apontar para a raiz do projeto dbt (o subdiretório target/ é detectado automaticamente) ou diretamente para o diretório que contém manifest.json. O padrão é .. Se um URI do Cloud Storage for fornecido, o caller precisará ter acesso de leitura (roles/storage.objectViewer ou roles/storage.objectAdmin) ao bucket de entrada.
    • --async: retorna imediatamente, sem aguardar a conclusão da operação.
    • --entry-group=ENTRY_GROUP: ID abreviado do grupo de entradas que recebe as entradas do dbt. Precisa existir no projeto e no local (o padrão é dbt-metadata-ingestion).
    • --aspects-only: atualize apenas os metadados observados por esta execução do dbt e deixe o restante do grupo de entradas intacto. Nenhuma entrada é criada, excluída ou redefinida como principal, nenhum link de entrada é emitido, e um aspecto cujo artefato do dbt estava ausente desta execução mantém o valor que uma execução anterior atribuiu a ele. Use isso para ingestão rotineira e repetida. Consulte Executar a ingestão novamente.
    • --include-entry-links: emite links de entrada para relações do dbt. Essa opção fica ativada por padrão. Para desativar, use --no-include-entry-links. O comando emite os seguintes tipos de links de entrada:
      • reference: um recurso depende, descreve ou usa outro. Isso inclui dependências do dbt entre nós, um teste e o recurso que ele testa, um modelo semântico ou uma métrica e o recurso em que ele é criado, um nó e as macros de projeto que ele chama e um nó e a tabela do BigQuery em que ele é materializado.
      • schema-join: colunas combináveis declaradas por um teste relationships do dbt.
    • --skip-bigquery-link: pule os links reference (nó do dbt → tabela do BigQuery física). Por padrão, um link reference é emitido para cada nó materializado do dbt (modelo, seed, snapshot) cujo conjunto de dados do BigQuery está no local de importação (--location). As fontes do dbt não recebem um link reference para a tabela do BigQuery. Os links de entrada só podem fazer referência a entradas @bigquery na mesma região. Portanto, os conjuntos de dados em outra região são ignorados automaticamente. Para determinar a região de cada conjunto de dados, o comando chama a API BigQuery. Portanto, o usuário precisa da permissão bigquery.datasets.get nesses conjuntos. Sem ela, o comando não pode ignorar conjuntos de dados em outras regiões, e os links para eles não são resolvidos. Quando as tabelas do BigQuery não estão catalogadas no Knowledge Catalog, use --skip-bigquery-link.
    • --validate-only: crie e faça upload do JSON e valide o job de metadados, mas não faça a ingestão.

  4. Confirme se você recebeu o status Criado.

REST

Para importar metadados do dbt usando a API REST:

  1. Gere os artefatos do dbt e transforme-os no arquivo JSON de importação do Knowledge Catalog (dbt_metadata.jsonl).
  2. Faça upload do arquivo transformado para o bucket de preparo do Cloud Storage (gs://BUCKET_NAME/PATH/).

  3. Chame o método 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"
          ]
        }
      }
    }'

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud em que seu grupo de entradas está localizado.
    • LOCATION: a região do seu grupo de entradas (por exemplo, us-central1).
    • JOB_ID: um identificador exclusivo para o job de metadados.
    • BUCKET_NAME/PATH: o prefixo do URI do Cloud Storage em que dbt_metadata.jsonl foi enviado.
    • ENTRY_GROUP: o ID abreviado do grupo de entradas de destino.

  4. Para acompanhar o status do seu job de importação, use o método 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

Depois de criar o job, o Knowledge Catalog agenda a primeira execução de acordo com sua configuração, ou você pode iniciá-la manualmente.

Executar a ingestão novamente

Após a primeira importação, a maioria das execuções só precisa atualizar os metadados dos recursos que já existem. Use --aspects-only para essas execuções. Ele atualiza apenas o que a execução do dbt observou e deixa todo o resto no grupo de entrada sozinho. Por isso, é seguro executar repetidamente, em qualquer programação e em mais de um job.

Execute uma ingestão completa (omita --aspects-only) quando o conjunto de entradas mudar:

  • A primeira ingestão em um grupo de entradas.
  • Um recurso do dbt é adicionado, renomeado ou excluído.
  • O nome de exibição, a descrição ou os rótulos de uma entrada mudam.
  • A hierarquia de entradas muda.
  • As dependências do dbt mudam, por exemplo, quando uma chamada de ref(), source(), teste ou macro é adicionada ou removida. As execuções de --aspects-only não criam nem atualizam links de entrada.
  • Você muda --include-entry-links ou --skip-bigquery-link.

Uma execução completa reescreve todos os aspectos necessários de cada entrada dos artefatos no disco. Portanto, execute-a com um conjunto de artefatos o mais completo possível que seu pipeline possa produzir.

Execute --aspects-only para atualizações de rotina:

  • Depois de qualquer comando do dbt que o pipeline execute: dbt build, dbt test, dbt source freshness ou uma recriação --select.
  • Uma coluna é adicionada, removida, redigitada ou redescrita.
  • O SQL do modelo mudou, e a execução também gravou catalog.json.
  • Novos resultados de teste ou atualização da fonte.

--aspects-only pode adicionar e atualizar metadados, mas não remover.

Pesquisar e ver metadados do dbt

Console

  1. No console Google Cloud , acesse a página Pesquisa do Knowledge Catalog.

    Acesse Pesquisar

  2. No painel Filtros, filtre os recursos do dbt:

    • Na seção Sistema, selecione Contexto importado.
    • Na subseção Managed Connectors que aparece, selecione dbt.

  3. No campo de pesquisa, digite sua consulta usando palavras-chave ou pesquisa com linguagem natural. Por exemplo, para ver todos os recursos do dbt usando a pesquisa por palavra-chave, digite system=DBT ou system=DBT AND type=dbt-model.

  4. Nos resultados da pesquisa, clique em qualquer recurso do dbt para abrir a página de detalhes da entrada e ver o esquema, a linhagem e os aspectos técnicos.

gcloud

  1. Para pesquisar entradas do dbt em todo o projeto, use o comando gcloud dataplex entries search:

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

    Para filtrar por um tipo de entrada específico do dbt (como modelos ou fontes):

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

  2. Para conferir todos os detalhes e aspectos de uma entrada específica do dbt, use o comando gcloud dataplex entries lookup:

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

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • LOCATION: o local do grupo de entradas (por exemplo, us-central1).
    • ENTRY_GROUP: o ID abreviado do grupo de entradas de destino (por exemplo, dbt-metadata-ingestion).
    • ENTRY_ID: o ID abreviado ou o nome do recurso relativo da entrada do dbt.

REST

  1. Para pesquisar entradas do dbt, chame o método 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"
    }'

    Para filtrar por um tipo de recurso específico do dbt:

    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. Para recuperar todos os detalhes e aspectos de metadados de uma entrada específica, chame o método 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. Para recuperar o contexto do LLM de recursos específicos do dbt, use a 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"
      ]
    }'

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • LOCATION: o local do grupo de entradas (por exemplo, us-central1).
    • ENTRY_GROUP: o ID abreviado do grupo de entradas de destino (por exemplo, dbt-metadata-ingestion).
    • ENTRY_ID: o ID abreviado ou o nome do recurso relativo da entrada do dbt.

Para listar os links de entrada de uma entrada do dbt, chame o método projects.locations:lookupEntryLinks. Por exemplo, para recuperar a tabela do BigQuery em que um modelo do dbt é materializado:

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 é o nome completo do recurso da entrada do dbt. Os resultados são paginados, com no máximo 10 links por página.

Para saber mais sobre como pesquisar recursos, consulte Pesquisar recursos no Knowledge Catalog. Para saber mais sobre expressões de consulta e filtros, consulte Sintaxe de pesquisa do Knowledge Catalog.

A seguir