TASK-188 - Audit ranking and stats query performance

Goal

Measure and document the real performance of the public Ranking and Stats endpoints before applying any optimization.

Context

/api/ranking weekly/monthly currently reads runtime aggregates over materialized RCON/AdminLog tables, while annual ranking already uses snapshots. Stats search and player detail also depend on runtime reads over the same materialized domain. HLL Vietnam needs a concrete baseline for latency, query shape, table size and execution plan so follow-up work can target the real bottlenecks instead of guessing.

Preserve the current product identity: Spanish-speaking HLL Vietnam community, military/Vietnam/tactical/sober visual direction and controlled repository evolution.

Steps

Read the listed files first.
Identify the exact queries and tables used by the target endpoints.
Measure request time and, if possible, approximate SQL time for each target endpoint.
Inspect relevant row counts, current indexes and execution plans when the engine allows it.
Document the slowest endpoint and provide a concrete index/snapshot recommendation without changing runtime code.

Files to Read First

AGENTS.md
ai/repo-context.md
ai/architecture-index.md
backend/app/routes.py
backend/app/rcon_historical_leaderboards.py
backend/app/rcon_historical_player_stats.py
backend/app/rcon_annual_rankings.py
docs/global-ranking-page-plan.md
scripts/run-stats-validation.ps1

Expected Files to Modify

docs/ranking-stats-performance-audit.md
ai/tasks/done/TASK-188-audit-ranking-and-stats-query-performance.md

Constraints

No modificar lógica de backend.
No modificar frontend.
No crear migraciones.
No crear índices todavía.
No cambiar APIs.
No reactivar Elo/MMR.
No reintroducir Comunidad Hispana #03.
Mantener el trabajo limitado a medición y documentación.

Validation

Before completing the task ensure:

the audit covers:
- /api/ranking weekly kills
- /api/ranking weekly kd_ratio
- /api/ranking monthly kills_per_match
- /api/ranking annual kills
- /api/stats/players/search
- /api/stats/players/{player_id}
the document records:
- total request time
- approximate SQL time if measurable
- row counts for relevant tables
- existing indexes
- current query shapes
- execution plan if available
- slowest endpoint
- concrete recommendation for indexes and/or snapshots
executed commands are documented
inability to obtain EXPLAIN is documented if the environment blocks it
git diff --name-only stays within scope

Outcome

Audit completed in docs/ranking-stats-performance-audit.md.
Measured baseline captured for the six required endpoint probes.
Environment limitation documented: backend HTTP server was not running locally, so request timing used in-process route resolution and SQL tracing over SQLite.
Current runtime weekly/monthly ranking windows on 2026-06-09 are empty because the latest materialized admin-log-match-ended data ends on 2026-05-20T23:21:45.816Z.
Slowest measured endpoint is /api/stats/players/{player_id} because it issues 16 SQL statements, including repeated window counts and two ranking-position subqueries.
Primary future performance risks identified:
- full scans on rcon_materialized_matches for source_basis + time-window filters
- a full scan on rcon_match_player_stats for player-detail-by-player_id
- temp B-trees for grouping, COUNT(DISTINCT) and ordering in leaderboard/search queries
Follow-up recommendation for TASK-189:
- add time-window indexes on rcon_materialized_matches
- add a direct player_id index on rcon_match_player_stats
- keep annual snapshot indexes as-is
Follow-up recommendation for TASK-190:
- move weekly/monthly public ranking to snapshot-backed reads with controlled runtime fallback

Change Budget

Prefer fewer than 5 modified files.
Prefer changes under 200 lines when feasible.
Split the work into follow-up tasks if limits are exceeded.

4.3 KiB Raw Blame History