Leer consulta

La operación Leer consulta te permite escribir tu propia consulta para extraer los datos de una entidad, en lugar de la lectura por defecto de toda la tabla o colección. Te da control completo sobre cómo se recuperan los datos y se ejecuta antes de cualquier operación de transformación en el pipeline.

En la cuadrícula de operaciones aparece en Operaciones de consulta como Leer consulta ("Utilice una query SQL/no-sql para extraer datos del tap").

Resumen

La operación Leer consulta te permite:

• Escribir sentencias SQL SELECT, consultas SOQL, o filtros y pipelines de agregación de MongoDB
• Unir tablas, filtrar registros y agregar datos según sea necesario
• Aplicar una consulta distinta a cada entidad
• Usar variables del proyecto dentro de la consulta
• Probar la consulta contra el tap antes de guardarla

Configuración

Personalización de Consultas a Nivel de Entidad

La operación muestra la lista de entidades del modelo, con una caja Buscar entidades encima. Cada entidad tiene tres iconos:

En la operación solo se guardan las entidades con consulta. El resto se leen como siempre.

Editor de consultas

El editor se abre en una ventana titulada Editar entidad - <entidad> con dos pestañas:

• Consulta: el texto de la consulta. Es obligatorio ("Se requiere el texto de consulta"). El texto de ejemplo muestra SELECT * FROM <entidad> y un ejemplo de agregación de MongoDB.
• Lista de Campos: los campos de la entidad en el esquema, con su Campo, Tipo y Tamaño. Úsala para comprobar que la consulta devuelve las columnas que la entidad espera.

El botón de la esquina superior derecha de la caja de texto (Mostrar variables) lista las variables del proyecto. Al elegir una se inserta $(nombre) en el cursor. Las variables se sustituyen por su valor al probar la consulta y al ejecutar el job.

Sintaxis de la consulta

La consulta debe devolver los campos que la entidad espera, con los mismos nombres, porque las operaciones posteriores y el sink trabajan con el esquema de la entidad.

Probar consulta

El botón Probar consulta ejecuta la consulta contra el tap del modelo y muestra el resultado debajo del editor:

• La consulta se ejecutó exitosamente, "Se obtuvieron N registro(s)". La prueba lee como máximo 5 registros, así que N está entre 0 y 5. Solo cuenta registros; no se muestran datos.
• La consulta tiene errores, seguido del mensaje de error que devuelve la base de datos.
• "Ocurrió un error inesperado al probar la consulta" cuando la prueba no se pudo ejecutar.

La prueba usa las variables del proyecto, así que $(nombre) se sustituye igual que en un job. Las variables que no existen se dejan tal cual, y normalmente la base de datos dará un error.

Al editar el texto de la consulta, el último resultado se borra.

Guardar la consulta

Guardar también prueba la consulta:

• Si la última Probar consulta fue correcta y el texto no ha cambiado desde entonces, la consulta se guarda directamente.
• Si no, primero se prueba la consulta. Solo se guarda si la prueba es correcta. Si falla, se muestra el error y la ventana sigue abierta para que puedas corregir la consulta.

Para probar hace falta el permiso ManageRules y que el tap esté accesible.

 Guardar
  │
  ├── ¿última prueba OK? ── sí ──► guardada
  │
  └── no ──► se prueba (máx. 5 registros)
               ├── OK ─────► guardada
               └── error ──► "La consulta tiene errores", no se guarda

Cómo se usa la consulta

• La consulta sustituye a la lectura por defecto de la entidad, así que las condiciones de Donde, los campos seleccionados y el Orden de esa entidad no se aplican. Ponlos en la consulta.
• El número de registros de Límite se aplica a la consulta en todas las bases de datos, siempre tomando los primeros registros:

• Un ;, las líneas en blanco y los comentarios al final de una consulta SQL se quitan antes de ejecutarla, para que no rompan la subconsulta.
• Tu propio LIMIT, FETCH FIRST, TOP u ORDER BY queda dentro de la subconsulta: el job lee como mucho los registros que devuelve tu consulta, y nunca más que el Límite.
• Los taps SQLite también ejecutan la Leer consulta.

Grupos de entidades

Cuando la entidad es la entidad principal de un grupo de entidades, escribe la consulta una sola vez en la entidad principal. Al ejecutarse el job, cada partición del grupo recibe una copia de esa consulta en la que cada aparición del nombre de la entidad principal se sustituye por el nombre de la partición:

Entidad principal orders:  SELECT * FROM orders WHERE status = 'paid'
Partición orders_202401:   SELECT * FROM orders_202401 WHERE status = 'paid'
Partición orders_202402:   SELECT * FROM orders_202402 WHERE status = 'paid'

• La consulta de una partición se sustituye por la copia, aunque hayas escrito una en la propia partición.
• La sustitución es un reemplazo de texto del nombre de la entidad, con las mismas mayúsculas y minúsculas, tal como aparece en la lista de entidades. Escribe el nombre de la tabla en la consulta exactamente así y evita otros nombres que lo contengan (con la entidad principal orders, un join con orders_items pasaría a ser orders_202401_items).
• Qué grupos se expanden depende de la operación incluir/excluir de la regla, igual que en las demás operaciones. Ver Grupos en las reglas.

Garantizar integridad referencial

Debajo de la lista de entidades está la casilla Garantizar integridad referencial. Es la misma opción que en Donde, Límite y Sintetizar: si está marcada en cualquiera de estas operaciones, se activa para toda la regla. En Leer consulta, Donde y Límite la casilla solo se muestra en taps SQL (Postgres, MySQL, Google Cloud SQL, Oracle, MSSQL, DB2, SQLite y Databricks); en otros taps la opción no tiene efecto.

Con ella, una fila hija solo se extrae si también se extrae la fila padre a la que referencia. Cuando una entidad padre tiene una Leer consulta, sus hijas se comprueban contra las filas que devuelve esa consulta.

Ejemplos

Consulta Personalizada Básica

Para reemplazar la extracción predeterminada de una entidad de clientes con una consulta personalizada:

1. Añade la operación Leer consulta a tu regla
2. Haz clic en el lápiz de la entidad clientes
3. Escribe una consulta personalizada como:

SELECT customer_id, first_name, last_name, email, phone, created_date
FROM customers
WHERE status = 'active'
ORDER BY created_date DESC

4. Haz clic en Probar consulta y revisa el resultado
5. Haz clic en Guardar

Consulta con variables

Con una variable de proyecto country:

SELECT * FROM customers WHERE country = '$(country)'

El valor de la variable se pega tal cual en el texto, así que añade las comillas que necesite la base de datos.

Consulta Compleja con Uniones

Para crear una vista unificada de órdenes y datos de clientes:

SELECT o.order_id, o.order_date, o.total_amount,
       c.first_name, c.last_name, c.email,
       p.product_name, p.category
FROM orders o
JOIN customers c ON o.customer_id = c.customer_id
JOIN order_items oi ON o.order_id = oi.order_id
JOIN products p ON oi.product_id = p.product_id
WHERE o.order_date >= DATEADD(month, -6, GETDATE())

Agregación en MongoDB

Para leer solo los clientes activos sin el campo notes:

[
  { "$match": { "status": "active" } },
  { "$project": { "notes": 0 } }
]

Mejores Prácticas

• Usa Probar consulta antes de guardar y revisa la pestaña Lista de Campos
• Mantén las consultas lo más simples posible para mejor rendimiento
• Usa índices apropiadamente en tus consultas
• Haz que los nombres de las columnas coincidan con los nombres de los campos de la entidad
• Las variables se pegan en el texto de la consulta, así que usa solo valores de confianza

Esta operación proporciona a los usuarios avanzados la flexibilidad para extraer exactamente los datos que necesitan, evitando la necesidad de múltiples operaciones de filtrado.