Usa el Agente de ingeniería de datos para compilar y modificar canalizaciones de datos

Versión preliminar

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales 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.

Nota: Para enviar comentarios o hacer preguntas sobre esta función en versión preliminar, comunícate con [e-mail]

El agente de ingeniería de datos te permite usar Gemini en BigQuery para compilar, 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 a partir de varias fuentes de datos o adaptar las canalizaciones de datos existentes para que se ajusten a tus necesidades de ingeniería de datos. El agente de ingeniería de datos tiene las siguientes funciones:

• Lenguaje natural para la creación de canalizaciones: El agente usa Gemini para comprender tus datos y tus instrucciones en lenguaje natural. Puedes usar instrucciones en lenguaje natural para que el agente de ingeniería de datos compile o edite canalizaciones de datos.

• Integración de Dataform: El agente genera y organiza el código de canalización necesario en archivos SQLX dentro de un repositorio 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.

• Instrucciones personalizadas del agente: Crea instrucciones del agente en lenguaje sencillo para definir reglas personalizadas para el agente de Ingeniería de datos. Las instrucciones del agente persisten en toda tu organización y pueden ser útiles para aplicar reglas en toda la organización, como convenciones de nomenclatura o guías de estilo.

• Validación de canalizaciones: El agente valida cualquier código generado para garantizar que las canalizaciones de datos funcionen correctamente.

Puedes usar instrucciones en lenguaje natural con el agente de ingeniería de datos para crear archivos SQLX de tablas, vistas, aserciones, declaraciones y operaciones. Por ejemplo, puedes usar el Agente de Ingeniería de Datos para hacer lo siguiente:

• Carga datos desde fuentes de datos externas, como Cloud Storage, en varios formatos, como CSV, AVRO o PARQUET.
• Crea o usa rutinas existentes de BigQuery (UDF) para realizar análisis y transformaciones personalizados en tus datos.
• Define lineamientos reutilizables para el agente en lenguaje natural.

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

Limitaciones

El Agente de Ingeniería de Datos tiene las siguientes limitaciones:

• El Agente de ingeniería de datos es una oferta previa a la DG y no está diseñado para usarse en producción.
• El agente de ingeniería de datos no admite comandos en lenguaje natural para los siguientes tipos de archivos:
  • Notebooks
  • Preparación de datos
  • JavaScript en cualquier SQLx
• El agente de ingeniería de datos no puede ejecutar canalizaciones. Los usuarios deben revisar y ejecutar o programar canalizaciones.
• El agente de ingeniería de datos no puede validar el código SQL que depende de recursos intermedios inexistentes sin la invocación completa de la canalización (activada por el usuario).
• El agente de ingeniería de datos no puede buscar vínculos web ni URLs proporcionados a través de instrucciones o mensajes directos.
• Cuando importas 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 es compatible con tablas, declaraciones o consultas con la marca hasOutput establecida en true.

Regiones admitidas

Gemini en BigQuery usa Google Cloudpara el balanceo de cargas, por lo que opera a nivel global. Dado que Gemini en BigQuery opera a nivel global, no puedes elegir qué región usar.

Todas las solicitudes de Dataform y BigQuery se dirigen a sus respectivos extremos regionales, por lo que todos los datos y el código permanecen dentro de su región.

Gemini en BigQuery se ofrece en las siguientes regiones:

América

• Iowa (us-central1)

Europa

• Finlandia (europe-north1)
• Fráncfort (europe-west3)

Cómo usa tus datos el agente de ingeniería de datos

Para producir respuestas de mayor calidad, el agente de ingeniería de datos puede recuperar datos y metadatos adicionales de BigQuery y Dataplex Universal Catalog, incluidas filas de muestra de tablas de BigQuery y perfiles de análisis de datos generados en Dataplex Universal Catalog. Estos datos no se usan para entrenar al agente de ingeniería de datos, sino solo durante las conversaciones con el agente como contexto adicional para fundamentar sus respuestas.

Antes de comenzar

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

También debes habilitar la API de 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

Roles obligatorios

Para obtener los permisos 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)

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

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

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 haz clic en Comenzar. El agente no usa estas credenciales, pero son necesarias para que ejecutes la canalización de datos generada.

4. Haz clic en Try out the agent experience for data pipeline.

5. En el campo Pregúntale 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.
   

   Una vez que hayas ingresado 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.

La canalización de datos que genera el agente de ingeniería de datos es un borrador propuesto de una canalización de datos. Puedes hacer clic en un nodo de la canalización para revisar la consulta en 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 la página 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 Pregúntale al agente.

5. En la instrucción Pregúntale 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.
   

   Una vez que hayas ingresado una instrucción, haz clic en Enviar.

Una vez que envíes la instrucción, el agente de Ingeniería de datos generará una canalización de datos y modificará los archivos SQLX de Dataform según tu instrucción. El agente aplica estos cambios directamente a los archivos de tu espacio de trabajo.

Revisa una canalización de datos

En una canalización de datos generada por el agente de ingeniería de datos, puedes hacer clic en un nodo de canalización para revisarlo.

• En la pestaña Configuration, se muestra la consulta en SQLX generada asociada al nodo.
• En la pestaña Vista previa de los datos, se muestran las tablas de entrada y salida del archivo. Para ver 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.

Edita una canalización de datos

Para editar tu canalización de datos con el agente de ingeniería 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 de SQLX de forma manual. Para ello, selecciona un nodo de canalización y, luego, haz clic en Abrir.

Crea instrucciones para el agente de ingeniería de datos

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 de tu agente sean coherentes en toda la organización, por ejemplo, con las convenciones de nomenclatura o para aplicar una guía de estilo.

Puedes crear un archivo de contexto GEMINI.MD como 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.

Sigue estos pasos para crear instrucciones del agente:

1. En Preguntar al agente, haz clic en Instrucciones de canalización.
2. En el panel Instructions for pipeline, haz clic en Create instructions file.

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 para los archivos de instrucciones del agente.

Carga instrucciones del agente desde un repositorio externo

Puedes especificar un conjunto de instrucciones del agente para que se reutilicen en varias canalizaciones de datos vinculando 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 instrucciones del agente que desees usar con tu canalización de datos.
4. Haz clic en Guardar.

Importa archivos locales adicionales como instrucciones para el agente

También puedes importar otros archivos de instrucciones para el agente de ingeniería de datos en el archivo GEMINI.md con la sintaxis de @file.md. Para obtener más información, consulta Procesador de importación de memoria.

Soluciona problemas de errores en la canalización de datos

Si encuentras errores durante la generación de la canalización de datos, verifica que hayas cumplido con todos los requisitos previos necesarios para ejecutar el agente de Data Engineering. Para obtener más información, consulta Antes de comenzar.

Si la canalización de datos generada encuentra algún error, puedes indicarle al agente de ingeniería de datos que diagnostique cualquier falla de la canalización y proponga recomendaciones para solucionar problemas 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 fallida de la canalización de datos. Puedes identificar las ejecuciones fallidas en la columna Estado de la ejecución.

   

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 la ejecución de tu canalización de datos para detectar errores.

   

4. Una vez que se complete el análisis, el Agente de ingeniería de datos generará un informe en la sección Observations and Hypothesis. Este 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 prácticos o recomendaciones 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 con los siguientes 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 Pregúntale al agente.
3. Pega las sugerencias en la instrucción y pídele al agente de ingeniería de datos que realice las correcciones directamente en tu canalización de datos.
4. Haz clic en Enviar.

Ejemplos de instrucciones

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

Agrega los datos existentes en una tabla nueva

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

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

Agrega verificaciones de calidad de los datos a una tabla existente

Con esta instrucción, el agente infiere verificaciones de calidad razonables para la tabla según el esquema y las muestras. También puedes agregar algunas aserciones basadas en opiniones como parte de la instrucción.

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

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

La siguiente instrucción muestra cómo puedes agregar una tabla y una columna, y especificar verificaciones de calidad para 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 ejecutar la canalización de datos para crearla. 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

En las siguientes secciones, se sugieren prácticas recomendadas para trabajar con Data Engineering Agent y Dataform.

Prácticas recomendadas con el Agente de ingeniería de datos

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

Proporciona más contexto al agente. Puedes proporcionar contexto adicional al agente desde Dataplex Universal Catalog adjuntando términos del glosario a las tablas y columnas de BigQuery, y generando análisis de perfiles de datos. Los términos del glosario se pueden usar para etiquetar columnas que requieren contexto adicional, como las que contienen información de identificación personal (PII) que requiere instrucciones especiales de manejo, o para identificar columnas coincidentes con nombres diferentes en las tablas. Los análisis de perfil de datos proporcionan al agente una mejor comprensión de la distribución de datos dentro de las columnas de una tabla y pueden ayudarlo a crear aserciones de calidad de los datos más específicas. Para obtener más información, consulta Acerca de la generación de perfiles de datos.

Escribe con claridad. Indica tu solicitud con claridad y evita ser impreciso. 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. En el caso de las instrucciones con más de una pregunta, puedes enumerar 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. En el caso de las tareas ordenadas, puedes estructurar 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 código 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).

Prácticas recomendadas para usar archivos de instrucciones del agente

Crea archivos de instrucciones del agente para personalizar el Agente de ingeniería de datos según tus necesidades. Cuando uses instrucciones del agente, te recomendamos que hagas lo siguiente:

• Todas las rutas de acceso a los archivos en Dataform son relativas a la raíz del repositorio. Usa rutas de acceso relativas para cualquier sintaxis de @file.md para importar correctamente las instrucciones a GEMINI.md.
• Los archivos importados en GEMINI.md pueden contener importaciones, lo que puede crear una estructura anidada. Para evitar la recursión infinita, GEMINI.md tiene una profundidad máxima de importación de cinco niveles.
• Para compartir instrucciones entre canalizaciones de datos, almacénalas en un repositorio central de Dataform y vincúlalas al repositorio de Dataform en funcionamiento. Puedes usar instrucciones locales para anular las reglas centrales en relación con el comportamiento específico de la canalización.
• Usar encabezados y listas en el archivo de instrucciones del agente puede ayudar a organizar y aclarar las instrucciones para el agente de Data Engineering.
• Asigna nombres significativos a los archivos y agrupa las instrucciones similares en un mismo archivo. Organiza las reglas de forma lógica por categoría, función o funcionalidad con encabezados de Markdown.
• Para evitar instrucciones contradictorias, define claramente las condiciones específicas en las que se aplica cada instrucción.
• Itera y define mejor tus instrucciones y tu flujo de trabajo. El comportamiento del agente cambia con el tiempo a medida que se lanzan agentes y se actualizan los modelos, por lo que te recomendamos que realices iteraciones en tus reglas con diferentes instrucciones para identificar las áreas que podrían necesitar mejoras. Mantén tu archivo de reglas sincronizado con cualquier cambio en tu canalización de datos.

En el siguiente ejemplo, se muestra un archivo de instrucciones del agente llamado GEMINI.md que utiliza nuestras prácticas recomendadas para el uso eficaz del agente de ingeniería de datos:

  ### 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