Enable AiUsageEvent analytics queries using GLQL with `mode: analytics` syntax, building on the existing AiUsageEvent aggregation engine. The backend aggregation engine needs to be implemented first. This epic tracks the **full implementation** of AiUsageEvent analytics in GLQL. **Parent Epic:** &21207 Data Aggregation in GLQL ## Example Query ```yaml mode: analytics query: type = AiUsageEvent and created >= -30d dimensions: - feature as "Duo Feature" - userRole as "User Role" metrics: - count as "Total Events" - uniqueUsers as "Unique Users" - averageSentiment as "Avg Sentiment" sort: count desc limit: 20 ``` This query returns GitLab Duo usage analytics grouped by feature and user role, showing adoption metrics and sentiment analysis for the last 30 days. ## Goals 1. Implement backend aggregation engine for AiUsageEvent 2. Add GLQL parser support for `type = AiUsageEvent` + `mode: analytics` 3. Enable querying GitLab Duo metrics (feature usage, adoption, sentiment, RCA, Code Review) 4. Make AiUsageEvent analytics accessible to Data Analyst agent 5. Document query patterns and examples ## Scope **✅ In Scope:** - Implement `Analytics::AggregationEngines::AiUsageEvent` engine - Create `aiUsageEventsAnalytics` GraphQL field on existing `AiUsage` type - GLQL parser support for `type = AiUsageEvent` + `mode: analytics` - GLQL UI integration for AiUsageEvent queries - Documentation: GLQL syntax examples, query patterns - Data Analyst agent integration (prompts, example questions) - Feature flag: `glql_ai_usage_event_analytics_aggregation` **❌ Out of Scope (Future Work):** - Additional AI metrics beyond core use cases - Migration of existing Duo analytics dashboards - Performance optimization for large-scale deployments **✅ Prerequisites:** - Backend engine (#589610) must be completed first - GraphQL field must be mounted ## Related Work - Backend Engine: https://gitlab.com/gitlab-org/gitlab/-/work_items/589610 - Research: https://gitlab.com/gitlab-org/gitlab/-/work_items/588589 - Parent Epic: https://gitlab.com/groups/gitlab-org/-/work_items/21207 - Aggregation Framework Docs: https://docs.gitlab.com/development/database/aggregation_framework/ - Reference Pattern: https://gitlab.com/groups/gitlab-org/-/work_items/21212 ## Success Criteria - [ ] GLQL queries with `mode: analytics` successfully return AiUsageEvents aggregation data - [ ] Data Analyst agent can answer questions like "Show me Duo feature usage by role" - [ ] Documentation published with working examples - [ ] Pattern consistent with Pipeline and CodeSuggestion implementations ## Implementation Flow ```mermaid graph TB subgraph "Per data type process" subgraph "Backend (Optimize)" ENGINE[1. Backend Engine<br/>Implement aggregation<br/>Weight: 3] GRAPHQL[2. GraphQL Field<br/>Mount engine<br/>Weight: 2] end subgraph "GLQL Integration (Platform Insights)" PARSER[3. Parser Support<br/>Add analytics mode<br/>Weight: 3] subgraph "Parallel Work" UI[4. UI Integration<br/>Render results<br/>Weight: 3] DOCS[5. Documentation<br/>Examples & guides<br/>Weight: 2] AGENT[6. Agent Integration<br/>Prompts & patterns<br/>Weight: 2] end end ENGINE --> GRAPHQL GRAPHQL -.Schema Handoff.-> PARSER PARSER --> UI PARSER --> DOCS PARSER --> AGENT end ``` **Implementation flow for this data type:** Sequential backend work by Optimize team, then parallel GLQL integration by Platform Insights team. The dotted "Schema Handoff" line shows where early schema sharing can unblock Platform Insights to start parser work before GraphQL is fully complete.