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

Este documento mostra como usar o agente de engenharia de dados no BigQuery e no Dataform para criar e modificar pipelines de dados.

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

O agente gera e organiza o código do pipeline de dados diretamente nos repositórios do Dataform. Ele opera no espaço de trabalho do Dataform, então os pipelines do Dataform ficam disponíveis automaticamente para o agente.

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

Também é possível usar a API do agente de engenharia de dados, que usa o protocolo A2A, para interagir com o agente.

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.
• Ao criar pipelines em tabelas externas do Apache Iceberg gerenciadas pelo catálogo do ambiente de execução do Lakehouse (antigo metastore do BigLake), todas as limitações do catálogo do ambiente de execução do Lakehouse se aplicam. Principalmente, o agente não pode gerar mutações de gravação (como INSERT, UPDATE, DELETE ou MERGE) ou instruções DDL (como CREATE TABLE ou DROP TABLE) em tabelas do Iceberg. Para mais informações, consulte Conceitos de endpoint do catálogo REST do Apache Iceberg.

Antes de começar

Antes de usar o agente de engenharia de dados, siga as etapas desta seção.

Ativar o Gemini no BigQuery

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

Ative as APIs necessárias

Observação: se você não tiver permissão para ativar as APIs, peça para o administrador do projeto fazer isso no painel "APIs e serviços". Como alternativa, o administrador do projeto pode conceder a você o papel Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin) no Google Cloud console, o que permite ativar e desativar APIs para o projeto atual.

Console

Ative as seguintes APIs no Google Cloud console do Google Cloud projeto que você usa com a API Conversational Analytics.

Ativar a API Gemini Data Analytics

Ativar o Gemini para Google Cloud API

Ativar a API BigQuery

Dica: depois de ativar uma API, atualize a Google Cloud página do console para confirmar se ela está ativada.

gcloud

Para ativar a API Gemini Data Analytics, o Gemini para Google Cloud API e a API BigQuery, use a Google Cloud CLI e execute os seguintes gcloud services enable comandos:

gcloud services enable geminidataanalytics.googleapis.com --project=PROJECT_ID
gcloud services enable cloudaicompanion.googleapis.com --project=PROJECT_ID
gcloud services enable bigquery.googleapis.com --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do Google Cloud projeto.

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 conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Para detalhes sobre os papéis necessários para consultar tabelas do Apache Iceberg, consulte Papéis necessários para o suporte do Lakehouse Apache Iceberg.

Pré-requisitos de integração do Knowledge Catalog

Para receber a permissão necessária para integrar o agente de engenharia de dados ao Knowledge Catalog, peça ao administrador para conceder a você o Editor de catálogo do Dataplex (roles/dataplex.catalogEditor) papel do IAM no projeto. 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 integrar o agente de engenharia de dados ao Knowledge Catalog.

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

Se você usar uma conta de serviço personalizada para executar pipelines, conceda o papel Editor de catálogo do Dataplex (roles/dataplex.catalogEditor) no projeto ou no grupo de entradas @bigquery. Além disso, ative a API Dataplex.

Criptografar dados com chaves do Cloud Key Management Service

É possível criptografar dados no nível do conjunto de dados ou do projeto com as chaves padrão do Cloud Key Management Service gerenciadas pelo cliente no BigQuery. Para mais informações, consulte Definir uma chave padrão do conjunto de dados e Definir uma chave padrão do projeto.

É possível criptografar o código do pipeline no nível do projeto definindo uma chave padrão do Cloud Key Management Service do Dataform.

Configurar perímetros do VPC Service Controls

Se você usa o VPC Service Controls, configure o perímetro para proteger o Dataform, o BigQuery e a API Conversational Analytics. Para mais informações, consulte Dataform, BigQuery, e API Conversational Analytics.

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:

Pipelines do BigQuery

É possível usar o agente de engenharia de dados na interface de pipelines do BigQuery fazendo o seguinte:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No editor de consultas, clique em arrow_drop_down Criar > Pipeline.

3. Selecione uma opção para as credenciais de execução e clique em Começar. Essas credenciais não são usadas pelo agente, mas são necessárias para executar o pipeline de dados gerado.

4. Clique em Testar a experiência do agente para pipeline de dados.

5. No campo Perguntar ao agente, insira um comando de linguagem natural para gerar um pipeline de dados. Por exemplo:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Depois de inserir um comando, clique em Enviar.

6. O agente de engenharia de dados gera um pipeline de dados com base no seu comando.

O agente de engenharia de dados gera um rascunho proposto de um pipeline de dados. É possível clicar em um nó de pipeline para revisar a consulta SQLX gerada. Para aplicar o pipeline de dados sugerido pelo agente, clique em Aplicar.

Dataform

É possível usar o agente de engenharia de dados no Dataform fazendo o seguinte:

1. Acessar o Dataform.

   Acesse Dataform

2. Selecione um repositório.

3. Selecione ou crie um espaço de trabalho de desenvolvimento.

4. No espaço de trabalho, clique em Perguntar ao agente.

5. No comando Perguntar ao agente que aparece, insira um comando de linguagem natural para gerar um pipeline de dados. Por exemplo:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Depois de inserir um comando, clique em Enviar.

Depois que o comando é enviado, o agente de engenharia de dados gera um pipeline de dados e modifica os arquivos SQLX do Dataform com base no seu comando. O agente aplica essas mudanças diretamente aos arquivos do espaço de trabalho.

Editar um pipeline de dados

Para editar o pipeline de dados, clique em Perguntar ao agente e insira 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.

Revisar um pipeline de dados

É possível clicar em um nó de pipeline em um pipeline de dados gerado pelo agente de engenharia de dados 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 visualizar a transformação de dados nesse nó clicando em Executar tarefa para executar a tarefa com ou sem dependências.

Resolver problemas de erros de pipeline de dados

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

Executar uma investigação do Gemini Cloud Assist

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para mais informações sobre a solução de problemas de pipeline, use o agente de engenharia de dados para executar uma análise de causa raiz e sugerir recomendações de solução de problemas.

Esse recurso usa investigações do Gemini Cloud Assist (pré-lançamento) e está disponível apenas para usuários com um contrato de suporte Premium. Para mais informações sobre como ativar as investigações do Gemini Cloud Assist, consulte Resolver problemas com as investigações do Gemini Cloud Assist.

É possível usar o agente de engenharia de dados para resolver problemas de erros de pipeline de dados seguindo estas 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 de pipeline de dados com falha. É possível identificar execuções com falha na coluna Status.

   

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

   

4. Após a conclusão da análise, o agente de engenharia de dados gera um relatório na seção Observações e hipóteses. O relatório inclui o seguinte:

   • 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 práticas 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ê seguindo estas etapas:

1. Copie as sugestões no relatório de solução de problemas.
2. Volte 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.

Criar instruções do agente

As instruções do agente são instruções de 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 com 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

Para reutilizar um conjunto de instruções do agente em vários pipelines de dados, vincule 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 repository.
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.

Comandos de amostra

As seções a seguir fornecem 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.

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

Esse comando 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 o DDL para criar funções definidas pelo usuário (UDFs). Embora o agente não crie a UDF, é possível criá-la 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

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 do agente para solicitações comuns. Se você costuma aplicar determinadas técnicas ou se faz as mesmas correções com frequência no agente, use instruções do agente como um local centralizado para armazenar instruções e solicitações comuns.

Use planos de agente. Os planos de agente podem ser úteis para dividir tarefas complexas de pipeline. Os planos de agente também podem mostrar as suposições e intenções do agente. 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 para gerar 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 dividir 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. 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 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 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).