DB Scalar

Tipo: db-scalar · Paquete: Database Activities v1.0.3 · Salida: object

Ejecuta un SELECT que devuelve un solo valor y lo devuelve directamente. Es la forma cómoda de obtener un dato puntual de la base de datos: un conteo (COUNT(*)), un máximo (MAX(Fecha)), un total (SUM(Monto)), o el valor de una celda concreta — sin tener que manejar una DataTable.

Cómo funciona

Ejecuta la consulta y devuelve el valor de la primera columna de la primera fila; el resto del resultado se descarta. 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: igual que en DB Query: cada clave de params se envía como @clave; con odbc se convierten en ? posicionales.
También sirve para un INSERT que devuelve la clave generada (por ejemplo INSERT … OUTPUT INSERTED.Id en SQL Server o INSERT … RETURNING id en PostgreSQL).

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
`sql`	`string`	—	Una sentencia SQL que devuelve un único valor. 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; textos, números, `true`/`false` y `null` se envían con su tipo.

Salida

Devuelve un object con el valor, con el tipo que entrega el driver: número entero o decimal, texto, fecha, booleano… El tipo exacto depende del motor (por ejemplo, COUNT(*) es un entero de 32 bits en SQL Server y de 64 bits en PostgreSQL y MySQL).

Sin filas o valor NULL: devuelve null. Compruébalo con isNull(valor) o conviértelo con num(valor) (da 0) o str(valor) (da "").

Ejemplo

Contar los pedidos pendientes de un cliente:

DB Scalar
  sql    = "SELECT COUNT(*) FROM Pedidos WHERE ClienteId = @id AND Estado = 'pendiente'"
  params = { "id": clienteId }
  → output: pendientes

If   condition = num(pendientes) > 0
 └─ then:
      Log   message = "El cliente tiene " + str(pendientes) + " pedidos pendientes"

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`.
`'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 los nombres de `params`.
Error al convertir el resultado en una expresión posterior	La consulta no devolvió filas y el valor es `null`. Usa `num(…)` o `str(…)`, que toleran `null`, en lugar de `toNumber(…)`.

Actividades relacionadas

DB Query — para resultados de varias filas.
DB Execute — para modificar datos.