refactor: consolidate audit indexes into comprehensive migration with query documentation

Co-Authored-By: Claude <[email protected]>

Author: marc0der

README.md

@@ -52,4 +52,118 @@ http POST localhost:8080/versions \
 ### GET versions for a candidate:
 ```bash
 http GET localhost:8080/versions/java
-```
+```
+
+## Audit Table Query Scenarios
+
+The audit table tracks download and usage events for SDKMAN candidates. The following indexes optimize common analytical queries:
+
+### Download Count for a Candidate (Last 30 Days)
+```sql
+SELECT COUNT(*) as downloads
+FROM audit
+WHERE candidate = 'java'
+  AND timestamp > NOW() - INTERVAL '30 days';
+```
+*Uses index:* `idx_audit_candidate_timestamp`
+
+### Top 10 Most Downloaded Versions (by Candidate)
+```sql
+SELECT version, COUNT(*) as downloads
+FROM audit
+WHERE candidate = 'gradle'
+GROUP BY version
+ORDER BY downloads DESC
+LIMIT 10;
+```
+*Uses index:* `idx_audit_candidate_version_timestamp`
+
+### Download Trends by Version Over Time
+```sql
+SELECT version,
+       DATE_TRUNC('week', timestamp) as week,
+       COUNT(*) as downloads
+FROM audit
+WHERE candidate = 'kotlin'
+  AND timestamp > NOW() - INTERVAL '6 months'
+GROUP BY version, week
+ORDER BY week DESC, downloads DESC;
+```
+*Uses index:* `idx_audit_candidate_version_timestamp`
+
+### Command-Specific Analytics (Install vs Use)
+```sql
+SELECT command, COUNT(*) as count
+FROM audit
+WHERE candidate = 'java'
+  AND timestamp > NOW() - INTERVAL '90 days'
+GROUP BY command
+ORDER BY count DESC;
+```
+*Uses index:* `idx_audit_candidate_command_timestamp`
+
+### Recent Activity Across All Candidates
+```sql
+SELECT candidate,
+       COUNT(*) as events,
+       MAX(timestamp) as last_activity
+FROM audit
+WHERE timestamp > NOW() - INTERVAL '7 days'
+GROUP BY candidate
+ORDER BY events DESC;
+```
+*Uses index:* `idx_audit_timestamp_candidate`
+
+### Platform Distribution for a Candidate
+```sql
+SELECT platform,
+       COUNT(*) as downloads,
+       ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) as percentage
+FROM audit
+WHERE candidate = 'kotlin'
+  AND timestamp > NOW() - INTERVAL '90 days'
+GROUP BY platform
+ORDER BY downloads DESC;
+```
+*Uses index:* `idx_audit_candidate_platform_timestamp`
+
+### Vendor Popularity Comparison by Platform (Java Distributions)
+```sql
+SELECT vendor,
+       platform,
+       COUNT(*) as downloads,
+       COUNT(DISTINCT DATE_TRUNC('day', timestamp)) as days_active
+FROM audit
+WHERE candidate = 'java'
+  AND platform = 'LINUX_X64'
+  AND vendor IS NOT NULL
+  AND timestamp > NOW() - INTERVAL '6 months'
+GROUP BY vendor, platform
+ORDER BY downloads DESC;
+```
+*Uses index:* `idx_audit_candidate_platform_vendor_timestamp`
+
+### Most Active Users by Host (Top 20)
+```sql
+SELECT host,
+       COUNT(*) as activity_count,
+       COUNT(DISTINCT candidate) as unique_candidates,
+       MAX(timestamp) as last_seen
+FROM audit
+WHERE timestamp > NOW() - INTERVAL '30 days'
+  AND host IS NOT NULL
+GROUP BY host
+ORDER BY activity_count DESC
+LIMIT 20;
+```
+
+### Peak Usage Times (Hourly Distribution)
+```sql
+SELECT EXTRACT(HOUR FROM timestamp) as hour,
+       COUNT(*) as events
+FROM audit
+WHERE timestamp > NOW() - INTERVAL '7 days'
+GROUP BY hour
+ORDER BY hour;
+```
+*Uses index:* `idx_audit_timestamp_candidate`

src/main/resources/db/migration/V6__add_audit_index_candidate_timestamp.sql

@@ -0,0 +1,32 @@
+-- flyway:no-transaction
+
+-- Index for queries filtering by candidate with time-based ordering
+-- Use cases: download counts per candidate, recent activity for a candidate, time-series analysis
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_candidate_timestamp
+    ON audit (candidate, timestamp DESC);
+
+-- Index for queries filtering by candidate and version with time-based ordering
+-- Use cases: version-specific download counts, version adoption trends, most downloaded versions per candidate
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_candidate_version_timestamp
+    ON audit (candidate, version, timestamp DESC);
+
+-- Index for queries filtering by candidate and command type with time-based ordering
+-- Use cases: command-specific analytics (install vs use), event type filtering, command-specific trends
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_candidate_command_timestamp
+    ON audit (candidate, command, timestamp DESC);
+
+-- Index for queries filtering by time range with candidate grouping
+-- Use cases: recent activity across all candidates, time-based filtering with candidate aggregation, last 30 days analytics
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_timestamp_candidate
+    ON audit (timestamp DESC, candidate);
+
+-- Index for queries filtering by candidate and platform with time-based ordering
+-- Use cases: platform-specific download statistics, platform adoption trends, architecture/OS analysis
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_candidate_platform_timestamp
+    ON audit (candidate, platform, timestamp DESC);
+
+-- Partial index for queries filtering by vendor and platform (excludes NULL vendors for efficiency)
+-- Use cases: platform and vendor popularity analysis, Java distribution comparisons (Zulu vs Temurin) per platform, vendor-specific trends
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_candidate_platform_vendor_timestamp
+    ON audit (candidate, platform, vendor, timestamp DESC)
+    WHERE vendor IS NOT NULL;