Gerenciar pipelines

Os pipelines do BigQuery permitem inspecionar o histórico de execução, configurar alertas de falha e controlar recursos de código com tecnologia do Dataform. Também é possível enriquecer os metadados do fluxo de trabalho no Knowledge Catalog para monitorar a qualidade de dados e excluir fluxos de trabalho obsoletos para manter seu projeto organizado. Dependendo de onde sua equipe armazena o código, é possível acessar pipelines em Arquivos e pastas, incluindo pastas de usuários e de equipe, ou em repositórios Git do BigQuery Studio (pastas Git) (pré-lançamento).

Antes de começar

  1. Crie um pipeline do BigQuery.
  2. Para gerenciar metadados de pipeline no Knowledge Catalog, verifique se a API Dataplex está ativada no seu projeto do Google Cloud .

Funções exigidas

Para receber as permissões necessárias para gerenciar pipelines, peça ao administrador que conceda a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre o IAM do Dataform, consulte Controlar o acesso com o IAM. Para mais informações sobre papéis para pastas, consulte Criar e gerenciar pastas. Para mais informações sobre papéis para repositórios Git, consulte Gerenciar código com repositórios Git do BigQuery Studio.

Se você usa uma conta de serviço personalizada para executar pipelines, precisa conceder os seguintes papéis a ela:

Ver pipelines

É possível visualizar e inspecionar pipelines armazenados em pastas ou pastas do Git no painel Arquivos. É possível conferir pipelines independentes e pipelines armazenados em pastas no painel Explorer. Os pipelines armazenados em pastas do Git não são exibidos no painel Explorer.

Ver pipelines no painel "Arquivos"

Os pipelines armazenados em pastas ou em pastas do Git aparecem diretamente no painel Arquivos.

Para visualizar um pipeline armazenado em uma pasta ou pasta do Git, siga estas etapas:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No painel à esquerda, clique em Arquivos para abrir o navegador de arquivos.

    Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

  3. Expanda a pasta Usuário, uma pasta de equipe ou uma pasta de repositório Git conectada.

    Os pipelines são exibidos com um ícone de Pipeline em vez de um ícone de pasta padrão.

  4. Clique em uma pasta de pipeline para abrir o Visualizador de pipeline.

    O Pipeline Viewer exibe o gráfico acíclico dirigido (DAG) compilado das tarefas do pipeline, o status de execução e as guias de configuração.

  5. Expanda o diretório do pipeline no navegador de arquivos para navegar pelos diretórios aninhados (como definitions/) e pelos arquivos de tarefas individuais.

Ver pipelines no painel do Explorer

Para ver uma lista de pipelines independentes e pipelines armazenados em pastas, faça o seguinte:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

    Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

  3. No painel Explorer, expanda o projeto e clique em Pipelines.

  4. Selecione um pipeline para abri-lo no Pipeline Viewer.

Conferir execuções manuais anteriores

Para conferir as execuções manuais anteriores de um pipeline selecionado, siga estas etapas:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

  3. No painel Explorer, expanda o projeto, clique em Pipelines e selecione um pipeline.

  4. Clique em Execuções.

  5. Opcional: para atualizar a lista de execuções anteriores, clique em Atualizar.

Configurar alertas para execuções de pipeline com falha

Cada pipeline tem um ID de repositório do Dataform correspondente. Cada execução do pipeline do BigQuery é registrada no Cloud Logging usando o ID do repositório do Dataform correspondente. Você pode usar o Cloud Monitoring para observar tendências nos registros do Cloud Logging para execuções de pipeline do BigQuery e receber notificações quando as condições descritas ocorrerem.

Para receber alertas quando uma execução de pipeline do BigQuery falhar, crie uma política de alertas com base em registros para o ID de repositório do Dataform correspondente. Para instruções, consulte Configurar alertas para invocações de fluxo de trabalho com falha.

Para encontrar o ID do repositório do Dataform do seu pipeline, faça o seguinte:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

  3. No painel Explorer, expanda o projeto, clique em Pipelines e selecione um pipeline.

  4. Clique em Configurações.

    O ID do repositório do Dataform do seu pipeline é exibido na parte de baixo da guia Configurações.

Excluir um pipeline

Para excluir um pipeline permanentemente, siga estas etapas:

  1. No console do Google Cloud , acesse a página BigQuery. Acessar o BigQuery

  • Para excluir um pipeline armazenado em uma pasta ou pasta do Git, faça o seguinte:

    1. No painel à esquerda, clique em Arquivos.

    2. Na árvore de arquivos, encontre a pasta do pipeline que você quer excluir.

    3. Clique em Ver ações ao lado da pasta do pipeline e clique em Excluir.

    4. Na caixa de diálogo de confirmação, clique em Excluir.

      A pasta do pipeline e todas as tarefas e arquivos contidos nela são excluídos do seu espaço de trabalho.

  • Para excluir um pipeline listado no painel Explorer, faça o seguinte:

    1. No painel à esquerda, clique em Explorer:

      Botão destacado para o painel "Explorer".

    2. No painel Explorer, expanda o projeto e clique em Pipelines.

    3. Encontre o pipeline que você quer excluir.

    4. Clique em Ver ações ao lado do pipeline e clique em Excluir.

    5. Clique em Excluir.

Gerenciar metadados no Knowledge Catalog

O Knowledge Catalog permite armazenar e gerenciar metadados de pipelines. Os pipelines estão disponíveis no Knowledge Catalog por padrão, sem configuração adicional.

É possível usar o Knowledge Catalog para gerenciar pipelines em todos os locais de pipeline. O gerenciamento de pipelines no Knowledge Catalog está sujeito às cotas e limites do Knowledge Catalog e aos preços do Knowledge Catalog.

O Knowledge Catalog recupera automaticamente os seguintes metadados dos pipelines:

  • Nome do recurso de dados
  • Ativo de dados pai
  • Local do recurso de dados
  • Tipo de recurso de dados
  • Projeto do Google Cloud correspondente

O Knowledge Catalog registra pipelines como entradas com os seguintes valores:

Grupo de entradas do sistema
O grupo de entrada do sistema para pipelines é @dataform. Para conferir detalhes das entradas de pipeline no Knowledge Catalog, acesse o grupo de entradas do sistema dataform. Para instruções sobre como ver uma lista de todas as entradas em um grupo de entradas, consulte Ver detalhes de um grupo de entradas na documentação do Knowledge Catalog.
Tipo de entrada do sistema
O tipo de entrada do sistema para pipelines é dataform-code-asset. Para ver detalhes de pipelines, é necessário visualizar o tipo de entrada do sistema dataform-code-asset, filtrar os resultados com um filtro baseado em aspecto e definir o campo type dentro do aspecto dataform-code-asset como WORKFLOW. Em seguida, selecione uma entrada do pipeline selecionado. Para instruções sobre como ver detalhes de um tipo de entrada selecionado, consulte Ver detalhes de um tipo de entrada na documentação do Knowledge Catalog. Para instruções sobre como ver detalhes de uma entrada selecionada, consulte Ver detalhes de uma entrada na documentação do Knowledge Catalog.
Tipo de aspecto do sistema
O tipo de aspecto do sistema para pipelines é dataform-code-asset. Para fornecer mais contexto aos pipelines no Knowledge Catalog anotando as entradas de pipeline de dados com aspectos, visualize o tipo de aspecto dataform-code-asset, filtre os resultados com um filtro baseado em aspecto e defina o campo type dentro do aspecto dataform-code-asset como WORKFLOW. Para instruções sobre como anotar entradas com aspectos, consulte Gerenciar aspectos e enriquecer metadados na documentação do Knowledge Catalog.
Tipo
O tipo de telas de dados é WORKFLOW. Esse tipo permite filtrar pipelines no tipo de entrada do sistema dataform-code-asset e no tipo de aspecto dataform-code-asset usando a consulta aspect:dataplex-types.global.dataform-code-asset.type=WORKFLOW em um filtro baseado em aspecto.

Para instruções sobre como pesquisar recursos no Knowledge Catalog, consulte Pesquisar recursos de dados no Knowledge Catalog na documentação do Knowledge Catalog.

Enriquecimento de metadados e integração de scorecard de qualidade de dados

O Dataform pode publicar os seguintes metadados no Knowledge Catalog:

  • Tipo de aspecto de visão geral
  • Tipo de aspecto genérico
  • Tipo de aspecto da tabela de qualidade de dados

As declarações do Dataform são integradas automaticamente ao boletim de qualidade de dados do Knowledge Catalog. Durante a execução do pipeline, os resultados de todas as declarações do Dataform são publicados automaticamente no Knowledge Catalog. Esses resultados preenchem o quadro de avaliação de qualidade de dados do Knowledge Catalog com um status de aprovação ou reprovação.

Para verificar o status de uma atualização de metadados, siga as instruções em Ver execuções manuais anteriores.

Depois que os metadados forem sincronizados, será possível pesquisar e visualizar a entrada no Knowledge Catalog. Para mais informações, consulte Pesquisar recursos.

Rastrear linhagem de dados

O BigQuery informa a linhagem de dados no nível da tabela ao Knowledge Catalog para as ações executadas no pipeline do BigQuery. Para cada ação executada, o gráfico de linhagem no BigQuery e no Knowledge Catalog mostra um processo entre as tabelas que a ação lê e a tabela em que ela grava. Não é necessário alterar os arquivos SQLX para informar a linhagem.

Tabelas, visualizações, tabelas incrementais, visualizações materializadas, declarações, gráficos de propriedades, preparações de dados e operações com hasOutput: true informam a linhagem de tabela para tabela. As operações sem hasOutput: true informam apenas o processo e a execução. Declarações, notebooks e testes de unidade SQL não informam a linhagem. As declarações aparecem apenas como entradas para outras ações.

A linhagem de relatórios nunca causa falhas na execução de um pipeline. Se a API Data Lineage estiver desativada, uma permissão estiver ausente ou uma cota for excedida, a execução do pipeline vai continuar sem informar a linhagem.

A ingestão de linhagem de dados é faturada de acordo com a SKU de processamento premium do Knowledge Catalog, e somente os eventos que gravam links de linhagem de tabela para tabela são faturados. O armazenamento de linhagem de dados é faturado de acordo com a SKU de armazenamento de metadados. Para mais informações, consulte Preços do Knowledge Catalog.

Limitações da linhagem de dados

A linhagem de dados para pipelines está sujeita às seguintes limitações:

  • Somente a linhagem no nível da tabela é informada. A linhagem no nível da coluna não é informada.

  • Os relatórios de linhagem de dados estão sujeitos às cotas da API Data Lineage para gravações por projeto, identidade e região.

Ativar a linhagem de dados

Para ativar a linhagem de dados no pipeline, siga estas etapas:

  1. Ative a API Data Lineage (datalineage.googleapis.com) no projeto que contém o pipeline e no projeto em que os usuários visualizam a linhagem.

  2. No projeto que contém o pipeline, conceda o papel de produtor de eventos de linhagem de dados (roles/datalineage.producer) à identidade que executa o pipeline. Essa identidade é a conta de serviço personalizada do pipeline ou o agente de serviço do Dataform (service-PROJECT_NUMBER@gcp-sa-dataform.) se nenhuma conta de serviço personalizada estiver definida.

  3. No arquivo workflow_settings.yaml do pipeline, adicione o seguinte bloco lineage:

    lineage:
  enabled: true

As execuções de pipeline que usam credenciais de usuário final para uma Conta do Google não informam a linhagem. Para informar a linhagem, execute o pipeline com uma conta de serviço personalizada.

Para interromper os relatórios de linhagem de dados de um pipeline, defina enabled como false no bloco lineage. Para interromper os relatórios de linhagem de dados de um projeto inteiro, desative a API Data Lineage no projeto. A desativação da API também interrompe os relatórios de linhagem de dados de outros serviços no projeto.

Ver linhagem de dados

Para visualizar a linhagem de dados de uma tabela produzida por uma ação de pipeline, siga estas etapas:

  1. No Google Cloud console, acesse o BigQuery Studio.

    Acessar o BigQuery Studio

  2. No painel Explorer, expanda o projeto e o conjunto de dados e selecione uma tabela produzida por uma ação de pipeline.

  3. Clique na guia Linhagem.

  4. Para conferir a ação, o pipeline e as execuções, selecione o nó do processo.

  5. Para abrir o pipeline, clique em Abrir no Dataform.

Para mais informações sobre como navegar em gráficos de linhagem, consulte Ver a linhagem de dados no Knowledge Catalog.

Resolver problemas de linhagem de dados

A tabela a seguir descreve problemas comuns de linhagem de dados para pipelines e como corrigi-los:

Sintoma Causa provável Corrigir
A guia Lineage não mostra nós de processo de pipeline. A API Data Lineage está desativada. Ative a API no projeto que contém o pipeline e no projeto em que você visualiza a linhagem.
Um pipeline não informa a linhagem. A identidade que executa o pipeline não tem o papel de produtor de eventos de linhagem de dados. Conceda roles/datalineage.producer à conta de serviço personalizada ou ao agente de serviço do Dataform.
As execuções de pipeline que usam credenciais de usuário final não informam a linhagem. Os relatórios de linhagem não são compatíveis com credenciais de usuário final. Execute o pipeline com uma conta de serviço personalizada.
Um pipeline não informa a linhagem, embora o papel seja concedido. O Dataform não pode atuar como a conta de serviço personalizada. Conceda ao agente de serviço do Dataform o papel de criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço personalizada.
Um pipeline não informa a linhagem. O pipeline foi desativado. Remova lineage.enabled: false de workflow_settings.yaml
A linhagem está ausente em algumas execuções. A cota da API Data Lineage foi excedida. Distribua as execuções do pipeline ou solicite uma cota maior.
Clicar em Abrir no Dataform retorna um erro de permissão. O usuário não tem acesso ao pipeline. Conceda ao usuário o papel de Leitor do Dataform (roles/dataform.viewer).

Após o primeiro erro de permissão ou de API em uma execução de pipeline, o BigQuery para de informar a linhagem para o restante dessa execução. A próxima execução do pipeline tenta informar a linhagem novamente.

Para verificar se uma execução de pipeline informou a linhagem, confira as entradas de registro dataform.googleapis.com/lineage_emission no Cloud Logging. Para filtrar relatórios de linhagem ignorados ou com falha na Análise de registros, execute a seguinte consulta:

log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")

A seguir