#SQLResource

保存済みの SQL 設定または動的 SQLに基づいてクエリを実行するリソース（Resource）です。データソースは flowSql:run / flowSql:runById などのインターフェースから取得されます。レポート、統計、カスタム SQL リストなどのシナリオに適しています。MultiRecordResource とは異なり、SQLResource はデータテーブル（コレクション）に依存せず、SQL クエリを直接実行します。ページネーション、パラメータバインディング、テンプレート変数（{{ctx.xxx}}）、および結果タイプの制御をサポートしています。

継承関係: FlowResource → APIResource → BaseRecordResource → SQLResource。

作成方法: ctx.makeResource('SQLResource') または ctx.initResource('SQLResource')。保存済みの設定に従って実行する場合は setFilterByTk(uid)（SQL テンプレートの uid）が必要です。デバッグ時には setDebug(true) + setSQL(sql) を使用して SQL を直接実行できます。RunJS 内では、ctx.api は実行環境によって注入されます。

#適用シーン

#データ形式

• getData() は setSQLType() の設定に応じて異なる形式を返します：
  • selectRows（デフォルト）：配列。複数行の結果。
  • selectRow：単一のオブジェクト。
  • selectVar：スカラー値（COUNT、SUM など）。
• getMeta() はページネーションなどのメタ情報を返します：page、pageSize、count、totalPage など。

#SQL 設定と実行モード

#パラメータとコンテキスト

#ページネーション

SQL 内では {{ctx.limit}} や {{ctx.offset}} を使用してページネーションパラメータを参照できます。SQLResource はコンテキストに limit と offset を自動的に注入します。

#データ取得とイベント

#例

#保存済みテンプレートによる実行（runById）

ctx.initResource('SQLResource');
ctx.resource.setFilterByTk('active-users-report'); // 保存済み SQL テンプレートの uid
ctx.resource.setBind({ status: 'active' });
await ctx.resource.refresh();
const data = ctx.resource.getData();
const meta = ctx.resource.getMeta(); // page、pageSize、count など

#デバッグモード：SQL を直接実行（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();

#ページネーションとページ移動

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

// ページ移動
await ctx.resource.next();
await ctx.resource.previous();
await ctx.resource.goto(3);

#結果タイプ

// 複数行（デフォルト）
ctx.resource.setSQLType('selectRows');
const rows = ctx.resource.getData(); // [{...}, {...}]

// 単一行
ctx.resource.setSQLType('selectRow');
const row = ctx.resource.getData(); // {...}

// 単一値（例：COUNT）
ctx.resource.setSQLType('selectVar');
const total = ctx.resource.getData(); // 42

#テンプレート変数の使用

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

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

#注意事項

• runById は事前にテンプレートの保存が必要: setFilterByTk(uid) で指定する uid は、管理画面で保存済みの SQL テンプレート ID である必要があります。ctx.sql.save({ uid, sql }) を通じて保存することも可能です。
• デバッグモードには権限が必要: setDebug(true) の場合は flowSql:run を使用するため、現在のロールに SQL 設定権限が必要です。runById はログイン済みであれば実行可能です。
• refresh のデバウンス: 同一のイベントループ内で refresh() が複数回呼び出された場合、重複リクエストを避けるために最後の 1 回のみが実行されます。
• パラメータバインディングによるインジェクション対策: 文字列結合による SQL 構築を避け、setBind() と :name / ? プレースホルダーを組み合わせて使用してください。

#関連情報

• ctx.sql - SQL の実行と管理。ctx.sql.runById は単純な使い切りクエリに適しています。
• ctx.resource - 現在のコンテキストにおけるリソースインスタンス。
• ctx.initResource() - リソースを初期化し、ctx.resource にバインドします。
• ctx.makeResource() - バインドせずに新しいリソースインスタンスを作成します。
• APIResource - 汎用 API リソース。
• MultiRecordResource - データテーブル/リスト向けのリソース。