DB Query

DB Query

Tipo: db-query  ·  Paquete: Database Activities v1.0.3  ·  Salida: DataTable

Ejecuta una consulta SELECT y devuelve los resultados como una DataTable, lista para recorrer, filtrar o volcar a Excel. Es la actividad de lectura más común.

Cómo funciona

Ejecuta el SELECT sobre la conexión y carga todas sus filas en memoria en una DataTable, con una columna por cada columna del resultado. Usa parámetros @nombre y el campo params para los valores variables (ver consultas parametrizadas).

• Sesión: si no indicas session, usa la del body de DB Connect que la contiene.
• Parámetros: cada clave de params se envía como @clave (puedes escribirla con o sin @). Con odbc, los @nombre del SQL se cambian por ? en el orden en que aparecen; un nombre repetido envía su valor otra vez y un nombre sin valor en params se envía como NULL.
• Volumen: todo el resultado queda en memoria. Para tablas grandes, filtra y pagina en el SQL (WHERE, TOP/LIMIT) en lugar de traerlo todo.
• Tiempo de espera: rige el del driver para cada comando (no hay un parámetro propio).

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
sql	string	—	La sentencia SELECT. Usa @nombre para los valores variables. Admite varias líneas y expresiones.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
session	ZoanDbSession	—	Sesión de DB Connect. Dentro de un body se hereda automáticamente; fuera, pasa db.
params	Dictionary	—	Valores de los parámetros, como objeto { "nombre": valor }. Los valores pueden ser expresiones (clienteId). Textos, números, true/false y null se envían con su tipo; un valor que no sea un objeto se ignora.

Salida

Devuelve una DataTable con el primer conjunto de resultados de la consulta:

• Columnas: los nombres que devuelve el SELECT (usa alias AS para nombres claros), con el tipo de dato que entrega el driver (número, texto, fecha, booleano…).
• Filas: una por registro, en el orden del resultado (usa ORDER BY si el orden importa).
• Valores nulos: llegan como vacío de base de datos (DBNull); str(fila["Columna"]) los convierte en texto vacío.
• Sin coincidencias: una DataTable con las columnas y 0 filas (no es un error). Compruébalo con rowCount(tabla) == 0.

Recórrela con For Each y accede a las celdas con str(fila["Columna"]).

Ejemplo

DB Query
  sql    = "SELECT Id, Nombre, Saldo FROM Clientes WHERE Ciudad = @ciudad"
  params = { "ciudad": ciudadBuscada }
  → output: clientes

Log   message = "Clientes encontrados: " + rowCount(clientes)
For Each   items = clientes   itemVariable = fila
 └─ activities:
      Log   message = str(fila["Nombre"]) + ": " + num(fila["Saldo"])

Usa parámetros, no concatenación

Escribe WHERE Ciudad = @ciudad con params, no "WHERE Ciudad = '" + ciudad + "'". Los parámetros evitan errores con comillas y protegen contra la inyección SQL. Los nombres de tabla o columna no se pueden parametrizar: si vienen de una variable, valídalos contra una lista de valores permitidos.

Errores comunes

Mensaje	Causa y solución
'session' es obligatorio y debe ser una sesión de base de datos.	No hay sesión: la actividad está fuera de un body de DB Connect y no recibió session, o la variable no contiene una sesión.
'sql' es obligatorio.	Falta la consulta o la expresión dio vacío.
Error del motor: sintaxis, tabla o columna inexistente, parámetro sin declarar	El mensaje viene de la base de datos. Revisa el SQL y que cada @nombre tenga su clave en params.
Error del driver por conexión cerrada	La sesión ya se cerró con DB Close o al salir de su body. Ejecuta la consulta antes de cerrar.

Para errores transitorios (red, bloqueos) envuelve la consulta en un Retry; para el resto, en un Try / Catch.

Actividades relacionadas

• DB Scalar — cuando el SELECT devuelve un solo valor.
• DB Execute — para INSERT/UPDATE/DELETE.
• DataTable — filtrar, ordenar y resumir el resultado.