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

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: para enviar feedback ou fazer perguntas sobre esta funcionalidade de pré-visualização, contacte [e-mail]

O agente de engenharia de dados permite-lhe usar o Gemini no BigQuery para criar, modificar e gerir pipelines de dados para carregar e processar dados no BigQuery. Com o agente de engenharia de dados, pode usar comandos de linguagem natural para gerar pipelines de dados a partir de várias origens de dados ou adaptar pipelines de dados existentes de acordo com as suas necessidades de engenharia de dados. O agente de engenharia de dados tem as seguintes funcionalidades:

• Linguagem natural para a criação de pipelines: o agente usa o Gemini para compreender os seus dados e interpretar as suas instruções em linguagem simples. 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 do pipeline necessário em ficheiros SQLX num repositório do Dataform. O agente opera no espaço de trabalho do Dataform, pelo que os pipelines do Dataform estão automaticamente disponíveis para o agente.

• Instruções do agente personalizado: 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 sua 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 pipelines: o agente valida qualquer código gerado para garantir que os pipelines de dados são funcionais.

Pode usar comandos de linguagem natural com o agente de engenharia de dados para criar ficheiros SQLX de tabelas, vistas, afirmações, declarações e operações. Por exemplo, pode usar o agente de engenharia de dados para fazer o seguinte:

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

Para ver mais exemplos de comandos que pode usar com o agente de engenharia de dados, consulte os comandos de exemplo.

Limitações

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

• O agente de engenharia de dados é uma oferta pré-DG e não se destina a utilização em produção.
• O agente de engenharia de dados não suporta comandos de linguagem natural para os seguintes tipos de ficheiros:
  • Blocos de notas
  • Preparação de dados
  • Javascript em qualquer SQLx
• O agente de engenharia de dados não consegue executar pipelines. Os utilizadores têm de rever e executar ou agendar 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 utilizador).
• O agente de engenharia de dados não pode pesquisar links Web nem URLs fornecidos através de instruções ou comandos diretos.
• Quando importa ficheiros num ficheiro de instruções do agente, a @sintaxe de importação só suporta caminhos que começam com ./, / ou uma letra.
• A funcionalidade de pré-visualização de dados só é suportada para tabelas, declarações ou consultas com a flag hasOutput definida como true.

Regiões suportadas

O Gemini no BigQuery usa Google Cloud para o equilíbrio de carga, pelo que funciona a nível global. Uma vez que o Gemini no BigQuery funciona a nível global, não pode escolher a região a usar.

Todos os pedidos do Dataform e do BigQuery são enviados para os respetivos pontos finais regionais, pelo que todos os dados e código permanecem na respetiva região.

O Gemini no BigQuery é publicado a partir das seguintes regiões:

Américas

• Iowa (us-central1)

Europa

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

Como o agente de engenharia de dados usa os seus dados

Para produzir respostas do agente de maior qualidade, o agente de engenharia de dados pode obter dados e metadados adicionais do BigQuery e do Catálogo universal do Dataplex, incluindo linhas de amostra de tabelas do BigQuery e perfis de análise de dados gerados no Catálogo universal do Dataplex. Estes dados não são usados para preparar o agente de engenharia de dados e são usados apenas durante as conversas com o agente como contexto adicional para informar as respostas do agente.

Antes de começar

Certifique-se de que o Gemini no BigQuery está ativado para o seu Google Cloud projeto. Para mais informações, consulte o artigo Configure o Gemini no BigQuery.

Também tem de 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 necessárias

Para receber as autorizações de que precisa para usar o Data Engineering Agent, peça ao seu administrador que lhe conceda as seguintes funções de IAM no projeto:

• Editor de código do Dataform (roles/dataform.codeEditor)
• Utilizador de tarefas do BigQuery (roles/bigquery.jobuser)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

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

Para usar o Data Engineering Agent no BigQuery, selecione uma das seguintes opções:

Pipelines do BigQuery

Pode usar o agente de engenharia de dados na interface das pipelines do BigQuery fazendo o seguinte:

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

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

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

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

5. No campo Pedir ao agente, introduza 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 introduzir um comando, clique em Enviar.

6. O Data Engineering Agent gera um pipeline de dados com base no seu comando.

O pipeline de dados gerado pelo agente de engenharia de dados é uma proposta de rascunho de um pipeline de dados. Pode clicar num nó do pipeline para rever a consulta SQLX gerada. Para aplicar o pipeline de dados sugerido pelo agente, clique em Aplicar.

Dataform

Pode usar o agente de engenharia de dados no Dataform fazendo o seguinte:

1. Aceda à página Dataform.

   Aceder ao 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 Pedir ao agente.

5. No comando Pedir ao agente apresentado, introduza 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 introduzir um comando, clique em Enviar.

Assim que o comando for enviado, o agente de engenharia de dados gera um pipeline de dados e modifica os ficheiros SQLX do Dataform com base no comando. O agente aplica estas alterações diretamente aos ficheiros do seu espaço de trabalho.

Reveja uma pipeline de dados

Num pipeline de dados gerado pelo Data Engineering Agent, pode clicar num nó do pipeline para o rever.

• O separador Configuração mostra a consulta SQLX gerada associada ao nó.
• O separador Pré-visualização de dados mostra a tabela de entrada e saída do ficheiro. Pode ver uma pré-visualização da transformação de dados através deste nó clicando em Executar tarefa para executar a tarefa com ou sem dependências.

Edite um pipeline de dados

Pode editar o pipeline de dados através do agente de engenharia de dados clicando em Pedir ao agente e introduzindo um comando que sugira uma alteração ao pipeline de dados.

Reveja as alterações propostas pelo agente de engenharia de dados e, de seguida, clique em Aplicar para aplicar as alterações.

Também pode editar uma consulta SQLX manualmente selecionando um nó do pipeline e, de seguida, clicando em Abrir.

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

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

Pode criar um GEMINI.MDficheiro de contexto como um ficheiro de instruções do agente para o agente de engenharia de dados. Pode criar ficheiros de instruções do agente para usar no seu espaço de trabalho local ou pode usar os mesmos ficheiros de instruções em vários pipelines de dados através de um repositório externo.

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

1. Em Pedir ao agente, clique em Instruções de pipeline.
2. No painel Instruções para o pipeline, clique em Criar ficheiro de instruções.

3. No ficheiro GEMINI.MD apresentado, introduza as suas instruções em linguagem natural.

   O exemplo seguinte mostra um ficheiro 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 Guardar.

Para informações sobre a melhor forma de estruturar os ficheiros de instruções do agente, consulte o artigo Práticas recomendadas com ficheiros de instruções do agente.

Carregue instruções do agente a partir de um repositório externo

Pode especificar um conjunto de instruções do agente para serem reutilizadas em vários pipelines de dados associando um repositório externo:

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

Importe ficheiros locais adicionais como instruções do agente

Também pode importar outros ficheiros de instruções para o agente de engenharia de dados no ficheiro GEMINI.md usando a sintaxe @file.md. Para mais informações, consulte o artigo Processador de importação de memória.

Resolva problemas de erros de data pipelines

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

Se o pipeline de dados gerado encontrar erros, pode pedir ao agente de engenharia de dados que diagnostique quaisquer falhas do pipeline de dados e proponha recomendações de resolução de problemas com os seguintes passos:

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

2. Na lista de execuções, encontre a execução da pipeline de dados com falhas. Pode identificar as execuções com falhas na coluna Estado da execução.

   

3. Passe o cursor do rato sobre o ícone e, de seguida, clique em Investigar. O Data Engineering Agent executa uma análise na execução do pipeline de dados para verificar se existem erros.

   

4. Assim que a análise estiver concluída, o agente de engenharia de dados gera um relatório na secção Observações e hipóteses. Este relatório inclui:

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

Com o relatório de resolução de problemas do agente de engenharia de dados, pode implementar as recomendações manualmente. Também pode dar instruções ao agente de engenharia de dados para aplicar a correção por si através dos seguintes passos:

1. Copie as sugestões no relatório de resolução de problemas.
2. Volte ao agente de engenharia de dados:
   1. Se estiver a usar pipelines do BigQuery, aceda à página dos pipelines e, de seguida, clique em Pedir ao agente.
   2. Se estiver a usar o Dataform, clique em Pedir ao agente.
3. Cole as sugestões no comando e dê instruções ao agente de engenharia de dados para fazer as correções diretamente no seu pipeline de dados.
4. Clique em Enviar.

Exemplos de comandos

As secções seguintes mostram alguns exemplos de comandos que pode usar com o agente de engenharia de dados para desenvolver o seu pipeline de dados.

Agregue dados existentes numa nova tabela

Com este comando, o agente de engenharia de dados usa o esquema e os exemplos para inferir o agrupamento de dados por chave. Normalmente, o agente configura 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.

Adicione verificações de qualidade de dados a uma tabela existente

Com este comando, o agente infere verificações de qualidade razoáveis para a tabela com base no esquema e nos exemplos. Também pode adicionar algumas afirmações opinativas como parte do comando.

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

Crie uma nova coluna derivada e adicione verificações de qualidade dos dados à nova tabela

O comando seguinte mostra como pode 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'.

Crie FUDs 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 utilizador (UDFs). Embora o agente não crie efetivamente a FUD, pode criar a FUD executando o pipeline de dados. Estas FDU podem ser usadas em definições de modelos no seu 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 secções seguintes 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 pedidos comuns. Se aplicar frequentemente técnicas ou fizer as mesmas correções ao agente, use as instruções do agente como uma localização centralizada para armazenar instruções e pedidos comuns.

Dê mais contexto ao agente. Pode dar ao agente contexto adicional do catálogo universal do Dataplex anexando termos do glossário a tabelas e colunas do BigQuery e gerando análises de perfis de dados. Os termos do glossário podem ser usados para etiquetar colunas que requerem contexto adicional, como colunas que contêm informações de identificação pessoal (IIP) que requerem instruções de processamento especiais, ou para identificar colunas correspondentes com nomes diferentes em várias tabelas. As análises de perfis de dados dão ao agente uma melhor compreensão da distribuição de dados nas colunas de uma tabela e podem ajudar o agente a criar afirmações de qualidade de dados mais específicas. Para mais informações, consulte o artigo Acerca da criação de perfis de dados.

Escrever com clareza. Indique o seu pedido de forma clara e evite ser vago. Sempre que possível, indique as origens de dados de origem e de destino quando receber um pedido, como no exemplo seguinte:

  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 pedidos diretos e específicos. Faça uma pergunta de cada vez e mantenha os comandos concisos. Para comandos com mais do que uma pergunta, pode detalhar cada parte distinta da pergunta para melhorar a clareza, como se vê no seguinte exemplo:

  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 realce os termos principais. Pode realçar termos ou conceitos importantes nos seus comandos e etiquetar determinados requisitos como importantes, como se vê no exemplo seguinte:

  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 ''.

Especifique a ordem das operações. Para tarefas ordenadas, pode estruturar o comando em listas, em que os itens listados são divididos em passos pequenos e focados, como no exemplo seguinte:

  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 repita. Continue a experimentar diferentes expressões e abordagens para ver o que gera os melhores resultados. Se o agente gerar SQL inválido ou outros erros, dê orientações ao agente através de 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 ficheiros de instruções do agente

Crie ficheiros de instruções do agente para personalizar o agente de engenharia de dados de acordo com as suas necessidades. Quando usar instruções do agente, recomendamos que faça o seguinte:

• Todos os caminhos de ficheiros 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 ficheiros importados no formato 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 partilhar instruções em pipelines de dados, armazene as instruções num repositório do Dataform central e associe-as ao repositório do Dataform de trabalho. Pode usar instruções locais para substituir as regras centrais para o comportamento específico do pipeline.
• A utilização de títulos e listas no ficheiro de instruções do agente pode ajudar a organizar e clarificar as instruções para o agente de engenharia de dados.
• Atribua nomes de ficheiros significativos e agrupe instruções semelhantes num ficheiro. Organize as regras de forma lógica por categoria, caraterística ou funcionalidade através de títulos em Markdown.
• Para evitar instruções contraditórias, defina claramente as condições específicas em que cada instrução se aplica.
• Itere e refine os seus comandos e fluxo de trabalho. O comportamento dos agentes muda ao longo do tempo com as implementações de agentes e as atualizações de modelos, por isso, recomendamos que itere as suas regras com comandos diferentes para identificar áreas que possam precisar de melhorias. Mantenha o ficheiro de regras sincronizado com quaisquer alterações à sua pipeline de dados.

O exemplo seguinte mostra um ficheiro de instruções do agente denominado GEMINI.md que usa as nossas práticas recomendadas para uma utilização 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