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, sementes, modelos) e as propriedades técnicas deles (nomes de colunas, tipos de dados, contagens de linhas).
  • Metadados semânticos e empresariais: com tecnologia do dbt MetricFlow, este 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 e 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 seguintes tarefas:

  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 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 preparo 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 produzir todos os quatro arquivos de artefato JSON do dbt. Apenas 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 contém os modelos semânticos, métricas e consultas salvas do MetricFlow.
  • catalog.json: nomes de colunas e tipos de dados. Sem catalog.json, o aspecto do esquema é importado com colunas não tipadas.
  • run_results.json: resultados de testes e metadados de execução.
  • sources.json: atualização da origem.

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 atendem a finalidades diferentes e não devem ser confundidos:

  • Entrada (artefatos de origem do dbt): onde os arquivos JSON do dbt gerados residem. Esse pode ser um caminho de diretório local na máquina ou no executor de CI (como ./target/ ou .) ou um prefixo de URI de bucket de entrada do Cloud Storage (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 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 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 do qual o job de importação do Knowledge Catalog lê durante a ingestão. Você fornece 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.

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 forem armazenados e acessíveis, você poderá usar o comando gcloud alpha dataplex dbt metadata-jobs create para:

  1. Ler artefatos de entrada: leia os artefatos JSON gerados pelo dbt Core e pelo 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 o preparo: faça upload do arquivo de importação de metadados transformados para o local de preparo de saída do Cloud Storage especificado em --storage-uri.
  4. Acionar o 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 preparados de --storage-uri nos recursos do Knowledge Catalog.

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 preparo 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 automatizada, 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: (saída/preparo) prefixo de URI do Cloud Storage (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 de origem do dbt. Esse 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 do 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 esperar que a operação em andamento seja concluída.
    • --entry-group=ENTRY_GROUP: ID abreviado do grupo de entrada que recebe as entradas do dbt. Já precisa existir no projeto e no local (o padrão é dbt-metadata-ingestion).
    • --aspects-only: atualiza apenas os metadados observados por essa execução do dbt e deixa o restante do grupo de entrada intacto. Nenhuma entrada é criada, excluída ou reparentada, e um aspecto cujo artefato do dbt estava ausente dessa execução mantém o valor que uma execução anterior forneceu. Use isso para ingestão rotineira e repetida. Consulte Executar a ingestão novamente.
    • --validate-only: cria e faz upload do JSON e valida o job de metadados, mas não ingere.

  4. Confirme se você recebeu um status Criado.

  5. Depois de criar o job, o Knowledge Catalog agenda a primeira execução de acordo com a 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. Portanto, é 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 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 entrada muda.

Uma execução completa reescreve os aspectos necessários de cada entrada dos artefatos no disco. Portanto, execute-o de 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 seu pipeline executar: dbt build, dbt test, dbt source freshness ou uma recriação restrita por --select.
  • Uma coluna é adicionada, removida, redigitada ou redescrita.
  • O SQL do modelo foi alterado e a execução também gravou catalog.json.
  • Novos resultados de testes ou atualização de origem.

--aspects-only pode adicionar e atualizar metadados, mas não pode removê-los.

Pesquisar e visualizar metadados do dbt

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

    Acesse Pesquisar

  2. No painel Filtros, é possível filtrar recursos do dbt usando as seções Projeto, Sistema e Pseudônimos de tipo. Na seção Sistema, selecione Contexto importado. A seleção desse filtro abre uma subseção Conectores gerenciados. Selecione dbt para filtrar todos os metadados do dbt.

  3. É possível usar o campo de pesquisa para realizar consultas de pesquisa. Você pode realizar uma pesquisa por palavras-chave ou linguagem natural. Por exemplo, para visualizar todos os recursos do dbt por pesquisa de palavras-chave, insira system=DBT.

    Para saber mais sobre como pesquisar recursos, consulte Pesquisar recursos no Knowledge Catalog. Para saber mais sobre as expressões que podem ser usadas no campo de pesquisa, consulte Sintaxe de pesquisa do Knowledge Catalog.

  4. Também é possível usar a LookupContext API para recuperar o contexto do LLM para recursos específicos do dbt.

Limitações

  • Oferece suporte a 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.
  • Os modelos do dbt que usam o controle de versões do modelo 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 pode removê-los. A exclusão de um recurso do dbt exige uma execução completa.
  • Os links de entrada não são compatíveis.
  • Essa integração oferece suporte apenas a eventos de linhagem do dbt em recursos do BigQuery na API Data Lineage e no gráfico. As entradas do dbt (origem, sementes, modelos) para fontes externas de terceiros não são capturadas na linhagem de dados.

A seguir