Usar o agente de engenharia de dados para criar e modificar pipelines de dados

O agente de engenharia de dados permite usar o Gemini no BigQuery para criar, modificar e gerenciar pipelines de dados para carregar e processar dados no BigQuery. Com o agente de engenharia de dados, é possível usar comandos de linguagem natural para gerar pipelines de dados de várias fontes de dados ou adaptar pipelines de dados atuais às suas necessidades de engenharia de dados. O agente de engenharia de dados tem os seguintes recursos:

• Linguagem natural para criação de pipelines: o agente usa o Gemini para entender seus dados e interpretar suas instruções em linguagem simples. É possível usar instruções em linguagem simples para que o agente de engenharia de dados crie ou edite pipelines de dados.

• Integração do Dataform: o agente gera e organiza o código de pipeline necessário em arquivos SQLX em um repositório do Dataform. O agente opera no espaço de trabalho do Dataform, então os pipelines do Dataform ficam disponíveis automaticamente para o agente.

• Instruções personalizadas do agente: crie instruções do agente em linguagem simples para definir regras personalizadas para o agente de engenharia de dados. As instruções do agente são persistentes em toda a organização e podem ser úteis para aplicar regras em toda a organização, como convenções de nomenclatura ou guias de estilo.

• Validação de pipeline: o agente valida qualquer código gerado para garantir que os pipelines de dados sejam funcionais.

É possível usar comandos de linguagem natural com o agente de engenharia de dados para criar arquivos SQLX de tabelas, visualizações, declarações, declarações e operações. Por exemplo, é possível usar o agente de engenharia de dados para fazer o seguinte:

• Carregar dados de fontes de dados externas, como o Cloud Storage, em vários formatos, como CSV, AVRO ou PARQUET.
• Criar ou usar rotinas do BigQuery (UDFs) para realizar análises e transformações personalizadas nos seus dados.
• Definir diretrizes reutilizáveis para o agente em linguagem natural.

Para mais exemplos de prompts que podem ser usados com o agente de engenharia de dados, consulte Prompts de amostra.

Limitações

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

• O agente de engenharia de dados é um produto em pré-GA e não se destina ao uso em produção.
• 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
  • JavaScript em qualquer SQLx
• O agente de engenharia de dados não pode executar pipelines. Os usuários precisam revisar e executar ou programar pipelines.
• O agente de engenharia de dados não pode validar o SQL que depende de recursos intermediários inexistentes sem a invocação completa do pipeline (acionada pelo usuário).
• 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 @ só oferece suporte a caminhos que começam com ./, /, ou uma letra.
• O recurso de visualização de dados só é compatível com tabelas, declarações ou consultas com a flag hasOutput definida como true.

Regiões compatíveis

O Gemini no BigQuery é oferecido nas seguintes regiões:

Alterar a região de processamento

É possível mudar a região de processamento do agente de engenharia de dados usando uma das seguintes opções:

Como o agente de engenharia de dados usa seus dados

Para produzir respostas de agente de maior qualidade, o agente de engenharia de dados pode recuperar dados e metadados adicionais do BigQuery e do Dataplex Universal Catalog, incluindo linhas de amostra de tabelas do BigQuery e perfis de verificação de dados gerados no Dataplex Universal Catalog. Esses dados não são usados para treinar o agente de engenharia de dados e são usados apenas durante conversas do agente como contexto adicional para informar as respostas do agente.

Antes de começar

Verifique se o Gemini no BigQuery está ativado para seu Cloud de Confiance by S3NS projeto. Para mais informações, consulte Configurar o Gemini no BigQuery.

Você também precisa ativar a API Gemini Data Analytics.

Ativar a API

Funções exigidas

Para receber a permissão necessária para usar o agente de engenharia de dados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Editor de código do Dataform (roles/dataform.codeEditor)
• Usuário de jobs do BigQuery (roles/bigquery.jobuser)
• Usuário de chat sem estado do Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser)

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

Esse papel predefinido contém a geminidataanalytics.locations.useDataEngineeringAgent permissão, que é necessária para usar o agente de engenharia de dados.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Gerar um pipeline de dados com o agente de engenharia de dados

Para usar o agente de engenharia de dados no BigQuery, selecione uma das seguintes opções:

Revisar um pipeline de dados

Em um pipeline de dados gerado pelo agente de engenharia de dados, é possível clicar em um nó de pipeline para revisá-lo.

• A guia Configuração mostra a consulta SQLX gerada associada ao nó.
• A guia Visualização de dados mostra a tabela de entrada e saída do arquivo. É possível conferir uma visualização da transformação de dados nesse nó clicando em Executar tarefa para executar a tarefa com ou sem dependências.

Editar um pipeline de dados

É possível editar o pipeline de dados usando o agente de engenharia de dados clicando em Perguntar ao agente e inserindo um comando que sugere uma mudança no pipeline de dados.

Revise as mudanças propostas pelo agente de engenharia de dados e clique em Aplicar para aplicar as mudanças.

Também é possível editar uma consulta SQLX manualmente selecionando um nó de pipeline e clicando em Abrir.

Criar instruções do agente para o agente de engenharia de dados

As instruções do 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 do 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.

É possível criar um GEMINI.MD arquivo de contexto como um arquivo de instrução do agente para o agente de engenharia de dados. É possível criar arquivos de instrução do agente para usar no espaço de trabalho local ou usar os mesmos arquivos de instrução em vários pipelines de dados usando um repositório externo.

Para criar instruções do agente, faça o seguinte:

1. Em Perguntar ao agente, clique em Instruções do pipeline.
2. No painel Instruções para pipeline, clique em Criar arquivo de instruções.

3. No arquivo GEMINI.MD que aparece, insira suas instruções em linguagem natural.

   O exemplo a seguir mostra um arquivo de instrução do agente com várias regras:

     1. All event-specific tables MUST be prefixed with `cs_event_`.
     2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
     3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.
   

4. Clique em Salvar.

Para informações sobre como estruturar melhor os arquivos de instrução do agente, consulte Práticas recomendadas com arquivos de instrução do agente.

Carregar instruções do agente de um repositório externo

É possível especificar um conjunto de instruções do agente para serem reutilizadas em vários pipelines de dados vinculando um repositório externo:

1. Em Perguntar ao agente, clique em Instruções do pipeline.
2. Em Repositório externo, selecione Usar instruções de um repositório externo repositório
3. Nos campos fornecidos, especifique um repositório que contenha instruções do agente que você quer usar com o pipeline de dados.
4. Clique em Salvar.

Importar outros arquivos locais como instruções do agente

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

Resolver problemas de erros de pipeline de dados

Se você encontrar erros durante a geração do pipeline de dados, verifique se você fez todos os pré-requisitos necessários para executar o agente de engenharia de dados. Para mais informações, consulte Antes de começar.

Se o pipeline de dados gerado encontrar erros, você poderá pedir ao agente de engenharia de dados para diagnosticar falhas de pipeline de dados e propor recomendações de solução de problemas com as seguintes etapas:

1. No pipeline ou no espaço de trabalho de desenvolvimento, clique na guia Execuções.

2. Na lista de execuções, encontre a execução do pipeline de dados com falha. É possível identificar execuções com falha na coluna Status da execução.

   

3. Passe o cursor sobre o ícone e clique em Investigar. O agente de engenharia de dados executa uma análise na execução do pipeline de dados para detectar erros.

   

4. Quando a análise for concluída, o agente de engenharia de dados vai gerar um relatório na seção Observações e hipóteses. Esse relatório inclui:

   • Observações e pontos de dados extraídos dos registros de execução do pipeline de dados
   • Causas prováveis da falha
   • Um conjunto de etapas ou recomendações acionáveis para resolver o problema identificado

Com o relatório de solução de problemas do agente de engenharia de dados, é possível implementar as recomendações manualmente. Também é possível instruir o agente de engenharia de dados a aplicar a correção para você com as seguintes etapas:

1. Copie as sugestões no relatório de solução de problemas.
2. Retorne ao agente de engenharia de dados:
   1. Se você estiver usando pipelines do BigQuery, acesse a página de pipelines e clique em Perguntar ao agente.
   2. Se você estiver usando o Dataform, clique em Perguntar ao agente.
3. Cole as sugestões no comando e instrua o agente de engenharia de dados a fazer as correções diretamente no pipeline de dados.
4. Clique em Enviar.

Comandos de amostra

As seções a seguir mostram alguns comandos de amostra que podem ser usados com o agente de engenharia de dados para desenvolver o pipeline de dados.

Agregar dados atuais em uma nova tabela

Com esse comando, o agente de engenharia de dados usa o esquema e as amostras para inferir o agrupamento de dados por chave. O agente normalmente configura uma nova configuração de tabela com descrições de tabela e coluna.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

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

Com esse comando, o agente infere verificações de qualidade razoáveis para a tabela com base no esquema e nas amostras. Também é possível adicionar algumas declarações opinativas como parte do comando.

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

Criar uma nova coluna derivada e adicionar verificações de qualidade de dados à nova tabela

O comando a seguir mostra como adicionar uma tabela e uma coluna e especificar verificações de qualidade à tabela ao mesmo tempo.

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

Criar UDFs como parte da definição do modelo

O agente de engenharia de dados também pode configurar a DDL para criar funções definidas pelo usuário (UDFs). Embora o agente não crie a UDF, é possível criar a UDF executando o pipeline de dados. Essas UDFs podem ser usadas em definições de modelo no pipeline de dados.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

Práticas recomendadas

As seções a seguir sugerem práticas recomendadas para trabalhar com o agente de engenharia de dados e o Dataform.

Práticas recomendadas com o agente de engenharia de dados

Use instruções do agente para solicitações comuns. Se houver técnicas que você costuma aplicar ou se você costuma fazer as mesmas correções no agente, use as instruções do agente como um local centralizado para armazenar instruções e solicitações comuns.

Forneça mais contexto ao agente. É possível fornecer contexto adicional ao agente do Dataplex Universal 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 ser usados para 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. As verificações de perfil de dados oferecem ao agente uma melhor compreensão da distribuição de dados nas colunas de uma tabela e podem ajudar o agente a criar declarações de qualidade de dados mais específicas. Para mais informações, consulte Sobre a criação de perfil de dados.

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, como 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. Faça uma pergunta por vez e mantenha os comandos concisos. Para comandos com mais de uma pergunta, é possível detalhar cada parte distinta da pergunta para melhorar a clareza, como 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, como 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, é possível estruturar o comando em listas, em que os itens listados são divididos em etapas pequenas e focadas, como 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 tentando frases e abordagens diferentes para ver o que gera os melhores resultados. Se o agente gerar SQL inválido ou outros erros, oriente o agente usando 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).

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

Crie arquivos de instrução do agente para personalizar o agente de engenharia de dados de acordo com suas necessidades. Ao usar instruções do agente, recomendamos que você faça 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.
• O uso de cabeçalhos 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.
• Dê nomes de arquivos significativos e agrupe instruções semelhantes em um arquivo. Organize as regras logicamente por categoria, recurso ou funcionalidade usando cabeçalhos 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