ADORSYS-GIS / ADORSYS-GIS/lightbridge-authz
[Story]: Continuous aggregates per KPI measure, refresh proven, aggregates never span grains
- Linguagem predominante
- Rust
- Estrelas
- 0
- Forks
- 1
- Merge médio
- 7h 7min
- PRs com merge (30d)
- 237
Descrição
Parent epic: #581
### Story Statement
As a platform operator, every dashboard KPI reads a named continuous aggregate with a running refresh policy — never a raw-table scan — and each measure has exactly one authoritative source.
### Real Intent
Deliver #491's "10 named continuous aggregates" goal on the new grain tables, under governance#166's rules: one aggregate per measure, exactly one authoritative source per measure, no aggregate spans grains.
### Background and Context
There are zero continuous aggregates today (and there could not be — production had no TimescaleDB, #489/#549). Once the grain tables are real hypertables, the KPI read path must be proven to use aggregates, not assumed: the house failure mode is silent success.
### Source of truth (links)
ADR-0027 Decision 5 · #491 · governance#166 · #489
### Acceptance Criteria
1. A named continuous aggregate per KPI measure (spend, tokens, requests, latency percentiles where supported, active users, acceptance placeholders as sources land), each built on exactly one grain table — no aggregate joins or unions across grains.
2. Refresh policies exist in `timescaledb_information.jobs` and have demonstrably run in the target cluster.
3. For each KPI query, an `EXPLAIN` (captured in the PR) proves the aggregate is read.
4. Aggregates preserve the money discipline: unknown-cost rows counted separately, never coerced to 0 in the rollup.
5. If a percentile aggregate needs `timescaledb_toolkit`, the image decision records it (the `-ha` image question from governance#163); an approximation, if used, is named in the API docs.
### Out of Scope
New KPI definitions (take #491's list); dashboard wiring.
### Dependencies and Blockers
Grain tables + Timescale image landed; per-grain query endpoints (aggregates back them).
### Assumptions
The 90d retention window (#489) is compatible with every aggregate's refresh lag — verify, don't assume, for month-boundary billing queries.
### Implementation Notes
`migrations-usage/`, fail-loud; aggregate names are part of the API surface — document them beside the endpoints they back.
### Test Expectations
A test (or CI check) per aggregate asserting existence + refresh-policy presence; an EXPLAIN-based assertion that the query path hits the aggregate.
### Verification evidence
To be attached on the implementing PR: `timescaledb_information.jobs` output, EXPLAIN captures.
### Human accountable owner
Stephane Segning Lambou
### AI Usage
AI-assisted (Claude): research and drafting. Reviewed and owned by Stephane Segning Lambou.
Guia de contribuição
Direção de pesquisa
Start in migrations-usage/ by verifying the grain tables and Timescale image dependency. Trace each per-grain query endpoint to its aggregate, then use the per-aggregate existence and refresh-policy checks plus captured EXPLAIN output as the completion criteria; also verify the 90d retention window for month-boundary billing queries and document aggregate names beside the endpoints they back.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- postgresql
- Domínio
- databases
- Tipo de issue
- Funcionalidade
- Dificuldade
- 4/5
- Tempo estimado
- 3-5 dias
- Status de atividade
- Ativa
- Clareza
- Razoavelmente clara
- Facilidade para iniciantes
- 45/100