Visão geral do agente de engenharia de dados

O agente de engenharia de dados permite criar, modificar e solucionar problemas de pipelines de dados no BigQuery usando comandos de linguagem natural. O agente de engenharia de dados oferece os seguintes recursos para simplificar os fluxos de trabalho de engenharia de dados para ingerir dados no BigQuery:

  • Integração do Dataform: o agente gera e organiza o código do pipeline de dados diretamente nos repositórios e espaços de trabalho do Dataform
  • Geração de planos: o agente pode resumir o raciocínio e gerar um plano que permite revisar e verificar o plano do agente antes de prosseguir
  • Validação de código: o agente valida e corrige automaticamente os erros de compilação de qualquer código gerado para garantir que o pipeline de dados seja funcional
  • Preparação automática de dados: o agente realiza a preparação de dados e transforma dados brutos em tabelas estruturadas sem intervenção manual.
  • Instruções personalizadas: o agente oferece suporte a instruções personalizadas que permitem definir regras específicas e diretrizes reutilizáveis em linguagem natural
  • Contexto externo: o agente está integrado ao Knowledge Catalog para contexto adicional
  • Controle de pipeline: é possível revisar e personalizar os planos de agentes gerados antes que qualquer ação seja executada.
  • Otimização: o agente pode otimizar o desempenho no pipeline de dados
  • Solução de problemas e reparo: o agente pode solucionar falhas de pipeline e corrigir o código.

Onde usar o agente de engenharia de dados

É possível usar o agente de engenharia de dados com os seguintes métodos:

Como o agente de engenharia de dados usa seus dados

Para produzir respostas de agentes de maior qualidade, o agente de engenharia de dados pode recuperar dados e metadados adicionais do BigQuery e do Knowledge Catalog, incluindo linhas de amostra de tabelas do BigQuery e perfis de verificação de dados gerados no Knowledge Catalog. O agente não usa esses dados para treinamento. Ele usa os dados apenas como contexto adicional durante as conversas do agente para informar as respostas.

Onde o agente de engenharia de dados processa seus dados

Para mais informações sobre os locais em que o agente de engenharia de dados processa seus dados, consulte Onde o Gemini no BigQuery processa seus dados.

Limitações

O agente de engenharia de dados tem as seguintes limitações:

  • O agente de engenharia de dados não oferece suporte a comandos de linguagem natural para os seguintes tipos de arquivo:
    • Notebooks
    • Preparação de dados
  • O agente de engenharia de dados não pode executar pipelines. É necessário revisar e executar ou programar pipelines.
  • O agente de engenharia de dados não pode pesquisar links da Web ou URLs fornecidos por instruções ou comandos diretos.
  • Ao importar arquivos em um arquivo de instrução do agente, a sintaxe de importação @ oferece suporte apenas a caminhos que começam com ./, /, ou uma letra.
  • O recurso de visualização de dados é compatível apenas com tabelas, declarações ou consultas com a flag hasOutput definida como true.
  • O agente de engenharia de dados está sujeito às limitações gerais da tecnologia de IA.

Recursos e personalizações do agente

As seções a seguir descrevem outros recursos do agente e outros métodos para personalizar o agente de engenharia de dados.

Instruções para o agente

As instruções para o agente são instruções em linguagem natural para o agente de engenharia de dados que permitem armazenar instruções persistentes para que o agente siga um conjunto de regras personalizadas e predefinidas. Use instruções para o agente se quiser que os resultados do agente sejam consistentes em toda a organização, por exemplo, com convenções de nomenclatura ou para aplicar um guia de estilo.

Para criar instruções para o agente de engenharia de dados, crie um GEMINI.MD arquivo de contexto como um arquivo de instrução do agente.

Práticas recomendadas com arquivos de instrução do agente

Ao usar instruções para o agente, recomendamos o seguinte:

  • Todos os caminhos de arquivo no Dataform são relativos à raiz do repositório. Use caminhos relativos para qualquer sintaxe @file.md para importar instruções corretamente para GEMINI.md.
  • Os arquivos importados em GEMINI.md podem conter importações, o que pode criar uma estrutura aninhada. Para evitar a recursão infinita, GEMINI.md tem uma profundidade máxima de importação de cinco níveis.
  • Para compartilhar instruções em pipelines de dados, armazene instruções em um repositório central do Dataform e vincule-as ao repositório de trabalho do Dataform. É possível usar instruções locais para substituir regras centrais de comportamento específico do pipeline.
  • Para garantir a consistência no projeto, é possível vincular arquivos de convenção de nomenclatura ou guias de estilo e instruir o agente a seguir essas diretrizes ao trabalhar com pipelines de dados.
  • É possível sugerir camadas de dados no arquivo de instrução para agrupar diferentes tipos de dados.
  • O uso de títulos e listas no arquivo de instrução do agente pode ajudar a organizar e esclarecer as instruções para o agente de engenharia de dados.
  • Forneça nomes de arquivos significativos e agrupe instruções semelhantes em um arquivo. Organize as regras logicamente por categoria, recurso ou funcionalidade com títulos do Markdown.
  • Para evitar instruções conflitantes, defina claramente as condições específicas em que cada instrução se aplica.
  • Itere e refine seus comandos e fluxo de trabalho. O comportamento do agente muda ao longo do tempo com lançamentos de agentes e upgrades de modelos. Por isso, recomendamos iterar nas regras com comandos diferentes para identificar áreas que podem precisar de melhorias. Mantenha o arquivo de regras sincronizado com as mudanças no pipeline de dados.

O exemplo a seguir mostra um arquivo de instrução do agente chamado GEMINI.md que usa nossas práticas recomendadas para o uso eficaz do agente de engenharia de dados:

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md

Importar outros arquivos locais como instruções para o agente

Também é possível importar outros arquivos de instrução para o agente de engenharia de dados no arquivo GEMINI.md com a sintaxe @file.md. Para mais informações, consulte Processador de importação de memória.

Preparação automática de dados

É possível usar o agente de engenharia de dados para transformar dados brutos e não processados em tabelas estruturadas adequadas para análise de dados. Quando solicitado, o agente primeiro amostra até 1.000.000 de registros de cada tabela padrão ou externa. Em seguida, o agente realiza uma análise de dados detalhada executando consultas de criação de perfil nessa amostra. Depois de gerar transformações de dados, o agente repete esse processo de amostragem e criação de perfil para avaliar a qualidade das transformações. Essas transformações de preparação de dados podem incluir a correção de inconsistências de dados, outliers ou incompatibilidades de tipo. O agente de engenharia de dados cria um plano que descreve as etapas de organização propostas para você revisar e refinar antes que qualquer ação ocorra.

O agente de engenharia de dados também inicia a análise de preparação de dados sempre que você adiciona uma tabela bruta, como uma tabela externa baseada em CSV. É possível revisar o plano de organização de dados e ajustá-lo com comandos conversacionais.

A amostragem de dados e a criação de perfil usam recursos do BigQuery e estão sujeitas aos preços do BigQuery.

O agente de engenharia de dados oferece suporte às seguintes transformações de preparação de dados:

  • Limpeza de dados. O agente pode analisar dados brutos e sugerir oportunidades de limpeza, como remover outliers, preencher valores ausentes ou inconsistentes (imputação de dados), corrigir dados duplicados ou padronizar formatos de dados, por exemplo, números de telefone ou endereços
  • Transformações estruturais. Quando um esquema de destino é fornecido, o agente pode desaninhar ou extrair valores de tipos JSON, ARRAY ou STRUCT; mesclar várias colunas em uma; ou dividir uma coluna em várias colunas
  • Detecção e conversão de tipo de dados. O agente pode analisar os dados para determinar os tipos de campo adequados. Em seguida, o agente pode realizar a conversão de tipo segura para resolver inconsistências de formatação nos campos de data, hora, data/hora ou carimbo de data/hora.
  • Conversão de unidades. O agente pode converter automaticamente várias unidades em um campo em uma unidade consistente para padronizar os dados.

Para garantir a precisão, o agente usa amostras representativas dos dados para detectar problemas e validar a lógica de transformação.

Gerar e revisar planos de agentes

O agente de engenharia de dados pode gerar planos de agentes que fornecem um resumo e uma visão geral dos objetivos e das etapas necessárias para concluir uma solicitação. Ao solicitar ao agente pedidos complexos que exigem muitas mudanças, recomendamos pedir ao agente que forneça um plano para que você possa revisar as intenções do agente antes que ele tome qualquer ação. Um plano de agente de engenharia de dados geralmente consiste no seguinte:

  • O objetivo do agente para uma solicitação específica
  • Uma visão geral das etapas que o agente planeja seguir
  • Quaisquer suposições feitas pelo agente
  • Arquivos que o agente planeja modificar
  • Quaisquer etapas de otimização ou limpeza que ele planeja realizar
  • Um plano de execução em fases

No comando, é possível incluir a necessidade de revisar e aprovar o plano para que o agente não tome nenhuma ação sem sua aprovação explícita. Exemplo:

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. I want to review the plan and
approve it before you create the pipeline.

O agente também pode gerar um plano de agente automaticamente e solicitar sua aprovação. Esse resultado pode ocorrer quando um comando é muito ambíguo ou se o agente precisa de mais clareza para atender à sua solicitação.

Para conferir as práticas recomendadas sobre o uso de planos de agentes, consulte Práticas recomendadas.

Adicionar contexto do Knowledge Catalog

O agente de engenharia de dados usa o Knowledge Catalog anexando termos de glossário a tabelas e colunas do BigQuery e gerando verificações de perfil de dados. Os termos do glossário podem marcar colunas que exigem contexto adicional, como colunas que contêm informações de identificação pessoal (PII) que exigem instruções de tratamento especial ou para identificar colunas correspondentes com nomes diferentes em tabelas.

O Knowledge Catalog também usa a criação de perfil de dados, que fornece ao agente uma melhor compreensão da distribuição de dados nas colunas da tabela e ajuda o agente a criar declarações de qualidade de dados mais específicas.

Adicionar verificações de qualidade de dados a uma tabela atual

Quando você solicita ao agente que adicione verificações de qualidade, o agente infere verificações razoáveis para a tabela com base no esquema e nas amostras. Também é possível adicionar declarações como parte do comando. Exemplo:

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

Otimizar pipelines de dados

É possível solicitar ao agente que otimize seus pipelines de dados. Ao gerar DDL para novas tabelas, o agente de engenharia de dados recomenda o particionamento e o clustering com base nos padrões de uso de dados analisados. Além disso, o agente pode aplicar automaticamente outras otimizações de pipeline. Exemplos de otimizações possíveis incluem:

  • Poda de colunas para reduzir a leitura de dados do armazenamento e atuar como um driver principal de custo e desempenho.
  • Pushdowns de predicados para filtrar dados no início do plano de execução e reduzir significativamente o volume processado por operações subsequentes.
  • Eliminação de subexpressões comuns para melhorar a eficiência, identificando e computando a lógica de transformação compartilhada apenas uma vez, evitando práticas ineficientes, como a verificação e a combinação de tabelas grandes várias vezes.
  • Modelos incrementais para processar apenas dados novos ou alterados desde a última execução, em vez de recriar tabelas inteiras a cada execução.

Práticas recomendadas

Para melhorar os resultados ao trabalhar com o agente de engenharia de dados e o Dataform, recomendamos que você faça o seguinte:

Use instruções para o agente em solicitações comuns. Se você costuma aplicar determinadas técnicas ou se faz as mesmas correções com frequência ao agente, use instruções para o agente como um local centralizado para armazenar instruções e solicitações comuns.

Utilize planos de agentes. Os planos de agentes podem ser úteis para dividir tarefas complexas de pipeline. Os planos de agentes também podem mostrar as suposições e intenções do agente. Por isso, recomendamos revisar esses planos para garantir que o agente receba o contexto correto.

Depois de revisar um plano, é possível editá-lo solicitando ao agente de engenharia de dados feedback e mudanças. Exemplo:

In the plan, ensure that all of the intermediate tables are views.

Em alguns casos, pode ser útil pedir ao agente que gere um plano que não precise da sua aprovação explícita. O ato de criar o plano do agente força o agente de engenharia de dados a detalhar as ações, o que geralmente leva a melhores resultados. É possível forçar o agente a gerar um plano e executá-lo automaticamente. Exemplo:

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

Escreva com clareza. Faça seu pedido de forma clara e evite ser vago. Sempre que possível, forneça fontes de dados de origem e destino ao solicitar, conforme mostrado no exemplo a seguir:

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

Forneça solicitações diretas e com escopo definido. Faça uma pergunta de cada vez e mantenha os comandos concisos. Para comandos com mais de uma pergunta, liste cada parte distinta da pergunta para melhorar a clareza, conforme mostrado no exemplo a seguir:

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

Forneça instruções explícitas e enfatize os termos principais. É possível adicionar ênfase a termos ou conceitos principais nos comandos e rotular determinados requisitos como importantes, conforme mostrado no exemplo a seguir:

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

Especificar a ordem das operações. Para tarefas ordenadas, estruture o comando em listas, em que os itens listados são divididos em etapas pequenas e focadas, conforme mostrado no exemplo a seguir:

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id.
  3. Load the final result into the reporting.customer_orders table.

Refine e itere. Continue testando frases e abordagens diferentes para saber o que produz os melhores resultados. Se o agente gerar SQL inválido ou outros erros, oriente o agente com exemplos ou documentação pública.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).