#SQLResource

Eine Resource zum Ausführen von Abfragen basierend auf gespeicherten SQL-Konfigurationen oder dynamischem SQL. Die Datenquelle stammt von Schnittstellen wie flowSql:run / flowSql:runById. Sie eignet sich für Berichte, Statistiken, benutzerdefinierte SQL-Listen und andere Szenarien. Im Gegensatz zur MultiRecordResource ist die SQLResource nicht von Sammlungen (Collections) abhängig; sie führt SQL-Abfragen direkt aus und unterstützt Paginierung, Parameterbindung, Vorlagenvariablen ({{ctx.xxx}}) sowie die Steuerung des Ergebnistyps.

Vererbungshierarchie: FlowResource → APIResource → BaseRecordResource → SQLResource.

Erstellungsmethode: ctx.makeResource('SQLResource') oder ctx.initResource('SQLResource'). Zur Ausführung basierend auf einer gespeicherten Konfiguration verwenden Sie setFilterByTk(uid) (die UID der SQL-Vorlage). Zum Debuggen können Sie setDebug(true) + setSQL(sql) verwenden, um SQL direkt auszuführen. In RunJS wird ctx.api durch die Laufzeitumgebung injiziert.

#Anwendungsbereiche

#Datenformat

• getData() gibt je nach setSQLType() unterschiedliche Formate zurück:
  • selectRows (Standard): Array, Ergebnisse mehrerer Zeilen.
  • selectRow: Einzelnes Objekt.
  • selectVar: Skalarer Wert (z. B. COUNT, SUM).
• getMeta() gibt Metainformationen wie die Paginierung zurück: page, pageSize, count, totalPage usw.

#SQL-Konfiguration und Ausführungsmodi

#Parameter und Kontext

#Paginierung

In SQL können Sie {{ctx.limit}} und {{ctx.offset}} verwenden, um auf Paginierungsparameter zuzugreifen. Die SQLResource injiziert limit und offset automatisch in den Kontext.

#Datenabruf und Ereignisse

#Beispiele

#Ausführung über eine gespeicherte Vorlage (runById)

ctx.initResource('SQLResource');
ctx.resource.setFilterByTk('active-users-report'); // UID der gespeicherten SQL-Vorlage
ctx.resource.setBind({ status: 'active' });
await ctx.resource.refresh();
const data = ctx.resource.getData();
const meta = ctx.resource.getMeta(); // page, pageSize, count usw.

#Debug-Modus: SQL direkt ausführen (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();

#Paginierung und Navigation

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

// Navigation
await ctx.resource.next();
await ctx.resource.previous();
await ctx.resource.goto(3);

#Ergebnistypen

// Mehrere Zeilen (Standard)
ctx.resource.setSQLType('selectRows');
const rows = ctx.resource.getData(); // [{...}, {...}]

// Einzelne Zeile
ctx.resource.setSQLType('selectRow');
const row = ctx.resource.getData(); // {...}

// Einzelner Wert (z. B. COUNT)
ctx.resource.setSQLType('selectVar');
const total = ctx.resource.getData(); // 42

#Verwendung von Vorlagenvariablen

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();

#Auf das refresh-Ereignis hören

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?.();

#Wichtige Hinweise

• runById erfordert vorheriges Speichern der Vorlage: Die in setFilterByTk(uid) verwendete UID muss eine SQL-Vorlagen-ID sein, die bereits in der Administrationsoberfläche gespeichert wurde. Sie können diese über ctx.sql.save({ uid, sql }) speichern.
• Debug-Modus erfordert Berechtigungen: setDebug(true) nutzt flowSql:run, was voraussetzt, dass die aktuelle Rolle über Berechtigungen zur SQL-Konfiguration verfügt. runById erfordert lediglich, dass der Benutzer angemeldet ist.
• Refresh-Debouncing: Mehrfache Aufrufe von refresh() innerhalb desselben Ereigniszyklus führen nur die letzte Anfrage aus, um redundante Anfragen zu vermeiden.
• Parameterbindung zur Vermeidung von Injektionen: Verwenden Sie setBind() mit :name oder ? Platzhaltern anstelle von String-Verkettungen, um SQL-Injektionen zu verhindern.

#Verwandte Themen

• ctx.sql – SQL-Ausführung und -Verwaltung; ctx.sql.runById eignet sich für einfache, einmalige Abfragen.
• ctx.resource – Die Resource-Instanz im aktuellen Kontext.
• ctx.initResource() – Initialisiert und bindet an ctx.resource.
• ctx.makeResource() – Erstellt eine neue Resource-Instanz ohne Bindung.
• APIResource – Allgemeine API-Resource.
• MultiRecordResource – Konzipiert für Sammlungen und Listen.