Usa el agente de ingeniería de datos para crear y modificar canalizaciones de datos

En este documento, se muestra cómo usar el agente de ingeniería de datos en BigQuery y Dataform para crear y modificar canalizaciones de datos.

El agente de ingeniería de datos te permite crear, modificar y administrar canalizaciones de datos para cargar y procesar datos en BigQuery. Con el agente de ingeniería de datos, puedes usar instrucciones en lenguaje natural para generar canalizaciones de datos de varias fuentes de datos o adaptar las canalizaciones de datos existentes para satisfacer tus necesidades de ingeniería de datos.

El agente genera y organiza el código de la canalización de datos directamente en los repositorios de Dataform. El agente opera en el espacio de trabajo de Dataform, por lo que las canalizaciones de Dataform están disponibles automáticamente para el agente.

Para obtener más ejemplos de instrucciones que puedes usar con el agente de ingeniería de datos, consulta Ejemplos de instrucciones.

También puedes usar la API del agente de ingeniería de datos, que usa el protocolo A2A, para interactuar con el agente.

Limitaciones

El agente de ingeniería de datos tiene las siguientes limitaciones:

• El agente de ingeniería de datos no admite comandos en lenguaje natural para los siguientes tipos de archivos:
  • Notebooks
  • Preparación de datos
• El agente de ingeniería de datos no puede ejecutar canalizaciones. Debes revisar y ejecutar o programar canalizaciones.
• El agente de ingeniería de datos no puede buscar ningún vínculo web ni URL que se proporcione a través de instrucciones o instrucciones directas.
• Cuando se importan archivos en un archivo de instrucciones del agente, la sintaxis de importación @ solo admite rutas que comienzan con ./, /, o una letra.
• La función de vista previa de datos solo se admite para tablas, declaraciones o consultas con la marca hasOutput establecida en true.
• El agente de ingeniería de datos está sujeto a las limitaciones generales de la tecnología de IA.

Antes de comenzar

Antes de usar el agente de ingeniería de datos, realiza los pasos de esta sección.

Habilita Gemini en BigQuery

Asegúrate de que Gemini en BigQuery esté habilitado para tu Google Cloud proyecto. Para obtener más información, consulta Cómo configurar Gemini en BigQuery.

Habilita las API necesarias

Nota: Si no tienes permiso para habilitar las APIs, pídele al administrador del proyecto que las habilite por ti desde el panel de APIs y servicios. De manera alternativa, el administrador del proyecto puede otorgarte el rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin) en la Google Cloud consola, que te permite habilitar y deshabilitar las APIs para el proyecto actual.

Console

Habilita las siguientes APIs en la Google Cloud consola de para el Google Cloud proyecto que usas con la API de Conversational Analytics.

Habilita la API de Gemini Data Analytics

Habilita Gemini para la Google Cloud API

Habilita la API de BigQuery

Sugerencia:Después de habilitar una API, actualiza lapágina de la consola de para confirmar que esté habilitada.

Google Cloud

gcloud

Para habilitar la API de Gemini Data Analytics, Gemini para Google Cloud la API de y la API de BigQuery, usa la CLI de Google Cloud y ejecuta los siguientes 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

Reemplaza PROJECT_ID por el ID del Google Cloud proyecto.

Roles obligatorios

Para obtener el permiso que necesitas para usar el agente de ingeniería de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

• Editor de código de Dataform (roles/dataform.codeEditor)
• Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Usuario de chat sin estado de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentStatelessUser)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el geminidataanalytics.locations.useDataEngineeringAgent permiso, que se requiere para usar el agente de ingeniería de datos.

También puedes obtener este permiso con roles personalizados o otros roles predefinidos.

Requisitos previos para la integración de Knowledge Catalog

Para obtener los permisos que necesitas para integrar el agente de ingeniería de datos con Knowledge Catalog, pídele a tu administrador que te otorgue el rol de IAM de editor de catálogo de Dataplex (roles/dataplex.catalogEditor) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el geminidataanalytics.locations.useDataEngineeringAgent permiso, que se requiere para integrar el agente de ingeniería de datos con Knowledge Catalog.

También puedes obtener este permiso con roles personalizados o otros roles predefinidos.

También debes habilitar la API de Knowledge Catalog.

Encripta datos con claves de Cloud Key Management Service

Puedes encriptar datos a nivel del conjunto de datos o del proyecto con las claves predeterminadas de Cloud Key Management Service administradas por el cliente en BigQuery. Para obtener más información, consulta Establece una clave predeterminada del conjunto de datos y Establece una clave predeterminada del proyecto.

Puedes encriptar el código de la canalización a nivel del proyecto si estableces una clave predeterminada de Cloud Key Management Service de Dataform.

Configura perímetros de Controles del servicio de VPC

Si usas Controles del servicio de VPC, debes configurar el perímetro para proteger Dataform, BigQuery y la API de Conversational Analytics. Para obtener más información, consulta Dataform, BigQuery, y la API de Conversational Analytics.

Genera una canalización de datos con el agente de ingeniería de datos

Para usar el agente de ingeniería de datos en BigQuery, selecciona una de las siguientes opciones:

Canalizaciones de BigQuery

Para usar el agente de ingeniería de datos en la interfaz de canalizaciones de BigQuery, haz lo siguiente:

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el editor de consultas, haz clic en arrow_drop_down Crear nuevo > Canalización.

3. Selecciona una opción para las credenciales de ejecución y, luego, haz clic en Comenzar. El agente no usa estas credenciales, pero son necesarias para ejecutar la canalización de datos generada.

4. Haz clic en Probar la experiencia del agente para la canalización de datos.

5. En el campo Preguntar al agente , ingresa una instrucción en lenguaje natural para generar una canalización de datos, por ejemplo:

     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.
   

   Después de ingresar una instrucción, haz clic en Enviar.

6. El agente de ingeniería de datos genera una canalización de datos según tu instrucción.

El agente de ingeniería de datos genera un borrador propuesto de una canalización de datos. Puedes hacer clic en un nodo de canalización para revisar la consulta SQLX generada. Para aplicar la canalización de datos sugerida por el agente, haz clic en Aplicar.

Dataform

Para usar el agente de ingeniería de datos en Dataform, haz lo siguiente:

1. Ve a Dataform.

   Ir a Dataform

2. Selecciona un repositorio.

3. Selecciona o crea un espacio de trabajo de desarrollo.

4. En el espacio de trabajo, haz clic en Preguntar al agente.

5. En la instrucción Preguntar al agente que aparece, ingresa una instrucción en lenguaje natural para generar una canalización de datos, por ejemplo:

     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.
   

   Después de ingresar una instrucción, haz clic en Enviar.

Después de enviar la instrucción, el agente de ingeniería de datos genera una canalización de datos y modifica los archivos SQLX de Dataform según tu instrucción. El agente aplica estos cambios directamente a los archivos de tu espacio de trabajo.

Edita una canalización de datos

Para editar tu canalización de datos, haz clic en Preguntar al agente y, luego, ingresa una instrucción que sugiera un cambio en la canalización de datos.

Revisa los cambios propuestos por el agente de ingeniería de datos y, luego, haz clic en Aplicar para aplicarlos.

También puedes editar una consulta SQLX de forma manual. Para ello, selecciona un nodo de canalización y, luego, haz clic en Abrir.

Revisa una canalización de datos

Puedes hacer clic en un nodo de canalización en una canalización de datos generada por el agente de ingeniería de datos para revisarla.

• En la pestaña Configuración , se muestra la consulta SQLX generada asociada con el nodo.
• En la pestaña Vista previa de datos , se muestran la tabla de entrada y salida del archivo. Para obtener una vista previa de la transformación de datos a través de este nodo, haz clic en Ejecutar tarea para ejecutar la tarea con o sin dependencias.

Soluciona errores de canalización de datos

Si encuentras algún error durante la generación de la canalización de datos, verifica que hayas completado todos los requisitos previos para ejecutar el agente de ingeniería de datos. Para obtener más información, consulta Antes de comenzar.

Ejecuta una investigación de Gemini Cloud Assist

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para solucionar problemas adicionales de la canalización, puedes usar el agente de ingeniería de datos para ejecutar un análisis de causa raíz y sugerir recomendaciones para la solución de problemas.

Esta función usa las investigaciones de Gemini Cloud Assist (versión preliminar) y solo está disponible para los usuarios con un contrato de asistencia Premium. Para obtener más información sobre cómo habilitar las investigaciones de Gemini Cloud Assist, consulta Soluciona problemas con las investigaciones de Gemini Cloud Assist.

Puedes usar el agente de ingeniería de datos para solucionar errores de canalización de datos con los siguientes pasos:

1. En tu canalización o espacio de trabajo de desarrollo, haz clic en la pestaña Ejecuciones.

2. En la lista de ejecuciones, busca la ejecución de la canalización de datos fallida. Puedes identificar las ejecuciones fallidas en la columna Estado.

   

3. Coloca el cursor sobre el ícono y, luego, haz clic en Investigar. El agente de ingeniería de datos ejecuta un análisis de causa raíz (ACR) en la ejecución de tu canalización de datos para detectar errores.

   

4. Una vez que se completa el análisis, el agente de ingeniería de datos genera un informe en la sección Observaciones e hipótesis. El informe incluye lo siguiente:

   • Observaciones y puntos de datos extraídos de los registros de ejecución de la canalización de datos
   • Causas probables de la falla
   • Un conjunto de pasos o recomendaciones prácticas para resolver el problema identificado

Con el informe de solución de problemas del agente de ingeniería de datos, puedes implementar las recomendaciones de forma manual. También puedes indicarle al agente de ingeniería de datos que aplique la corrección por ti. Para ello, sigue estos pasos:

1. Copia las sugerencias del informe de solución de problemas.
2. Vuelve al agente de ingeniería de datos:
   1. Si usas canalizaciones de BigQuery, ve a la página de canalizaciones y, luego, haz clic en Preguntar al agente.
   2. Si usas Dataform, haz clic en Preguntar al agente.
3. Pega las sugerencias en la instrucción y, luego, indica al agente de ingeniería de datos que realice las correcciones directamente en tu canalización de datos.
4. Haz clic en Enviar.

Crea instrucciones del agente

Las instrucciones del agente son instrucciones en lenguaje natural para el agente de ingeniería de datos que te permiten almacenar instrucciones persistentes para que el agente siga un conjunto de reglas personalizadas y predefinidas. Usa instrucciones del agente si deseas que los resultados del agente sean coherentes en toda la organización, por ejemplo, con convenciones de nombres o para aplicar una guía de estilo.

Puedes crear un archivo de contexto GEMINI.MD como un archivo de instrucciones del agente para el agente de ingeniería de datos. Puedes crear archivos de instrucciones del agente para usarlos en tu espacio de trabajo local o usar los mismos archivos de instrucciones en varias canalizaciones de datos con un repositorio externo.

Para crear instrucciones del agente, haz lo siguiente:

1. En Preguntar al agente, haz clic en Instrucciones de canalización.
2. En el panel Instrucciones para la canalización, haz clic en Crear archivo de instrucciones.

3. En el archivo GEMINI.MD que aparece, ingresa tus instrucciones en lenguaje natural.

   En el siguiente ejemplo, se muestra un archivo de instrucciones del agente con varias reglas:

     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. Haz clic en Guardar.

Para obtener información sobre la mejor manera de estructurar los archivos de instrucciones del agente, consulta Prácticas recomendadas con archivos de instrucciones del agente.

Carga instrucciones del agente desde un repositorio externo

Para reutilizar un conjunto de instrucciones del agente en varias canalizaciones de datos, vincula un repositorio externo:

1. En Preguntar al agente, haz clic en Instrucciones de canalización.
2. En Repositorio externo, selecciona Usar instrucciones del repositorio externo.
3. En los campos proporcionados, especifica un repositorio que contenga las instrucciones del agente que deseas usar con tu canalización de datos.
4. Haz clic en Guardar.

Ejemplos de instrucciones

En las siguientes secciones, se proporcionan ejemplos de instrucciones que puedes usar con el agente de ingeniería de datos para desarrollar tu canalización de datos.

Agrega datos existentes a una tabla nueva

Con esta instrucción, el agente de ingeniería de datos usa el esquema y las muestras para inferir la agrupación de datos por clave. Por lo general, el agente configura una nueva configuración de tabla con descripciones de tabla y columna.

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

Crea una nueva columna derivada y agrega verificaciones de calidad de los datos a la tabla nueva

En esta instrucción, se muestra cómo agregar una tabla y una columna, y especificar verificaciones de calidad a la tabla al mismo tiempo:

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

Crea UDF como parte de la definición del modelo

El agente de ingeniería de datos también puede configurar el DDL para crear funciones definidas por el usuario (UDF). Si bien el agente no creará la UDF, puedes crearla ejecutando la canalización de datos. Estas UDF se pueden usar en las definiciones de modelos de tu canalización de datos.

  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ácticas recomendadas

Para mejorar los resultados cuando trabajes con el agente de ingeniería de datos y Dataform, te recomendamos que hagas lo siguiente:

Usa instrucciones del agente para solicitudes comunes. Si sueles aplicar ciertas técnicas o si realizas las mismas correcciones con frecuencia al agente, usa instrucciones del agente como una ubicación centralizada para almacenar instrucciones y solicitudes comunes.

Utiliza planes del agente. Los planes del agente pueden ser útiles para desglosar tareas complejas de canalización. Los planes del agente también pueden mostrarte las suposiciones y las intenciones del agente, por lo que te recomendamos que revises esos planes para asegurarte de que el agente reciba el contexto correcto.

Después de revisar un plan, puedes editarlo. Para ello, proporciona comentarios y cambios al agente de ingeniería de datos. Por ejemplo:

In the plan, ensure that all of the intermediate tables are views.

En algunos casos, puede ser útil pedirle al agente que genere un plan que no necesite tu aprobación explícita. El acto de crear el plan del agente obliga al agente de ingeniería de datos a desglosar sus acciones, lo que suele generar mejores resultados. Puedes obligar al agente a generar un plan y ejecutarlo automáticamente. Por ejemplo:

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.

Escribe con claridad. Expresa tu solicitud con claridad y evita ser ambiguo. Cuando sea posible, proporciona fuentes de datos de origen y destino cuando se te solicite, como se muestra en el siguiente ejemplo:

  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.

Proporciona solicitudes directas y con alcance. Haz una pregunta a la vez y mantén las instrucciones concisas. Para las instrucciones con más de una pregunta, enumera cada parte distinta de la pregunta para mejorar la claridad, como se muestra en el siguiente ejemplo:

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

Proporciona instrucciones explícitas y enfatiza los términos clave. Puedes agregar énfasis a los términos o conceptos clave en tus instrucciones y etiquetar ciertos requisitos como importantes, como se muestra en el siguiente ejemplo:

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

Especifica el orden de las operaciones. Para las tareas ordenadas, estructura tu instrucción en listas, en las que los elementos enumerados se dividen en pasos pequeños y enfocados, como se muestra en el siguiente ejemplo:

  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.

Define mejor e itera. Sigue probando diferentes frases y enfoques para ver cuál genera los mejores resultados. Si el agente genera SQL no válido o comete otros errores, guíalo con ejemplos o documentación 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).