.tpl). Os templates são renderizados em diversos formatos de saída, mantendo a estrutura do documento que você define. O código-fonte está disponível publicamente no GitHub.
| Formato do template | Formato de saída |
|---|---|
.tpl estruturado como CSV | Arquivo CSV |
.tpl estruturado como XML | Arquivo XML |
.tpl estruturado como HTML | Arquivo HTML ou PDF |
.tpl estruturado como TXT | Arquivo TXT |
Por que usar o Reporter?
Em vez de escrever consultas SQL complexas, você referencia domínios, tabelas e campos por meio de placeholders intuitivos. Isso torna a criação de relatórios mais rápida, flexível e fácil de manter.
Como funciona
Fluxo de trabalho
O Reporter segue um fluxo de trabalho simples e eficiente que transforma seus templates em relatórios prontos para produção:- Envie templates com filtros e parâmetros opcionais
- O Reporter recupera os dados dos bancos de dados configurados (PostgreSQL, MongoDB)
- A lógica do template é aplicada (loops, condições, cálculos)
- A saída final é gerada no formato solicitado

Arquitetura
O Reporter é construído sobre uma arquitetura em camadas que mantém as responsabilidades bem definidas e permite crescimento:- Camada de dados: Conecta-se aos bancos de dados por meio de fontes de dados configuradas. Suporta PostgreSQL e MongoDB, com consultas multi-schema para PostgreSQL.
- Camada de lógica de negócio: Gerencia a análise de templates, resolução de placeholders e renderização.
- Camada de armazenamento: Armazena templates e relatórios gerados usando armazenamento de objetos compatível com S3 (AWS S3, MinIO ou SeaweedFS).
- Camada de apresentação: Retorna a saída formatada por meio de APIs RESTful.

O que ele pode fazer
- Consultas dinâmicas com placeholders: Referencie qualquer ponto de dados por caminhos diretos — sem necessidade de SQL.
- Suporte a multi-schema: Consulte tabelas em múltiplos schemas do PostgreSQL a partir de um único template usando sintaxe explícita de schema.
- Lógica de loops e condições: Construa conteúdo dinâmico com loops
for, condicionaisif/elif/elsee blocos com escopo definido. - Operações matemáticas e agregação: Realize cálculos com
sum_by,avg_by,count_by,min_by,max_by,calceaggregate_balance. - Rastreamento de contadores: Rastreie e exiba contadores nomeados ao longo das iterações do template com
counterecounter_show. - Filtros de transformação de dados: Transforme valores inline com
where,sum,count,replace,slice,strip_zerosepercent_of. - Processamento assíncrono: Relatórios pesados são processados de forma assíncrona via fila de mensagens.
- Armazenamento compatível com S3: Templates e relatórios são armazenados em qualquer serviço compatível com S3 (AWS S3, MinIO, SeaweedFS).
- Múltiplos formatos de saída: Gere saídas em CSV, XML, HTML, TXT ou PDF a partir de um único mecanismo de templates.
Modelo de template
O Reporter utiliza templates que espelham a estrutura final do documento. Os arquivos devem ter a extensão
.tpl independentemente do formato do conteúdo interno.
Embora o conteúdo do arquivo deva seguir o formato de saída, certifique-se de salvá-lo com a extensão
.tpl. Isso é necessário para que o template funcione corretamente.Configurando seu ambiente
As referências de banco de dados devem ser renomeadas no arquivo
.env do projeto para evitar conflitos quando tabelas compartilham nomes entre bancos de dados. Exemplo de nomenclatura:
midaz_onboarding(PostgreSQL)midaz_onboarding_metadata(MongoDB)
Usando placeholders
A estrutura dos placeholders segue uma sintaxe baseada em caminhos:
Placeholders com multi-schema
Quando sua fonte de dados PostgreSQL possui múltiplos schemas, use a sintaxe explícita de schema para evitar ambiguidade:Se o nome de uma tabela existe em apenas um schema, a sintaxe legada
{{ base.table.field }} ainda funciona — o Reporter descobre automaticamente o schema correto. Se uma tabela existe em múltiplos schemas, o Reporter usa por padrão o schema public. Se a tabela não está em public, o Reporter retorna um erro com sugestões:Construindo templates
Blocos comuns
- Loop
- Loop com schema explícito
- Condição simples
- Escopo temporário
- Formatação de valores
Blocos condicionais
| Bloco | Descrição | Exemplo |
|---|---|---|
| If | Executa o bloco se a condição for verdadeira | {% if condition %}...{% endif %} |
| If-else | Executa um bloco se verdadeiro, outro se falso | {% if condition %}...{% else %}...{% endif %} |
| If-else-if | Permite múltiplas verificações | {% if a %}...{% elif b %}...{% else %}...{% endif %} |
| Igual | Verifica se dois valores são iguais | {% if a == b %} |
| Diferente | Verifica se dois valores são diferentes | {% if a != b %} |
| Maior que | Verifica se a é maior que b | {% if a > b %} |
| Menor que | Verifica se a é menor que b | {% if a < b %} |
| Maior ou igual | Verifica se a é maior ou igual a b | {% if a >= b %} |
| Menor ou igual | Verifica se a é menor ou igual a b | {% if a <= b %} |
| And | Retorna verdadeiro se ambas as condições forem verdadeiras | {% if a and b %} |
| Or | Retorna verdadeiro se pelo menos uma for verdadeira | {% if a or b %} |
| Not | Inverte o resultado booleano | {% if not a %} |
Referência de tags
Tags de agregação
sum_by — Soma valores numéricos de um campo em todos os itens de uma coleção.Todas as tags de agregação utilizam precisão decimal para evitar erros de arredondamento de ponto flutuante. Campos ausentes ou não numéricos são ignorados. Retorna
0 se nenhum item corresponder.Tag de data e hora
date_time — Gera a data e hora atuais formatadas de acordo com a string de formato fornecida. O horário é gerado em UTC.| Código | Significado | Exemplo |
|---|---|---|
YYYY | Ano com 4 dígitos | 2025 |
MM | Mês com 2 dígitos | 01-12 |
dd | Dia com 2 dígitos | 01-31 |
HH | Hora com 2 dígitos (24h) | 00-23 |
mm | Minuto com 2 dígitos | 00-59 |
ss | Segundo com 2 dígitos | 00-59 |
Tag aritmética
calc — Avalia expressões matemáticas com suporte a variáveis do contexto do template.| Operador | Descrição | Precedência |
|---|---|---|
** | Exponenciação | Mais alta (direita para esquerda) |
* / | Multiplicação, divisão | Média |
+ - | Adição, subtração | Mais baixa |
( ) | Parênteses | Sobrescreve a precedência |
Variáveis que não podem ser resolvidas assumem o valor padrão
0. Divisão por zero produz um erro.Tag de agregação financeira
aggregate_balance — Agrupa itens por um campo, seleciona a entrada mais recente por conta dentro de cada grupo e soma os saldos. Útil para relatórios regulatórios que exigem o saldo mais recente por conta agrupado por categoria.| Campo | Tipo | Descrição |
|---|---|---|
group_value | string | O valor do campo group_by |
balance | decimal | Soma dos saldos mais recentes por conta no grupo |
count | inteiro | Número de contas no grupo |
Tamanho máximo da coleção: 100.000 itens. Os resultados são ordenados por
group_value.Tags de contador
counter — Incrementa um contador nomeado em 1. Não produz saída. Os contadores têm escopo por renderização.Referência de filtros
percent_of
Calcula a porcentagem de um valor em relação a um total. Retorna uma string formatada com 2 casas decimais.category.amount = "6.00" e total.expenses = "20.00":
strip_zeros
Remove zeros à direita de um valor numérico sem arredondamento.slice
Extrai uma substring usando índices de início e fim (base 0).replace
Substitui todas as ocorrências de uma string de busca por uma string de substituição. Formato:"busca:substituição".
where
Filtra um array de objetos por igualdade de campo. Suporta campos aninhados via notação de ponto.sum (filtro)
Soma valores numéricos de um campo em todos os itens de um array. Utiliza precisão decimal.count (filtro)
Conta elementos em um array onde um campo corresponde a um valor. Suporta campos aninhados.contains
Verifica se um valor está parcialmente contido em outro. Útil quando os dados incluem prefixos ou sufixos dinâmicos.- Origem:
0#@external/BRL - Destino:
@external/BRL
true porque @external/BRL existe dentro do valor de origem.
Resumo de operadores e filtros
| Nome | Tipo | Descrição |
|---|---|---|
sum_by | Tag | Soma valores por campo com filtro opcional |
count_by | Tag | Conta itens com filtro opcional |
avg_by | Tag | Calcula a média por campo |
min_by | Tag | Encontra o valor mínimo |
max_by | Tag | Encontra o valor máximo |
date_time | Tag | Formata a data/hora atual |
calc | Tag | Avalia expressões aritméticas |
aggregate_balance | Tag | Agregação de saldos financeiros agrupados |
counter | Tag | Incrementa um contador nomeado |
counter_show | Tag | Exibe valor(es) do contador |
percent_of | Filtro | Calcula porcentagem |
strip_zeros | Filtro | Remove zeros à direita |
slice | Filtro | Extrai substring |
replace | Filtro | Substituição de string |
where | Filtro | Filtra array por valor de campo |
sum | Filtro | Soma valores de campo do array |
count | Filtro | Conta itens correspondentes |
contains | Função | Correspondência parcial de string |
floatformat | Filtro | Formata casas decimais |
Filtragem avançada
Ao gerar um relatório, você pode passar filtros no corpo da requisição para restringir os dados. Os filtros seguem uma estrutura de datasource > tabela > campo: Schema único (padrão):
| Operador | Descrição | Exemplo |
|---|---|---|
eq | Igual a | { "eq": ["active", "pending"] } |
gt | Maior que | { "gt": [100] } |
gte | Maior ou igual a | { "gte": ["2025-06-01"] } |
lt | Menor que | { "lt": [1000] } |
lte | Menor ou igual a | { "lte": ["2025-06-30"] } |
between | Valor dentro de um intervalo | { "between": [100, 1000] } |
in | Valor está em uma lista | { "in": ["active", "pending"] } |
nin | Valor não está em uma lista | { "nin": ["deleted", "archived"] } |
Precisa de inspiração?
Confira a página de Exemplos de templates para explorar o que você pode fazer e começar a criar seu próprio template.
Autenticação e autorização
O Reporter não exige autenticação por padrão, mas é desenvolvido com integração nativa ao Access Manager. Quando habilitado, o Access Manager fornece controle de acesso baseado em papéis (RBAC) para templates, relatórios e fontes de dados — oferecendo controle granular sobre quem pode visualizar, criar ou gerenciar recursos de relatórios.

