Filtro de datas (inicio / fim)

inicio e fim filtram a coluna created_at, sempre em horário de Brasília (UTC−3). Existem três modos, dependendo de quais você envia:

Você envia	Modo	Resultado
Nenhum	sem filtro	Varre a tabela inteira (custo alto — evite).
Só inicio ou só fim	data fixa	Aquele dia inteiro (00:00 → 23:59).
inicio e fim	intervalo	[inicio, fim], no máximo 30 dias.

:::caution Um único valor = um dia inteiro (não "a partir de") Mandar só inicio=2026-05-14 não significa "do dia 14 em diante" — significa só o dia 14 inteiro. Para um período, envie inicio e fim. :::

Formatos aceitos

Formato	Significado
YYYY-MM-DD	Dia (sem hora).
YYYY-MM-DD HH:MM:SS	Instante exato.

No modo data fixa, a hora é ignorada (sempre o dia inteiro). No modo intervalo, a hora é respeitada nos extremos quando informada. Formato inválido → 400 {"error":"data/hora invalida", ...}.

Regras do intervalo

• inicio define o limite inferior (created_at >=).
• fim como data pura → inclui o dia de fim inteiro (created_at < início do dia seguinte). fim como instante → inclusivo (created_at <=).
• fim anterior a inicio → 400 {"error":"intervalo invalido","motivo":"fim anterior a inicio"}.
• Span maior que 30 dias (MAX_RANGE_DAYS) → 400 {"error":"intervalo muito grande","max_dias":30,"informado_dias":N}.

Por que existe um "+3 horas"

created_at é gravado em UTC. O dia local de Brasília (UTC−3 fixo) começa às 03:00 UTC. Por isso o handler soma 3h ao limite local antes de comparar:

created_at >= TIMESTAMP 'inicio' + INTERVAL '3' HOUR
created_at <  TIMESTAMP 'dia_seguinte_de_fim' + INTERVAL '3' HOUR

Você informa horário de Brasília; a conversão para UTC é interna.

Poda de partição (dt)

Quando há filtro de data, o handler também filtra a coluna de partição dt com margem de 1 dia em cada ponta:

dt >= 'inicio - 1 dia'  AND  dt <= 'fim + 1 dia'

Isso reduz drasticamente o data scanned (~100×) e, portanto, o custo. É o principal motivo para sempre informar inicio/fim.

:::note Particionamento em andamento As tabelas ainda estão sendo migradas para particionamento diário (via AWS DMS). Até concluir, a poda por dt pode não ter efeito — mas informar inicio/fim continua sendo a prática correta. :::

Exemplos

# Data fixa: o dia 14 inteiro
GET /?query=audits&inicio=2026-05-14

# Intervalo de até 30 dias
GET /?query=audits&inicio=2026-05-01&fim=2026-05-30

# Intervalo com hora nos extremos
GET /?query=access_logs&inicio=2026-05-14 08:00:00&fim=2026-05-14 18:30:00