Importar metadados do dbt Core

Neste documento, descrevemos como importar metadados do dbt Core e do MetricFlow para o Knowledge Catalog (antigo Dataplex Universal Catalog) usando o comando gcloud.

Os seguintes metadados são capturados pela integração do dbt:

  • Metadados técnicos: incluem 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: com tecnologia dbt MetricFlow, isso inclui definições e lógica de negócios, como modelos semânticos, métricas e consultas salvas.
  • Metadados operacionais e de qualidade de dados: incluem metadados de execução, como tempo, status de sucesso ou falha, atualização de dados, testes e resultados de testes.
  • Metadados de linhagem e relacionamento: incluem 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: incluem metadados capturados em exposições que mapeiam como os dados estão sendo usados fora do dbt.

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:

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.

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.

Para gerar o conjunto completo de arquivos JSON de artefato de metadados do dbt, execute os seguintes comandos do dbt nesta ordem:

  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.

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, e um aspecto cujo artefato 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.
    • --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.

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 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.

Limitações

  • Compatível com as versões recentes do dbt Core v1 (validadas nas versões 1.11 e 1.12). O dbt Core v2 e o dbt Fusion não são compatíveis.
  • Modelos do dbt que usam controle de versões de modelos são indisponíveis.
  • O dbt Cloud não é compatível.
  • Esquemas muito grandes ou profundamente aninhados são truncados: um único aspecto não pode exceder o limite de tamanho por aspecto. Portanto, esquemas profundamente 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.
  • Não é possível usar links de entrada.
  • Essa integração só é compatível com eventos de linhagem do dbt em recursos do BigQuery na API e no gráfico da Linhagem de dados. As entradas do dbt (origem, seeds, modelos) para fontes externas de terceiros não são capturadas na linhagem de dados.

A seguir