Este artigo apresenta o SQLVantage, um sistema de relatórios web leve que unifica consultas SQL, formulários paramétricos e apresentação de resultados num único fluxo de trabalho. Abordam-se a arquitetura do sistema, a instalação e implementação, a gestão do ciclo de vida completo dos relatórios e o componente central — o designer de relatórios com os módulos SQL, FORM e HTML. Discutem-se ainda os cenários de aplicação e as limitações práticas.
Uma ferramenta de relatórios web pronta a usar que ajuda a dominar facilmente todo o fluxo: consulta de dados, formulários de parâmetros e apresentação de resultados.
Na atividade diária das empresas, os relatórios de dados são uma componente indispensável. Seja para reconciliação financeira, análise de vendas ou monitorização operacional, praticamente todos os departamentos dependem de relatórios em vários formatos.
No entanto, na prática, deparamo-nos frequentemente com estes problemas:
Assim, torna-se necessária um sistema de relatórios leve que permita gerir de forma unificada as definições de relatórios, suporte consultas parametrizadas, gere automaticamente resultados em múltiplos formatos e garanta o isolamento de permissões.
Recentemente, conheci um sistema de relatórios chamado SQLVantage (versão v1.0.2, lançada em 2026-07-15) que resolve exatamente estas dores. A sua filosofia de design é clara: um processo padrão que liga três tarefas — «consulta SQL, formulário de parâmetros, apresentação de resultados» — de modo a que todo o ciclo de vida do relatório seja rastreável.
Neste artigo, vou descrever o design principal e os padrões de utilização com base na documentação oficial, para ajudar a perceber rapidamente se a ferramenta se adequa à sua equipa.
O SQLVantage é um sistema de relatórios com arquitetura puramente web. As suas caraterísticas principais são:
| Conceito | Descrição |
|---|---|
| Relatório | Um relatório = consulta SQL + formulário de parâmetros (FORM) + apresentação de resultados (HTML) + três JSON de configuração, pertencente a uma «responsabilidade» |
| Responsabilidade | Diretório de classificação de relatórios, corresponde ao conceito de responsabilidade no Oracle EBS, usado para agrupar relatórios por módulo para o utilizador |
| Parâmetro | Condição de consulta (data, cliente, organização, etc.), submetida pelo utilizador e vinculada ao SQL como parâmetro nomeado |
| Pedido | Uma tarefa concreta de execução de relatório por parte do utilizador; o sistema executa de forma assíncrona e gera o ficheiro de resultado |
| Autorização | Ficheiro License que controla o limite máximo de relatórios e o prazo de utilização |
O sistema distingue duas funções, com pontos de entrada e permissões completamente separados:
A forma de implementação do SQLVantage pode ser considerada muito pragmática.
Descompacte o pacote de distribuição num diretório qualquer (por exemplo, D:\SQLVantage), faça duplo clique em SQLVantage.exe para iniciar. Por predefinição, escuta em 127.0.0.1:8080 — abra no navegador e está pronto.
Descompacte para /opt/sqlvantage, atribua permissões de execução e execute em segundo plano com nohup ou systemd. Porta predefinida igualmente 8080.
No primeiro arranque, o sistema executa automaticamente as seguintes ações, o que é muito conveniente para os administradores:
Este design reduz ao mínimo o custo de «experimentar do zero».
O administrador pode criar utilizadores comuns (função normal) e definir o estado como active ou inactive (em caso de saída da empresa, basta desativar, sem necessidade de eliminar a conta).
A gestão de responsabilidades corresponde ao conceito de responsabilidade no Oracle EBS e também pode ser criada manualmente. Cada relatório deve ser associado a uma responsabilidade — assim, na interface do utilizador comum, o menu de relatórios é apresentado agrupado por responsabilidade, com uma navegação clara.
O relatório tem três estados:
Um relatório publicado não pode ser eliminado diretamente — é necessário mudar primeiro o estado para rascunho ou arquivado. Esta abordagem evita eficazmente a eliminação acidental de relatórios em produção.
A página de lista suporta «duplo clique na célula para editar diretamente» o nome, a descrição e o estado — um pequeno detalhe que melhora a eficiência operacional.
O ficheiro de autorização conf/license.dat controla o número máximo de relatórios e o prazo de validade. Sem autorização ou com autorização expirada, o sistema permite criar no máximo 3 relatórios; acima desse limite, não é possível criar novos nem submeter pedidos.
Este mecanismo é prático para cenários de versão comercial ou avaliação interna — preserva toda a funcionalidade, mas define um limiar de limitação razoável.
Se houver uma funcionalidade no SQLVantage que mereça investimento de tempo para conhecer, é sem dúvida o designer de relatórios.
Este divide o processo de desenvolvimento do relatório em três módulos independentes mas interligados, concluídos num único interface.
Abra a lista de relatórios, clique no botão «Código» (roxo) na linha do relatório — abre-se um designer de grandes dimensões, ocupando cerca de 98% do ecrã. O interface divide-se em:
Esta disposição «código à esquerda + configuração à direita + pré-visualização em tempo real» é muito intuitiva para o programador.
Utiliza a sintaxe Oracle; as condições de consulta usam placeholders de parâmetros nomeados :nome_do_parâmetro:
SELECT company_name, ou_id, amount
FROM fnd_ou_tl
WHERE ou_id = :P_OU_ID
Aqui, P_OU_ID tem de coincidir com o nome do parâmetro definido no módulo FORM.
No painel direito é possível configurar cada coluna:
Esta configuração determina diretamente o profissionalismo da exportação para Excel — cabeçalhos, números alinhados à direita, separadores de milhares, formatos percentuais — tudo configurável aqui num só passo.
Por outras palavras, basta configurar os metadados das colunas e a qualidade da exportação Excel deixa de depender de código adicional no backend.
Este é o ponto de entrada para a interação com o relatório. Na «tabela de configuração de parâmetros» do painel direito, cada linha define um parâmetro de consulta:
| Campo | Descrição |
|---|---|
| Nome do parâmetro field | Tem de coincidir exatamente com :nome_do_parâmetro no SQL |
| Etiqueta label | Texto apresentado no formulário |
| Tipo de componente type | text / number / select / radio / date / month / datetime / hidden / temp |
| Opções estáticas static_options | Formato chave:valor,chave:valor |
| API dinâmica / SQL | Suporta placeholders {nome_da_variável} para encadeamento de parâmetros |
Esta é uma funcionalidade muito útil do módulo FORM: quando uma lista suspensa dependente está condicionada por um parâmetro a montante (por exemplo, só depois de «selecionar a organização» se carrega a «lista de departamentos»), é possível usar um placeholder como {P_OU_ID} no api_url ou query_sql.
Quando o utilizador altera o valor a montante, o sistema atualiza automaticamente as opções dependentes — sem necessidade de escrever código JavaScript adicional.
Na parte inferior do painel direito há também uma área de pré-visualização em tempo real: após configurar os parâmetros, vê-se imediatamente o resultado da renderização e o código HTML gerado pode ser «copiado e aplicado» no editor com um único clique.
Após a execução do relatório, de que forma os resultados são apresentados ao utilizador? É o módulo HTML que trata desta camada.
No painel direito, a «Configuração de componentes da vista HTML» permite definir vários blocos de apresentação, cada um com:
No final, quando o utilizador descarrega o resultado HTML, o sistema renderiza dinamicamente uma página completa com tabelas, gráficos e cartões KPI, e os parâmetros de consulta também são apresentados no topo do resultado.
Este nível de design confere à «camada de apresentação» do relatório capacidade de configuração — deixando de ser necessário escrever uma página de frontend individual para cada relatório.
Todo o fluxo segue uma única linha:
O caminho do utilizador comum é muito simples:
Queued (em fila) → Processing (em execução) → Success (concluído com sucesso) → Error (erro) → Terminated (terminado por tempo limite)
O sistema consulta a fila de tarefas a cada 3 segundos; o nível de paralelismo é configurável, com um máximo predefinido de 3 tarefas em execução simultânea. O tempo limite predefinido é de 30 minutos, ajustável na configuração.
SQL, FORM e HTML têm cada um «código» e «JSON de configuração» — o que deixa espaço para gestão de versões e reutilização de modelos no futuro.
Não se trata de «exportar primeiro e pós-processar depois» — o estilo do Excel é decidido na fase de conceção. Isto significa: o autor do relatório controla totalmente a qualidade do resultado, sem depender de scripts adicionais de pós-processamento.
O mecanismo de placeholders para implementar dependências entre parâmetros reduz a barreira de entrada para o desenvolvimento frontend.
O utilizador comum só vê os seus próprios pedidos; o administrador vê todos. Quando um utilizador ERP submete um pedido, o sistema valida também as permissões de organização OU/ORG, prevenindo acessos não autorizados.
Todos os dados de negócio são armazenados em conf/data.dat; os ficheiros de resultado são gerados no diretório data/. Para migrar, basta copiar os diretórios conf/ e data/ — tudo muito claro.
A impressão geral do SQLVantage é: pragmático, contido e fácil de usar.
Não procura ser «tudo para todos», mas concentra-se no cenário central dos «relatórios», ligando a gestão de SQL, a interação por parâmetros, a apresentação de resultados e o isolamento de permissões numa cadeia clara e completa.
Para equipas que lidam com dificuldades na gestão de relatórios, o SQLVantage oferece uma boa solução de referência — pode ser usado diretamente como ferramenta de produção ou como exemplo de estudo para compreender o design de um sistema de relatórios web leve.
Se também procura um sistema de relatórios simples de usar e com implementação autónoma, vale a pena começar por experimentar o SQLVantage.
Este artigo foi elaborado com base na documentação oficial do SQLVantage v1.0.2 (lançado em 2026-07-15). Para mais detalhes, consulte a documentação multilingue incluída no projeto (diretório docs/).