#SQLResource

Resource para ejecutar consultas basadas en configuraciones SQL guardadas o SQL dinámico, con datos provenientes de interfaces como flowSql:run / flowSql:runById. Es adecuado para informes, estadísticas, listas SQL personalizadas y otros escenarios. A diferencia de MultiRecordResource, SQLResource no depende de las colecciones; ejecuta consultas SQL directamente y admite paginación, vinculación de parámetros, variables de plantilla ({{ctx.xxx}}) y control del tipo de resultado.

Relación de herencia: FlowResource → APIResource → BaseRecordResource → SQLResource.

Formas de creación: ctx.makeResource('SQLResource') o ctx.initResource('SQLResource'). Para ejecutar basándose en una configuración guardada, utilice setFilterByTk(uid) (el UID de la plantilla SQL); para depuración, utilice setDebug(true) + setSQL(sql) para ejecutar SQL directamente. En RunJS, ctx.api es inyectado por el entorno de ejecución.

#Escenarios de uso

#Formato de datos

• getData() devuelve diferentes formatos según setSQLType():
  • selectRows (predeterminado): Array, resultados de varias filas.
  • selectRow: Objeto único.
  • selectVar: Valor escalar (por ejemplo, COUNT, SUM).
• getMeta() devuelve metadatos como la paginación: page, pageSize, count, totalPage, etc.

#Configuración de SQL y modos de ejecución

#Parámetros y contexto

#Paginación

En SQL, puede utilizar {{ctx.limit}} y {{ctx.offset}} para hacer referencia a los parámetros de paginación. SQLResource inyecta automáticamente limit y offset en el contexto.

#Obtención de datos y eventos

#Ejemplos

#Ejecución mediante plantilla guardada (runById)

ctx.initResource('SQLResource');
ctx.resource.setFilterByTk('active-users-report'); // UID de la plantilla SQL guardada
ctx.resource.setBind({ status: 'active' });
await ctx.resource.refresh();
const data = ctx.resource.getData();
const meta = ctx.resource.getMeta(); // page, pageSize, count, etc.

#Modo de depuración: Ejecución de SQL directamente (runBySQL)

const res = ctx.makeResource('SQLResource');
res.setDebug(true);
res.setSQL('SELECT * FROM users WHERE status = :status LIMIT {{ctx.limit}}');
res.setBind({ status: 'active' });
await res.refresh();
const data = res.getData();

#Paginación y navegación

ctx.resource.setFilterByTk('user-list-sql');
ctx.resource.setPageSize(20);
await ctx.resource.refresh();

// Navegación
await ctx.resource.next();
await ctx.resource.previous();
await ctx.resource.goto(3);

#Tipos de resultados

// Múltiples filas (predeterminado)
ctx.resource.setSQLType('selectRows');
const rows = ctx.resource.getData(); // [{...}, {...}]

// Fila única
ctx.resource.setSQLType('selectRow');
const row = ctx.resource.getData(); // {...}

// Valor único (ej. COUNT)
ctx.resource.setSQLType('selectVar');
const total = ctx.resource.getData(); // 42

#Uso de variables de plantilla

ctx.defineProperty('minId', { get: () => 10 });
const res = ctx.makeResource('SQLResource');
res.setDebug(true);
res.setSQL('SELECT * FROM users WHERE id > {{ctx.minId}} LIMIT {{ctx.limit}}');
await res.refresh();

#Escuchar el evento refresh

ctx.resource?.on?.('refresh', () => {
  const data = ctx.resource.getData();
  ctx.render(<ul>{data?.map((r) => <li key={r.id}>{r.name}</li>)}</ul>);
});
await ctx.resource?.refresh?.();

#Notas

• runById requiere guardar la plantilla primero: El UID utilizado en setFilterByTk(uid) debe ser un ID de plantilla SQL ya guardado en la interfaz de administración. Puede guardarlo a través de ctx.sql.save({ uid, sql }).
• El modo de depuración requiere permisos: setDebug(true) utiliza flowSql:run, lo que requiere que el rol actual tenga permisos de configuración de SQL. runById solo requiere que el usuario haya iniciado sesión.
• Antirrebote (Debouncing) de Refresh: Múltiples llamadas a refresh() dentro del mismo ciclo de eventos solo ejecutarán la última para evitar solicitudes redundantes.
• Vinculación de parámetros para prevención de inyecciones: Utilice setBind() con marcadores :name o ? en lugar de la concatenación de cadenas para evitar la inyección de SQL.

#Relacionado

• ctx.sql - Ejecución y gestión de SQL; ctx.sql.runById es adecuado para consultas simples y puntuales.
• ctx.resource - La instancia del recurso en el contexto actual.
• ctx.initResource() - Inicializa y vincula a ctx.resource.
• ctx.makeResource() - Crea una nueva instancia de recurso sin vincularla.
• APIResource - Recurso de API general.
• MultiRecordResource - Diseñado para colecciones y listas.