Importar metadados do dbt Core

O Knowledge Catalog (antigo Dataplex Universal Catalog) permite importar metadados operacionais, semânticos e de linhagem do dbt Core, do dbt Cloud e do MetricFlow usando a Google Cloud CLI e seus arquivos de artefato do dbt. Em vez de deixar os metadados de transformação isolados no ecossistema do dbt, é possível centralizá-los para ajudar engenheiros de dados, engenheiros de análise e gestores de dados a descobrir e controlar dados corporativos.

Metadados importados e casos de uso

Como o dbt Core opera como um mecanismo de transformação, e não como um sistema de armazenamento, como o Oracle ou o PostgreSQL, a importação dos metadados dele é compatível com diferentes casos de uso. Você importa metadados do Oracle ou do PostgreSQL para responder à pergunta "Quais dados brutos temos?" e importa metadados do dbt Core para responder à pergunta "Como nossos dados são transformados, eles são confiáveis e o que eles significam para os negócios?"

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

  • Metadados técnicos: descubra dados corporativos explorando os principais recursos (fontes, sementes, modelos) e as propriedades técnicas deles (nomes de colunas, tipos de dados, contagens de linhas).
  • Metadados comerciais e semânticos: fornecem contexto para ferramentas de BI e agentes de IA, explorando definições e lógicas de negócios com tecnologia do 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 analisando metadados de execução, como tempo, status de sucesso ou falha, atualização de dados e resultados de testes.
  • Metadados de linhagem e relacionamento: realize análises de impacto downstream e rastreamento de causa raiz explorando 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 mesclagem e mesclagens dinâmicas e relacionamentos pai-filho.
  • Metadados de consumo: resolva problemas com a forma como os aplicativos downstream consomem dados transformados explorando 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), dbt Core v2 e dbt Fusion.
  • A CLI gcloud versão 586.0.0 e mais recentes oferecem suporte à integração do dbt e do Knowledge Catalog. Para instalar ou atualizar a CLI, consulte Instalar a Google Cloud CLI.
  • Não há conexão direta com o dbt Cloud. Para importar metadados de um job do dbt Cloud, primeiro receba os artefatos do job. Consulte Importar metadados de execuções do dbt Cloud.
  • Esquemas muito grandes ou profundamente aninhados são truncados: um único aspecto não pode exceder o limite de tamanho por aspecto, então esquemas profundamente aninhados podem perder campos finais.
  • --aspects-only pode adicionar e atualizar metadados, mas não pode removê-los. A exclusão de um recurso dbt requer uma execução completa.
  • Essa integração é compatível apenas com eventos de linhagem dbt em recursos do BigQuery na API Data Lineage e no gráfico. As entradas dbt (fontes, sementes, 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 seguintes tarefas:

  1. Conceda os papéis e as permissões necessários.
  2. Ativar a API Dataplex.
  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 concedem permissões para o Knowledge Catalog e o Cloud Storage.

Para receber as permissões necessárias para configurar um conector 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 projeto, poderá conceder esses papéis à sua própria 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 esses papéis à 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, é necessário conceder 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 do Cloud Storage de preparo de saída (--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

Ativar a API Dataplex.

Ativar a API

Pré-requisitos do dbt

Para importar o conjunto completo de metadados do dbt, recomendamos produzir todos os quatro arquivos de artefato JSON do dbt. Somente manifest.json é obrigatório. Os outros enriquecem a importação, e a transformação é degradada normalmente 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 de testes e metadados de execução.
  • sources.json: atualização da fonte.

No terminal local, no Cloud Shell ou no ambiente de CI/CD automatizado em que o dbt está instalado, acesse o diretório raiz do projeto do dbt e execute os seguintes comandos do dbt em um único perfil e destino para gerar o conjunto completo de arquivos JSON de artefatos 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 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 servem a propósitos diferentes e não devem ser confundidos:

  • Entrada (artefatos de origem do dbt): onde os arquivos JSON do dbt gerados estão. 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 do bucket do Cloud Storage de entrada (como gs://my-dbt-artifacts-bucket/target/). Forneça esse caminho usando a flag --artifacts-path. O comando gcloud lê esses arquivos de entrada durante a preparação do job. O autor da chamada 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 de importação do Knowledge Catalog): um prefixo de URI do 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 transformado (dbt_metadata.jsonl) e de onde o job de importação do Knowledge Catalog lê durante a ingestão. Forneça esse URI usando a flag --storage-uri. O autor da chamada 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 importá-lo.

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 que o dbt Core, é possível importar metadados do dbt Cloud recuperando esses arquivos de artefato 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, é possível recuperar 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 do dbt Google Cloud , defina as configuraçõ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 fonte. O dbt Cloud executa dbt source freshness antes dos comandos do 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 as 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. Se uma etapa de comando falhar, o job também falhará, mas a etapa de caixa de seleção não causará a falha do job.

Se dbt build falhar, por exemplo, devido a uma falha no teste, o dbt Cloud vai pular os comandos após ele, e a execução não terá catalog.json. Para sempre produzir um, adicione o comando de catálogo antes de dbt build. Em seguida, o catálogo descreve as tabelas como estavam antes do build.

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

Fazer o download de artefatos do console do dbt Google Cloud

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

  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 da 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 pelo terminal local e faz o download automático dos artefatos gerados no diretório target/ do projeto dbt local.

  1. No terminal local, acesse o diretório raiz do projeto do 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 ambiente de desenvolvimento usando suas credenciais pessoais do data warehouse. Assim, os metadados gerados refletem o 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 use 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 dbt Administrative

Use a API administrativa do dbt para recuperar de forma programática artefatos 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. Autentique 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 grava apenas 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. É possível copiar o ID da execução do URL de execução no console do dbt Google Cloud ou consultar a API no terminal ou no script de fluxo de trabalho para ver a execução bem-sucedida 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 as execuções concluídas com um status Success. É possível consultar esse endpoint de forma programada para identificar a execução bem-sucedida mais recente, fazer o download dos artefatos dela e executar o comando de importação gcloud.

Acionar a importação usando um webhook

Em vez de consultar a API, configure um webhook do dbt Cloud para acionar uma importação automática de metadados sempre que uma execução de job for concluída. O webhook envia um payload para um endpoint HTTP que você fornece:

  1. No console do dbt Google Cloud , acesse Configurações da conta > Webhooks e clique em Criar webhook (ou Criar novo webhook). Configure a assinatura do webhook:
    • Eventos: selecione Execução concluída (job.run.completed), que é acionada somente após o término da execução e quando os artefatos estão 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 do Cloud Run ou uma função do Cloud Run).
  2. Salve o token secreto do webhook que o dbt Cloud mostra. Seu serviço usa esse secret para verificar o cabeçalho Authorization, que contém uma assinatura HMAC-SHA256 do corpo da solicitação.
  3. No 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 dataplex dbt metadata-jobs create.

Ao implementar o 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, primeiro retorne uma resposta HTTP e execute a importação em segundo plano (por exemplo, como um job do Cloud Run ou com a flag --async).
  • job.run.completed também é acionado para execuções com falha, então as execuções com testes com falha ainda são importadas. Não se inscreva em 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 dbt apropriados 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 pelo MetricFlow no 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 o preparo: faça upload do arquivo de importação de metadados transformado para o local de preparo 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 do 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 ver os recursos do dbt importados, acesse a página Pesquisar ou a página de destino Grupos de entrada.

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 de preparo de saída do Cloud Storage 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 automatizada, execute o 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/

    Flags obrigatórias

    • --storage-uri=STORAGE_URI: prefixo do URI do Cloud Storage (saída/teste) (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 autor da chamada 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 em andamento.
    • --entry-group=ENTRY_GROUP: ID curto do grupo de entradas que recebe as entradas do dbt. Precisa já existir no projeto e no local (o padrão é dbt-metadata-ingestion).
    • --aspects-only: atualize apenas os metadados que essa execução do dbt observou e não altere o restante do grupo de entrada. Nenhuma entrada é criada, excluída ou reassociada, nenhum link de entrada é emitido e um aspecto com artefato dbt ausente dessa execução mantém o valor atribuído por uma execução anterior. Use essa opção para ingestão rotineira e repetida. Consulte Executar a ingestão novamente.
    • --include-entry-links: emite links de entrada para relações dbt. Essa opção fica ativada por padrão. Para desativá-lo, use --no-include-entry-links. O comando emite os seguintes tipos de link de entrada:
      • reference: um recurso depende, descreve ou usa outro. Isso abrange as dependências do dbt entre nós, um teste e o recurso que ele testa, um modelo semântico ou métrica e o recurso em que ele é criado, um nó e as macros do projeto que ele chama, e um nó e a tabela do BigQuery em que ele é materializado.
      • schema-join: colunas que podem ser mescladas declaradas por um teste relationships do dbt.
    • --skip-bigquery-link: pular links reference (nó dbt → tabela física do BigQuery). Por padrão, um link reference é emitido para cada nó dbt materializado (modelo, semente, snapshot) cujo conjunto de dados do BigQuery reside no local de importação (--location). As fontes dbt não recebem um link reference para a tabela do BigQuery. Os links de entrada só podem fazer referência a entradas do @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 autor da chamada precisa da permissão bigquery.datasets.get nesses conjuntos de dados. Sem ela, o comando não pode pular conjuntos de dados em outras regiões, e os links para eles não são resolvidos. Quando as tabelas do BigQuery não estiverem catalogadas no Knowledge Catalog, use --skip-bigquery-link.
    • --validate-only: cria e faz upload do JSON e valida o job de metadados, mas não faz 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 de importação JSON 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 do Google Cloud em que o grupo de entrada está localizado.
    • LOCATION: a região do grupo de entrada (por exemplo, us-central1).
    • JOB_ID: um identificador exclusivo para o job de metadados.
    • BUCKET_NAME/PATH: o prefixo de URI do Cloud Storage em que dbt_metadata.jsonl foi enviado.
    • ENTRY_GROUP: o ID curto do grupo de entrada de destino.

  4. Para acompanhar o status do 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 programa a primeira execução de acordo com sua configuração, ou você pode iniciá-lo 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 restante no grupo de entrada, de modo que é 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 entrada.
  • Um recurso 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 entrada muda.
  • As dependências do dbt mudam, por exemplo, quando uma chamada ref(), source(), de 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 os aspectos necessários de cada entrada dos artefatos no disco. Portanto, execute-a em 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 dbt que seu pipeline executar: dbt build, dbt test, dbt source freshness ou uma recriação restrita por --select.
  • Uma coluna é adicionada, removida, redigitada ou descrita novamente.
  • O SQL do modelo foi alterado, 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 pode removê-los.

Pesquisar e visualizar metadados do dbt

Console

  1. No console do 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 Conectores gerenciados 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 conferir o esquema, a linhagem e os aspectos técnicos.

gcloud

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

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

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

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

  2. Para ver todos os detalhes e aspectos de uma entrada dbt específica, 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 entrada (por exemplo, us-central1).
    • ENTRY_GROUP: o ID curto do grupo de entrada de destino (por exemplo, dbt-metadata-ingestion).
    • ENTRY_ID: o ID curto ou o nome relativo do recurso 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 dbt específico:

    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 detalhes e aspectos completos 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 para 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 entrada (por exemplo, us-central1).
    • ENTRY_GROUP: o ID curto do grupo de entrada de destino (por exemplo, dbt-metadata-ingestion).
    • ENTRY_ID: o ID curto ou o nome relativo do recurso da entrada do dbt.

Para listar os links de uma entrada do dbt, chame o método projects.locations:lookupEntryLinks. Por exemplo, para recuperar a tabela do BigQuery em que um modelo 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 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 e filtros de consulta, consulte Sintaxe de pesquisa do Knowledge Catalog.

A seguir