Generador de consultas estáticas de informes

Visión General

El MiniQueryBuilder es una interfaz fluida para construir consultas tipo SQL en Gaio DataOS. Proporciona una forma simple e intuitiva de crear consultas utilizando cláusulas como:

• SELECT

• FROM

• WHERE (filter)

• GROUP BY

• ORDER BY

• LIMIT

• OFFSET

---

Uso Básico

// Access the query builder through context.query
const results = await context.query
  .select(['id', 'name', 'created_at'])
  .from('users')
  .filter('status', 'eq', 'active')
  .orderBy('created_at', 'desc')
  .limit(100)
  .run();

Referencia de la API

Constructor

El constructor de consultas se accede mediante el objeto context:

// You don't need to create an instance - use context.query
const query = context.query;

Métodos Disponibles

select(fields: string[])

Especifica los campos a seleccionar en la consulta.

context.query.select(['id', 'name', 'email']);

from(table: string)

Especifica la tabla desde la cual consultar. Este método es obligatorio.

context.query.from('users');

filter(field: string, operator: FilterOperator, value: any)

Agrega una condición de filtro a la consulta.

context.query.filter('age', 'gt', 18);

Operadores Disponibles

• eq → igual

• neq → distinto

• gt → mayor que

• gte → mayor o igual que

• lt → menor que

• lte → menor o igual que

• like → coincidencia de patrón con %

• ilike → coincidencia de patrón sin distinguir mayúsculas/minúsculas

• in → dentro de una lista de valores

• is → verificación de null

• cs → contiene (para arrays)

• cd → contenido por (para arrays)

• ov → superposición (para arrays)

• fts → búsqueda de texto completo

• or → operador lógico OR

• and → operador lógico AND

groupBy(fields: string[])

Define los campos para agrupar resultados.

context.query.groupBy(['department', 'role']);

orderBy(field: string, direction: 'asc' | 'desc' = 'asc', nullsPosition?: 'first' | 'last')

Agrega una cláusula ORDER BY.

context.query.orderBy('created_at', 'desc', 'last');

limit(limit: number)

Define el número máximo de filas a devolver.

context.query.limit(100);

offset(offset: number)

Define cuántas filas omitir (para paginación).

context.query.offset(50);

run(): Promise<GenericType[]>

Ejecuta la consulta y devuelve una Promesa que resuelve un arreglo de resultados.

Usage

const results = await context.query
  .select(['id', 'name'])
  .from('users')
  .limit(100)
  .run();

Valor de Retorno

Devuelve una Promesa que resuelve en un arreglo de objetos (GenericType[]). Cada objeto representa una fila del resultado, con propiedades que coinciden con las columnas seleccionadas.

Validaciones

The run() method performs the following validations before executing the query:

• Ensures that the limit is a number

• Ensures that the limit does not exceed 10,000 rows

• Implicitly checks that the FROM clause is specified (through the build method)

Manejo de Errores

El método run() puede lanzar errores en los siguientes casos:

• Si el limit no es un número

  Error('Limit must be a number')

• Si el limit supera 10,000

  Error('Limit must be less than 10000')

• Si no se especifica la cláusula FROM

  Error('FROM clause is required. Use .from() to specify a table.')

• Si falla la solicitud a la API → El error del cliente API será propagado

---

Detalles de Implementación

El método run() envía una solicitud POST a:

api/table/query

Incluye el esquema de la consulta y los datos de la tarea, y luego extrae y devuelve los datos de la respuesta.

---

Ejemplos

Consulta Básica

const users = await context.query
  .select(['id', 'name', 'email'])
  .from('users')
  .limit(100)
  .run();

Consulta con Filtro

const activeUsers = await context.query
  .select(['id', 'name', 'email'])
  .from('users')
  .filter('status', 'eq', 'active')
  .run();

Consulta con Agregación

const departmentCounts = await context.query
  .select(['department', 'COUNT(*) as count'])
  .from('employees')
  .groupBy(['department'])
  .orderBy('count', 'desc')
  .run();

Paginación

const page = 2;
const pageSize = 50;

const paginatedUsers = await context.query
  .select(['id', 'name', 'email'])
  .from('users')
  .orderBy('id', 'asc')
  .limit(pageSize)
  .offset((page - 1) * pageSize)
  .run();