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

O Agente de Engenharia de Dados no BigQuery e no Dataform permite criar, modificar e gerenciar pipelines de dados para carregar e processar dados no BigQuery. É possível usar comandos de linguagem natural para gerar pipelines de dados de várias fontes ou adaptar os pipelines de dados atuais para atender à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 e opera no espaço de trabalho do Dataform. Assim, os pipelines do Dataform ficam automaticamente disponíveis para o agente. Também é possível interagir com o agente usando a API Data Engineering Agent, que usa o protocolo A2A. Para ver exemplos de comandos que você pode usar, consulte Exemplos de comandos.

O Agente de Engenharia de Dados usa o Gemini para Google Cloud e oferece suporte às funções de IA e ML do BigQuery para criar pipelines de enriquecimento de IA em lote, pesquisa semântica e machine learning no Dataform. Para mais informações, consulte Suporte de IA e ML do BigQuery.

Limitações

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

• O Agente de Engenharia de Dados não aceita comandos em linguagem natural para os seguintes tipos de arquivo:
  • Notebooks
  • Preparação de dados
• O agente de engenharia de dados não pode executar pipelines. É preciso 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ções do agente, a sintaxe de importação @ aceita apenas 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 BigLake metastore), todas as limitações do catálogo do ambiente de execução do Lakehouse se aplicam. 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 projeto doGoogle Cloud . 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), o que permite gerenciar APIs para o projeto atual.

Console

Ative as seguintes APIs no console do Google Cloud para o projeto do Google Cloud que você usa com a API Conversational Analytics, se elas ainda não estiverem ativadas.

Ativar a API Gemini Data Analytics

Ativar a API Gemini para Google Cloud

Ativar a API BigQuery

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

gcloud

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

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 projeto Google Cloud .

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 permissão geminidataanalytics.locations.useDataEngineeringAgent, 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.

Para detalhes sobre os papéis necessários para consultar tabelas do Apache Iceberg, consulte Papéis necessários para o suporte ao 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 catálogo de conhecimento, peça ao administrador para conceder a você o papel do IAM de editor do catálogo do Dataplex (roles/dataplex.catalogEditor) 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 permissão geminidataanalytics.locations.useDataEngineeringAgent, que é necessária para integrar o agente de engenharia de dados ao Knowledge Catalog.

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

Se você usa uma conta de serviço personalizada para executar pipelines, precisa conceder o papel de Editor do Dataplex Catalog (roles/dataplex.catalogEditor) no projeto ou no grupo de entrada @bigquery. Além disso, é necessário ativar 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 de conjunto de dados e Definir uma chave padrão de 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

Para usar o Agente de Engenharia de Dados na interface de pipelines do BigQuery, faça o seguinte:

1. Acessar a página do BigQuery.

   Acessar o BigQuery

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

3. Na interface do pipeline, clique em Perguntar ao agente.

4. No campo Perguntar ao agente, insira um comando em 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.

5. 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. Clique em um nó do pipeline para analisar a consulta SQLX gerada. Para aplicar o pipeline de dados sugerido pelo agente, clique em Aplicar.

Dataform

Para usar o Agente de Engenharia de Dados no Dataform, faça o seguinte:

1. Acesse o Dataform.

   Acesse o 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 prompt Perguntar ao agente que aparece, insira um comando em 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 comando. O agente aplica essas mudanças diretamente aos arquivos do seu 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 sugira uma mudança no pipeline de dados.

Revise as mudanças propostas pelo agente de engenharia de dados e clique em Aplicar para aplicá-las.

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

Analisar um pipeline de dados

Clique em um nó em um pipeline de dados gerado pelo agente de engenharia de dados para analisá-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. Para visualizar a transformação de dados por esse nó, clique em Executar tarefa para executar a tarefa com ou sem dependências.

Resolver erros de pipeline de dados

Se você encontrar erros ao gerar o pipeline de dados, conclua todos os pré-requisitos para executar o Agente de Engenharia de Dados.

Os erros no pipeline aparecem como execuções com falha na guia Execuções. Para usar o agente de engenharia de dados para executar uma análise de causa raiz e receber recomendações de solução de problemas, faça o seguinte:

1. Na guia Execuções, clique no status de uma execução com falha e, em seguida, clique em Investigar.

   

   O painel Perguntar ao agente é aberto com uma solicitação para que o agente realize uma análise de causa raiz da execução com falha.

2. Analise o relatório de solução de problemas do agente.

O relatório de solução de problemas inclui mais informações sobre os erros no processo de geração de pipeline. Você pode pedir ao agente para corrigir esses erros de pipeline com base no relatório.

Criar instruções do agente

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 as instruções do agente se quiser que os resultados dele 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 arquivo de contexto GEMINI.MD como um arquivo de instruções para o agente de engenharia de dados. É possível criar arquivos de instrução de 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 as instruções em linguagem natural.

   O exemplo a seguir mostra um arquivo de instruções 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 saber como estruturar melhor os arquivos de instruções do agente, consulte Práticas recomendadas com arquivos de instruções do agente.

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

Para reutilizar um conjunto de instruções de 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.
3. Nos campos fornecidos, especifique um repositório que contenha as instruções do agente que você quer usar com seu pipeline de dados.
4. Clique em Salvar.

Suporte para IA e ML do BigQuery

O agente de engenharia de dados é compatível com muitas funções e instruções de IA, ML e objetos do BigQuery nos pipelines SQLX do Dataform gerados e nos arquivos de instrução do agente (GEMINI.MD) que você cria, incluindo:

• AI.FORECAST
• AI.DETECT_ANOMALIES
• AI.CAUSAL_EFFECT
• AI.EVALUATE
• AI.KEY_DRIVERS
• AI.GENERATE
• AI.GENERATE_TABLE
• AI.GENERATE_EMBEDDING
• AI.IF
• AI.SCORE
• AI.CLASSIFY
• AI.SEARCH
• AI.SIMILARITY
• AI.AGG
• CREATE MODEL (incluindo LOGISTIC_REG, KMEANS, CONTRIBUTION_ANALYSIS, modelos remotos (REMOTE WITH CONNECTION) e a cláusula TRANSFORM)
• CREATE TABLE com geração autônoma de embeddings (AI.EMBED)
• ML.PREDICT
• ML.EVALUATE
• ML.CORRELATION
• ML.DETECT_CHANGE_POINTS
• ML.GET_INSIGHTS
• ML.SEASONALITY
• ML.TREND
• ML.VALIDATE_DATA_DRIFT
• VECTOR_SEARCH
• OBJ.GET_ACCESS_URL

Para executar pipelines do Dataform que contêm funções de IA generativa ou modelos remotos, a conta de serviço ou o usuário que executa o pipeline precisa ter as permissões necessárias para executar consultas de IA generativa. Quando o agente de engenharia de dados gera instruções DDL, como CREATE MODEL ou CREATE TABLE, com geração de embedding autônomo, ele as configura como ações operations do Dataform (type: "operations") com hasOutput: true para que os nós de pipeline downstream possam referenciá-las usando ${ref("RESOURCE_NAME")}. O agente só usa a função AI.SEARCH em tabelas que têm a geração de embeddings autônoma ativada.

Ao trabalhar com funções ObjectRef, o usuário também precisa ter acesso delegado ao bucket do Cloud Storage. Para mais informações, consulte Acesso delegado.

Para mais informações sobre as funções de IA e ML no BigQuery, consulte Introdução à IA no BigQuery.

Casos de uso

Para ativar as funções de IA e ML compatíveis nos pipelines de dados, use-as das seguintes maneiras:

• Peça ao agente de engenharia de dados para criar ou modificar um pipeline. Por exemplo, se você for um engenheiro de dados criando um pipeline de ELT programado que enriquece texto bruto, extrai campos estruturados de documentos não estruturados ou pontua novos registros, o agente gera os arquivos SQLX do Dataform e o gráfico de dependência apropriados.

• Defina regras de pipeline persistentes em um arquivo de instruções do agente (GEMINI.MD). Por exemplo, para padronizar endpoints de modelo, IDs de conexão ou limites de anomalia padrão nos pipelines da sua organização.

A tabela a seguir mostra exemplos de comandos que ativam o uso de funções de IA ou ML para pipelining de dados em lote:

Caso de uso	Exemplo de uso	Conjunto de dados público
Resumo de texto em lote (AI.GENERATE)	"Crie uma tabela de preparo de bigquery-public-data.bbc_news.fulltext para artigos de 'esportes' e adicione uma coluna que resuma a coluna do corpo em uma ou duas frases."	bigquery-public-data.bbc_news.fulltext
Extração de esquema estruturado (AI.GENERATE_TABLE)	"Crie uma tabela de pipeline que extraia um esquema estruturado (company_name STRING, key_topic STRING, is_earnings_related BOOL) da coluna body de artigos de negócios em bigquery-public-data.bbc_news.fulltext."	bigquery-public-data.bbc_news.fulltext
Enriquecimento de objetos multimodal (OBJ.GET_ACCESS_URL)	"Crie uma tabela de objetos externa no bucket de imagens de produtos do Cloud Storage e crie uma tabela downstream que gere uma matriz image_description e de entidades para cada imagem usando OBJ.GET_ACCESS_URL."	Tabela de objetos do Cloud Storage (por exemplo, gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png)
Filtragem de dados semânticos (AI.IF)	"Crie uma tabela limpa de artigos de tecnologia de bigquery-public-data.bbc_news.fulltext, filtrando para manter apenas as linhas que discutem avanços na inteligência artificial."	bigquery-public-data.bbc_news.fulltext
Pontuação de sentimento em lote (AI.SCORE)	"Crie uma tabela enriquecida de bigquery-public-data.bbc_news.fulltext para a categoria de entretenimento com uma coluna numérica sentiment_score que classifica o grau de sentimento positivo."	bigquery-public-data.bbc_news.fulltext
Classificação de taxonomia automatizada (AI.CLASSIFY)	"Usando as críticas de filmes em bigquery-public-data.imdb.reviews, classifique automaticamente cada crítica em nossos níveis de taxonomia editorial para Arquétipo Narrativo (por exemplo, 'Estudo de Personagem', 'Espetáculo de Ação', 'Suspense Psicológico') e Clima de Visualização (por exemplo, 'Sombrio e Realista', 'Inspirador', 'Suspense'). Grave os resultados com os metadados do filme em uma tabela selecionada."	bigquery-public-data.imdb.reviews
Resumo semântico agrupado (AI.AGG)	"Para cada filme em bigquery-public-data.imdb.reviews, reúna todo o feedback do público de centenas de avaliações em um resumo executivo consolidado que destaque o consenso da recepção crítica, os principais elogios e as reclamações recorrentes dos espectadores. Agrupe os resultados por movie_id e título, além de métricas como contagem total de avaliações e classificação média, para produzir uma tabela unificada de inteligência no nível do filme para executivos de estúdio e equipes de marketing."	bigquery-public-data.imdb.reviews
Geração de embedding em lote (AI.GENERATE_EMBEDDING)	"Crie um nó de pipeline que gere embeddings de vetor para a coluna de avaliações em bigquery-public-data.imdb.reviews e os materialize em uma tabela de atributos."	bigquery-public-data.imdb.reviews
Embeddings autônomos e pesquisa semântica (AI.EMBED, AI.SEARCH)	"Crie uma tabela de resenhas de filmes com a geração de embeddings autônomos ativada na coluna de resenhas e crie uma tabela de relatórios downstream que encontre as 10 principais resenhas que correspondam a 'suspense psicológico que cria tensão'."	bigquery-public-data.imdb.reviews
Previsão de demanda programada (AI.FORECAST)	"Crie uma tabela de relatórios diários que preveja o número de viagens de compartilhamento de bicicletas por dia para os próximos 30 dias a partir de bigquery-public-data.san_francisco_bikeshare.bikeshare_trips."	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips
Detecção de anomalias de pipeline (AI.DETECT_ANOMALIES)	"Crie uma tabela de monitoramento que detecte anomalias no volume diário de viagens em 2018 usando 2017 como o valor de referência histórico de bigquery-public-data.san_francisco_bikeshare.bikeshare_trips."	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips
Relatórios automatizados de fatores principais (AI.KEY_DRIVERS)	"Crie uma tabela de relatórios que identifique os principais fatores para as mudanças no volume de viagens entre 2017 e 2018 usando bigquery-public-data.austin_bikeshare.bikeshare_trips."	bigquery-public-data.austin_bikeshare.bikeshare_trips
Detecção de ponto de mudança (ML.DETECT_CHANGE_POINTS)	"Crie uma tabela que detecte pontos de mudança estrutural no volume diário de viagens de bigquery-public-data.san_francisco_bikeshare.bikeshare_trips."	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips
Treinamento de modelo com pré-processamento, avaliação e pontuação em lote (CREATE MODEL, TRANSFORM, ML.EVALUATE, ML.PREDICT)	Crie um pipeline do Dataform em bigquery-public-data.ml_datasets.census_adult_income que treine um modelo de regressão logística com uma cláusula TRANSFORM para prever income_bracket, avalie o modelo em uma tabela de avaliação e gere predições em lote para uma tabela de pontuação.	bigquery-public-data.ml_datasets.census_adult_income
Segmentação de clientes (CREATE MODEL com KMEANS)	"Crie um pipeline que treine um modelo de clustering k-means com base nas medidas físicas de pinguins de bigquery-public-data.ml_datasets.penguins e atribua IDs de cluster a uma tabela de saída segmentada."	bigquery-public-data.ml_datasets.penguins
Validação automatizada de desvio de dados (ML.VALIDATE_DATA_DRIFT)	"Adicione uma tabela de monitoramento ao pipeline que valida o desvio de atributos entre a tabela de viagens de referência de 2017 e a tabela de viagens de exibição de 2018 de bigquery-public-data.san_francisco_bikeshare.bikeshare_trips."	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips

Comandos de amostra

As seções a seguir mostram exemplos de comandos que podem ser usados com o Agente de Engenharia de Dados para desenvolver seu pipeline de dados.

Agregue os 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 define uma nova configuração de tabela com descrições de tabelas e colunas.

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

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

Este comando mostra como adicionar uma tabela e uma coluna e especificar verificações de qualidade para a 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, você pode 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.

Enriquecer dados não estruturados e executar previsões de ML em lote em um pipeline

Este comando mostra como combinar engenharia de atributos comportamentais, modelagem de classificação do BigQuery ML e personalização de IA generativa em nós de pipeline encadeados do Dataform:

  Create a multi-step Dataform pipeline using
  bigquery-public-data.thelook_ecommerce.users and bigquery-public-data.thelook_ecommerce.orders:

  1. Create a staging table on a sample of customers to engineer retention
     features (tenure, lifetime spend, recency) and label churn based on
     inactivity over the past 90 days.
  2. Train a BigQuery ML logistic regression model on those behavioral features
     to predict churn risk.
  3. Create a final table that scores customer churn probabilities and drafts
     personalized, 3-sentence win-back emails with purchase-tailored discounts
     for the 20 customers at highest risk of churning.

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 as instruções do agente para solicitações comuns. Se você costuma aplicar determinadas técnicas ou 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.

Use planos de agente. Eles podem ser úteis para dividir tarefas complexas de pipeline. Os planos do agente também podem mostrar as suposições e intenções do agente. Por isso, recomendamos que você os revise para garantir que o agente receba o contexto correto.

Depois de analisar um plano, você pode editá-lo enviando um comando ao agente de engenharia de dados com 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 fazer o agente planejar 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 as 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.

Faça solicitações diretas e com escopo definido. Faça uma pergunta de cada vez e escreva comandos concisos. Para comandos com mais de uma pergunta, detalhe cada parte 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).

Dê instruções explícitas e enfatize os termos principais. É possível enfatizar termos ou conceitos importantes 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, estruture 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 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 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).