Usar el agente de ingeniería de datos para crear y modificar flujos de procesamiento de datos

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Nota: Para enviar comentarios o hacer preguntas sobre esta función de vista previa, póngase en contacto con [e-mail]

El agente de ingeniería de datos te permite usar Gemini en BigQuery para crear, modificar y gestionar flujos de datos con el objetivo de cargar y procesar datos en BigQuery. Con el agente de ingeniería de datos, puedes usar peticiones en lenguaje natural para generar flujos de procesamiento de datos a partir de varias fuentes de datos o adaptar los flujos de procesamiento de datos que ya tengas para que se ajusten a tus necesidades de ingeniería de datos. Data Engineering Agent tiene las siguientes funciones:

• Lenguaje natural para la creación de flujos de procesamiento: el agente usa Gemini para entender tus datos e interpretar tus instrucciones en lenguaje natural. Puedes usar instrucciones en lenguaje natural para que el agente de ingeniería de datos cree o edite flujos de procesamiento de datos.

• Integración de Dataform: el agente genera y organiza el código de la 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 los flujos de procesamiento de Dataform están disponibles automáticamente para el agente.

• Instrucciones del agente personalizado: crea instrucciones del agente en lenguaje natural para definir reglas personalizadas para el agente de ingeniería de datos. Las instrucciones del agente se mantienen 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 la canalización: el agente valida el código generado para asegurarse de que las canalizaciones de datos funcionan.

Puedes usar peticiones 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:

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

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

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 disponibilidad general y no está pensada 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 flujos de trabajo. Los usuarios deben revisar y ejecutar o programar las canalizaciones.
• El agente de ingeniería de datos no puede validar el código SQL que depende de recursos intermediarios inexistentes sin invocar el flujo de procesamiento completo (activado por el usuario).
• El agente de ingeniería de datos no puede buscar enlaces web ni URLs proporcionados mediante instrucciones o peticiones directas.
• Al importar archivos en un archivo de instrucciones del agente, la sintaxis de importación @ solo admite rutas que empiecen por ./, / o una letra.
• La función Vista previa de datos solo se admite en tablas, declaraciones o consultas en las que la marca hasOutput esté definida como true.

Regiones disponibles

Gemini en BigQuery usa Google Cloud para el balanceo de carga, por lo que funciona a nivel mundial. Como Gemini en BigQuery funciona a nivel mundial, no puedes elegir qué región usar.

Todas las solicitudes de Dataform y BigQuery se dirigen a sus respectivos endpoints regionales, por lo que los datos y el código permanecen en 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 generar 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 ejemplo 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 que solo se utilizan durante las conversaciones con el agente como contexto adicional para fundamentar sus respuestas.

Antes de empezar

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

También debes habilitar la API Data Analytics de Gemini.

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, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el proyecto:

• Editor de código de Dataform (roles/dataform.codeEditor)
• Usuario de tareas de BigQuery (roles/bigquery.jobuser)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Generar un flujo de procesamiento 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:

Pipelines de BigQuery

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

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, haz clic en arrow_drop_down Crear nuevo > Pipeline.

3. Seleccione una opción para las credenciales de ejecución y haga clic en Empezar. El agente no usa estas credenciales, pero son necesarias para que puedas ejecutar el flujo de procesamiento de datos generado.

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

5. En el campo Pregunta al agente, introduce una petición en lenguaje natural para generar un flujo de procesamiento 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 introducido una petición, haz clic en Enviar.

6. El agente de ingeniería de datos genera una canalización de datos basada en tu petición.

El flujo de procesamiento de datos generado por el agente de ingeniería de datos es un borrador propuesto de un flujo de procesamiento de datos. Puedes hacer clic en un nodo de la 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 Data Engineering Agent 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 Preguntar al agente.

5. En la petición Pregunta al agente que aparece, introduce una petición en lenguaje natural para generar un flujo de procesamiento 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 introducido una petición, haz clic en Enviar.

Una vez que se envía la petición, el agente de ingeniería de datos genera una canalización de datos y modifica los archivos SQLX de Dataform en función de la petición. El agente aplica estos cambios directamente a los archivos de tu espacio de trabajo.

Revisar un flujo de procesamiento de datos

En un flujo de procesamiento de datos generado por Data Engineering Agent, puedes hacer clic en un nodo del flujo para revisarlo.

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

Editar un flujo de datos

Puedes editar tu flujo de datos con el agente de ingeniería de datos haciendo clic en Preguntar al agente e introduciendo una petición que sugiera un cambio en el flujo de datos.

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

También puedes editar manualmente una consulta SQLX seleccionando un nodo de la canalización y haciendo clic en Abrir.

Crear 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 predefinidas. Usa instrucciones del agente si quieres que los resultados de tu agente sean coherentes en toda tu organización, por ejemplo, con 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 de agente para usarlos en tu espacio de trabajo local o usar los mismos archivos de instrucciones en varias canalizaciones de datos mediante un repositorio externo.

Para crear instrucciones para el agente, haz lo siguiente:

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

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

   En el siguiente ejemplo se muestra un archivo de instrucciones de 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 forma de estructurar los archivos de instrucciones del agente, consulta Prácticas recomendadas para los archivos de instrucciones del agente.

Cargar instrucciones del agente desde un repositorio externo

Puedes especificar un conjunto de instrucciones de agente para reutilizarlo en varias canalizaciones de datos vinculando un repositorio externo:

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

Importar archivos locales adicionales como instrucciones del agente

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

Solucionar errores de la canalización de datos

Si se produce algún error durante la generación de la canalización de datos, compruebe que ha completado todos los requisitos previos para ejecutar el agente de ingeniería de datos. Para obtener más información, consulta la sección Antes de empezar.

Si el flujo de procesamiento de datos generado detecta algún error, puedes pedirle al agente de ingeniería de datos que diagnostique los fallos y proponga recomendaciones para solucionar los problemas siguiendo estos pasos:

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

2. En la lista de ejecuciones, busque la ejecución de la canalización de datos que ha fallado. Puedes identificar las ejecuciones fallidas en la columna Estado de la ejecución.

   

3. Coloca el cursor sobre el icono y haz clic en Investigar. El agente de ingeniería de datos analiza la ejecución de tu flujo de procesamiento de datos para detectar errores.

   

4. Una vez que se haya completado el análisis, el agente de ingeniería de datos generará un informe en la sección Observaciones e hipótesis. 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 del fallo
   • Un conjunto de pasos o recomendaciones prácticos para resolver el problema identificado

Con el informe de solución de problemas del agente de ingeniería de datos, puede implementar las recomendaciones manualmente. También puedes indicar al agente de ingeniería de datos que aplique la corrección por ti siguiendo 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 tus canalizaciones y haz clic en Preguntar al agente.
   2. Si usas Dataform, haz clic en Preguntar al agente.
3. Pega las sugerencias en la petición e indica al agente de ingeniería de datos que aplique las correcciones directamente a tu flujo de datos.
4. Haz clic en Enviar.

Peticiones de ejemplo

En las siguientes secciones se muestran algunas peticiones de ejemplo que puedes usar con el agente de ingeniería de datos para desarrollar tu canalización de datos.

Agregar datos en una tabla nueva

Con esta petición, el agente de ingeniería de datos usa el esquema y las muestras para inferir la agrupación de datos por clave. Normalmente, el agente configura una nueva tabla con descripciones de la tabla y de las columnas.

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

Añadir comprobaciones de calidad de los datos a una tabla

Con esta petición, el agente infiere comprobaciones de calidad razonables para la tabla en función del esquema y de las muestras. También puedes añadir algunas aserciones subjetivas como parte de la petición.

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

Crear una columna derivada y añadir comprobaciones de calidad de los datos a la nueva tabla

En la siguiente petición se muestra cómo puedes añadir una tabla y una columna, y especificar comprobaciones 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'.

Crear funciones definidas por el usuario como parte de la definición del modelo

Data Engineering Agent también puede configurar el DDL para crear funciones definidas por el usuario (UDFs). Aunque el agente no creará la UDF, puedes crearla ejecutando la canalización de datos. Estas UDFs se pueden usar en las definiciones de modelos de tu flujo 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 el agente de ingeniería de datos y Dataform.

Prácticas recomendadas para usar el agente de ingeniería de datos

Utiliza instrucciones para agentes en las solicitudes habituales. Si hay técnicas que aplicas con frecuencia o si sueles hacer las mismas correcciones al agente, utiliza las instrucciones del agente como ubicación centralizada para almacenar instrucciones y solicitudes habituales.

Proporciona más contexto al agente. Puedes proporcionar contexto adicional al agente desde Dataplex Universal Catalog asociando términos de glosario a tablas y columnas de BigQuery, así como generando análisis de perfil de datos. Los términos del glosario se pueden usar para etiquetar columnas que requieran contexto adicional, como las que contengan información personal identificable (IPI) que requiera instrucciones de tratamiento especiales, o para identificar columnas coincidentes con nombres diferentes en distintas tablas. Los análisis de perfil de datos proporcionan al agente una mejor comprensión de la distribución de los datos en las columnas de una tabla y pueden ayudarle a crear aserciones de calidad de datos más específicas. Para obtener más información, consulta el artículo Acerca de la creación de perfiles de datos.

Escribe con claridad. Indica tu solicitud de forma clara y evita ser ambiguo. Si es posible, proporcione fuentes de datos de origen y destino al hacer peticiones, 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.

Haz peticiones directas y específicas. Haz las preguntas de una en una y procura que sean concisas. En las peticiones con más de una pregunta, puedes desglosar cada parte 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).

Da instrucciones explícitas y destaca los términos clave. Puedes destacar términos o conceptos clave en tus peticiones 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 petición en listas, donde los elementos se dividen en pasos pequeños y específicos, 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.

Perfecciona y repite. Prueba diferentes frases y enfoques para ver qué te da los mejores resultados. Si el agente genera código SQL no válido u 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 de agentes

Crea archivos de instrucciones para el agente para personalizar el agente de ingeniería de datos y adaptarlo a tus necesidades. Cuando utilices instrucciones para el agente, te recomendamos que hagas lo siguiente:

• Todas las rutas de archivo de Dataform son relativas a la raíz del repositorio. Usa rutas relativas para cualquier sintaxis @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 flujos de procesamiento de datos, almacena las instrucciones en un repositorio de Dataform central y vincúlalas al repositorio de Dataform de trabajo. Puedes usar instrucciones locales para anular las reglas centrales y definir comportamientos específicos de una canalización.
• Usar encabezados y listas en el archivo de instrucciones del agente puede ayudar a organizar y aclarar las instrucciones del agente de ingeniería de datos.
• Asigna nombres de archivo descriptivos y agrupa las instrucciones similares en un archivo. Organiza las reglas de forma lógica por categoría, función o funcionalidad mediante encabezados de Markdown.
• Para evitar que haya instrucciones contradictorias, define claramente las condiciones específicas en las que se aplica cada instrucción.
• Repite y perfecciona tus peticiones y tu flujo de trabajo. El comportamiento de los agentes cambia con el tiempo a medida que se lanzan agentes y se actualizan modelos, por lo que te recomendamos que repitas tus reglas con diferentes peticiones para identificar las áreas que puedan necesitar mejoras. Mantén el archivo de reglas sincronizado con los cambios que hagas en tu canalización de datos.

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

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