## Background GLQL passes usernames (strings) when filtering by user, but the analytics Aggregation Engines (AE) expect user IDs (integers/GIDs). To bridge this gap, the AE is adding a `user_username` filter alongside the existing `user_id`/`author_id` filters: - `user_id` / `author_id`: accepts integer IDs / GIDs (existing behaviour) - `user_username`: accepts string usernames, performs a PG lookup to convert to IDs See the tracking issue in the GitLab project: gitlab-org/gitlab#599750 **Scope update:** this issue was originally scoped to the CodeSuggestions AE only. The underlying backend work in gitlab-org/gitlab#611201 turned out to cover **every** aggregation engine, not just CodeSuggestions. This issue is now scoped to match: GLQL needs username/ID auto-detection for the `user` (or equivalent) filter on **every analytics data source that exposes one**, not just CodeSuggestions. ## Problem GLQL's analytics-mode sources currently accept only numeric user IDs wherever a user-identifying filter exists. When usernames are added on the AE side, GLQL will need to decide whether to emit the `*_id` or `*_username` variant of the filter based on the type of value the user provides in their query — a numeric ID vs. a string username. ### Affected data sources | GLQL source | Filter field (GLQL) | AE argument today | Status | | --- | --- | --- | --- | | `CodeSuggestions` | `user` | `userId` | Filter exists in GLQL, numeric-ID only. Needs username dispatch. | | `Contributions` | `user` | `authorId` | Filter exists in GLQL, numeric-ID only. Needs username dispatch. | | `AiUsageEvents` | `user` | `userId` | Filter exists in GLQL, numeric-ID only. Needs username dispatch. | | `MergeRequests` (analytics mode) | not yet exposed in GLQL | `authorId` (added in gitlab-org/gitlab!251586) | GLQL needs to add the filter/dimension first, then username dispatch. | | `Pipelines` (analytics mode) | not yet exposed in GLQL | `userId` (added in gitlab-org/gitlab!251587) | GLQL needs to add the filter/dimension first, then username dispatch. | | `AgentPlatformSessions` | not a GLQL source yet | already supports `userId`/`user_username` pilot | Out of scope until GLQL exposes this source. | | `Deployments` | not a GLQL source yet | `userId` (added in gitlab-org/gitlab!251585) | Out of scope until GLQL exposes this source. | The last two rows aren't GLQL sources today, so they're tracked here for awareness only — no GLQL work is needed for them until (if) those sources are added. ## Proposed Solution Update the `user`-identifying filter in each applicable GLQL analytics source analyzer to inspect the value type at compile time and route to the correct AE filter: - If the value is a **number** (or GID string like `"gid://gitlab/User/123"`): emit the `*_id` variant (`userId`, `authorId`, etc., depending on the source) - If the value is a **string username** (e.g. `"pshutsin"`): emit the `*_username` variant This keeps the GLQL query syntax simple and user-friendly — consumers write `user = "pshutsin"` or `user = 123` and GLQL handles the dispatch transparently, regardless of which analytics source they're querying. ### Example query syntax ```yaml mode: analytics query: type = CodeSuggestion and user = "pshutsin" dimensions: language, timestamp metrics: totalCount, acceptanceRate ``` ```yaml mode: analytics query: type = CodeSuggestion and user = 42 dimensions: language, timestamp metrics: totalCount, acceptanceRate ``` ```yaml mode: analytics query: type = Contribution and user = "pshutsin" dimensions: created metrics: totalCount ``` Each should produce valid GraphQL with the appropriate filter key for its source (e.g. `userUsername`/`userId` for CodeSuggestions, `authorUsername`/`authorId` for Contributions). ## Implementation Notes - The type detection should happen in the **analyzer** or **codegen** layer, not the parser, so the AST stays uniform. - This is a single, reusable dispatch pattern (single filter, dual output based on value type) applied per-source, since each source's AE argument name differs (`userId` vs. `authorId`, etc.). - Sources without a `user`-identifying filter today (`MergeRequests`, `Pipelines` in analytics mode) need that filter/dimension added to GLQL first — see gitlab-org/gitlab#611201 for the AE-side work, which has already merged for these engines. - The `user_username` AE filter is being piloted in the CodeSuggestions AE first; once stable, other AEs will follow (per gitlab-org/gitlab#599750). ## Dependencies - Blocked by the `user_username` filter being available on each relevant AE: gitlab-org/gitlab#599750 - Related backend work extending user filter/dimension coverage to all AEs: gitlab-org/gitlab#611201 ### Note Contributions GLQL integration is actively being developed as https://gitlab.com/groups/gitlab-org/-/work_items/21213 and also has the same requirements for User filtering. Depending on progress, we would need to add support for username there too.