#SQLResource

Um Resource para executar consultas baseadas em configurações SQL salvas ou SQL dinâmico, com dados originados de interfaces como flowSql:run / flowSql:runById. É adequado para cenários como relatórios, estatísticas, listas SQL personalizadas, entre outros. Diferente do MultiRecordResource, o SQLResource não depende de coleções; ele executa consultas SQL diretamente e suporta paginação, vinculação de parâmetros (binding), variáveis de template ({{ctx.xxx}}) e controle do tipo de resultado.

Relação de herança: FlowResource → APIResource → BaseRecordResource → SQLResource.

Formas de criação: ctx.makeResource('SQLResource') ou ctx.initResource('SQLResource'). Para executar com base em uma configuração salva, use setFilterByTk(uid) (o UID do template SQL); para depuração, você pode usar setDebug(true) + setSQL(sql) para executar o SQL diretamente. No RunJS, o ctx.api é injetado pelo ambiente de execução.

#Cenários de uso

#Formato de dados

• getData() retorna diferentes formatos com base em setSQLType():
  • selectRows (padrão): Array, resultados de múltiplas linhas.
  • selectRow: Objeto único.
  • selectVar: Valor escalar (ex: COUNT, SUM).
• getMeta() retorna metadados como paginação: page, pageSize, count, totalPage, etc.

#Configuração SQL e modos de execução

#Parâmetros e Contexto

#Paginação

No SQL, você pode usar {{ctx.limit}} e {{ctx.offset}} para referenciar os parâmetros de paginação. O SQLResource injeta automaticamente limit e offset no contexto.

#Busca de dados e eventos

#Exemplos

#Executando via template salvo (runById)

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

#Modo Debug: Executando SQL diretamente (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();

#Paginação e Navegação

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

// Navegação
await ctx.resource.next();
await ctx.resource.previous();
await ctx.resource.goto(3);

#Tipos de resultado

// Múltiplas linhas (padrão)
ctx.resource.setSQLType('selectRows');
const rows = ctx.resource.getData(); // [{...}, {...}]

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

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

#Usando variáveis de template

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

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

#Observações

• runById requer salvar o template primeiro: O UID usado em setFilterByTk(uid) deve ser um ID de template SQL já salvo na interface de administração. Você pode salvá-lo via ctx.sql.save({ uid, sql }).
• Modo debug requer permissões: setDebug(true) utiliza flowSql:run, o que exige que o cargo atual tenha permissões de configuração SQL. O runById exige apenas que o usuário esteja logado.
• Debounce de refresh: Múltiplas chamadas para refresh() dentro do mesmo loop de eventos executarão apenas a última para evitar requisições redundantes.
• Vinculação de parâmetros para prevenção de injeção: Use setBind() com placeholders :name ou ? em vez de concatenação de strings para evitar injeção de SQL.

#Relacionados

• ctx.sql - Execução e gerenciamento de SQL; ctx.sql.runById é adequado para consultas simples e pontuais.
• ctx.resource - A instância de resource no contexto atual.
• ctx.initResource() - Inicializa e vincula ao ctx.resource.
• ctx.makeResource() - Cria uma nova instância de resource sem vincular.
• APIResource - Recurso de API geral.
• MultiRecordResource - Voltado para coleções e listas.