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

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta 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 assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Observação: para enviar feedback ou fazer perguntas sobre esse recurso de pré-lançamento, entre em contato com [e-mail]

Com o agente de engenharia de dados, você usa 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 em linguagem natural para gerar pipelines de dados de várias fontes ou adaptar os pipelines atuais para atender à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. Você pode 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 dentro de 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 ele.

• Instruções para agentes personalizados: crie instruções 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 estejam funcionando.

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

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

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

Limitações

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

• O agente de engenharia de dados é uma oferta pré-GA e não se destina ao uso em produção.
• O Agente de engenharia de dados não é compatível com comandos em 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 web links 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 @ só aceita caminhos que começam com ./, / ou uma letra.
• O recurso prévia dos dados só é compatível com tabelas, declarações ou consultas em que a flag hasOutput está definida como true.

Regiões compatíveis

O Gemini no BigQuery usa o Google Cloudpara balanceamento de carga, o que permite que ele opere globalmente. Como o Gemini no BigQuery opera globalmente, não é possível escolher qual região usar.

Todas as solicitações do Dataform e do BigQuery vão para os respectivos endpoints regionais. Assim, todos os dados e códigos permanecem na região.

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

Américas

• Iowa (us-central1)

Europa

• Finlândia (europe-north1)
• Frankfurt (europe-west3)

Como o agente de engenharia de dados usa seus dados

Para gerar respostas de maior qualidade, o Data Engineering Agent pode recuperar mais dados e metadados 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, apenas durante as conversas como contexto adicional para informar as respostas do agente.

Antes de começar

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

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Funções exigidas

Para receber as permissões necessárias para usar o agente de engenharia de dados, peça ao administrador que conceda 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)

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.

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 dos 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. 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 o pipeline de dados.

5. No campo Perguntar ao agente, insira um comando em linguagem natural para gerar um pipeline de dados. 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 pipeline de dados gerado pelo agente de engenharia de dados é um rascunho proposto de um pipeline de dados. Clique em um nó de 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 a página 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 comando Perguntar ao agente que aparece, insira um comando de linguagem natural para gerar um pipeline de dados. 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.

Analisar um pipeline de dados

Em um pipeline de dados gerado pelo agente de engenharia de dados, clique em um nó de pipeline para analisá-lo.

• A guia Configuração mostra a consulta SQLX gerada associada ao nó.
• A guia Prévia dos dados mostra a tabela de entrada e saída do arquivo. Para ver uma prévia da transformação de dados por esse nó, clique em Executar tarefa com ou sem dependências.

Editar um pipeline de dados

Para editar seu pipeline de dados usando o agente de engenharia de dados, clique em Perguntar ao agente e insira um comando que sugira uma mudança no pipeline.

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

Também é possível editar uma consulta SQLX manualmente. Para isso, selecione um nó de pipeline e clique em Abrir.

Criar instruções de 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 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 do agente para o Data Engineering Agent. É possível criar arquivos de instruções do agente para usar no seu espaço de trabalho local ou usar os mesmos arquivos 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 de instruções para o 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çõ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 informações sobre 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

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

Se você encontrar erros durante a geração do pipeline de dados, verifique se atendeu a 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, peça ao agente de engenharia de dados para diagnosticar falhas e propor recomendações de solução de problemas 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 com falha do pipeline de dados. É 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 identificar erros.

   

4. Quando a análise é concluída, o agente de engenharia de dados gera um relatório na seção Observações e hipóteses. Este 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 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. Você também pode instruir o agente de engenharia de dados a aplicar a correção 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.

Comandos de amostra

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

Agregar dados 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. Normalmente, o agente 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

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

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

Criar uma 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 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 fazer isso 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ê aplica com frequência ou se você costuma fazer as mesmas correções no agente, use as instruções dele como um local centralizado para armazenar instruções e solicitações comuns.

Dê mais contexto ao agente. É possível dar ao agente mais contexto do Dataplex Universal Catalog anexando termos do 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 mais contexto, como colunas que contêm informações de identificação pessoal (PII) e precisam de instruções de tratamento especial, ou para identificar colunas correspondentes com nomes diferentes em várias tabelas. As verificações de perfil de dados oferecem ao agente uma compreensão melhor da distribuição de dados nas colunas de uma tabela e podem ajudar 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 fazer solicitações, como 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 específicas. Faça uma pergunta por vez e mantenha as instruções concisas. Para comandos com mais de uma pergunta, você pode listar cada parte distinta da pergunta para melhorar a clareza, como 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 termos-chave. Você pode enfatizar termos ou conceitos-chave nos comandos e rotular determinados requisitos como importantes, como 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, você pode estruturar seu 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. Teste frases e abordagens diferentes para saber produz os melhores resultados. Se o agente gerar SQL inválido ou outros erros, oriente-o 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ções do agente

Crie arquivos de instruções 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 corretamente instruções para GEMINI.md.
• Os arquivos importados em GEMINI.md podem conter outras importações, o que cria uma estrutura aninhada. Para evitar 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-as em um repositório central do Dataform e vincule-as ao repositório de trabalho do Dataform. Você pode usar instruções locais para substituir regras centrais de comportamento específico do pipeline.
• Usar cabeçalhos e listas no arquivo de instruções do agente ajuda 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 de forma lógica por categoria, recurso ou funcionalidade usando cabeçalhos em 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 com o tempo, com lançamentos de agentes e upgrades de modelos. Por isso, recomendamos iterar suas regras com diferentes comandos 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ções do agente chamado GEMINI.md que utiliza nossas práticas recomendadas para o uso eficiente 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