## The Why <details><summary>Expand to read The Why</summary> The DAP (Duo Agent Platform) Impact Dashboard v1 has a "Group comparison" panel showing, per root group, how many users ran Duo Agent Platform flows and how many credits they used ([discussion](https://gitlab.com/groups/gitlab-org/-/work_items/23420#note_3834970807)). Today, getting per-group numbers takes one request per group, capped at 20 groups. A group dimension turns this into a single request covering any number of groups. The panel always shows root (top-level) groups, confirmed by @pshutsin in the thread above, so the panel itself writes plain `dimensions: group` and relies on the engine default `depth: 1`. The engine side of this dimension shipped in gitlab-org/gitlab#617805 (gitlab-org/gitlab!255369, merged 2026-09-18). The shared groundwork it depends on (gitlab-org/gitlab!254110 and gitlab-org/gitlab!255052) is also merged. Tracked under #188 ("Track GLQL work for v1 DAP Impact Dashboard"), alongside sibling issues #207, #209, #211, #213, #214, #215. This unblocks the "Duo adoption by group" bar chart, a per-group adoption breakdown, and the full group comparison table. This issue used to also cover the AiUsageEvents source; that part is now split out and tracked in #227. </details> ## Proposal GLQL authors will be able to group DuoWorkflows analytics results by group, filter results to one or more groups (a group's numbers include everything under it: subgroups and projects), and sort results by any metric per group. This replaces the current one-request-per-group workaround with a single query covering any number of groups. --- ## Technical Proposal Add `group` as a dimension, sort field, and filter field on the DuoWorkflows analytics source in the GLQL compiler, following the existing pattern used for association dimensions like `project` and `user`. Target GLQL: ``` source: duoWorkflows dimensions: group metrics: usersCount, creditsUsedSum sort: usersCount desc ``` Filtering: `group = <group global id>` or the numeric form `group = <id>`. A quoted *path* stays query scope, so `group = "gitlab-org"` scopes the query rather than filtering it. The filter compiles to the engine's `groupId` argument and matches a group plus all its subgroups and projects. ## Acceptance criteria - [x] A GLQL query with `source: duoWorkflows` and `dimensions: group` returns one row per root group, each with its user count and credits used. - [x] A GLQL query can filter DuoWorkflows results to one or more groups by Group Global ID, and results include usage from that group's subgroups and projects. - [x] A GLQL query can sort DuoWorkflows results by any requested metric, per group. - [x] The DAP Impact Dashboard's Group comparison panel can be built from a single GLQL query instead of one request per group. - [x] Docs and the Data Analyst agent schema describe the new `group` dimension and filter for DuoWorkflows. Implemented in !530. On the last criterion: `src/schema/schema.json` (the document the Data Analyst agent reads) publishes `group` as dimension, sort field and filter for the source. No file in this repo or in `gitlab-org/gitlab` enumerates dimensions per source, so there is no separate docs page to update — reopen this point if that was meant differently. ## Out of scope - `group` dimension/filter for the AiUsageEvents source — tracked in #227. - Chart pagination for large group hierarchies (#170). ### References - Adoption tab GLQL scan and the depth answer: https://gitlab.com/groups/gitlab-org/-/work_items/23420#note_3834970807 - Tracking: #188. Sibling DAP Impact issues: #207, #209, #211, #213, #214, #215 - https://gitlab.com/gitlab-org/glql/-/work_items/212 (DuoWorkflows twin by rcrespo3) was closed as a duplicate in favour of this issue on 2026-09-16 ## DuoWorkflows detail (added 2026-09-16, updated 2026-09-18) The Group comparison panel always renders root groups, so it uses the engine default `depth: 1` and writes plain `dimensions: group`. The dimension also exposes `depth` (@pshutsin, 2026-09-17) so other queries can bucket at a specific level: `depth` is counted from the top-level group (`1` = top-level groups, `2` = their subgroups, ...), bounds 1..99, default 1. Planned query for the panel: ```graphql duoWorkflows(createdAtFrom: "...", createdAtTo: "...") { aggregated(orderBy: [{ identifier: "usersCount", direction: DESC }]) { nodes { dimensions { group(depth: 1) { fullPath } } usersCount creditsUsed { sum } } } } ``` ### What (DuoWorkflows) - `group` dimension and sort field on the DuoWorkflows analytics source, with a `depth` integer parameter defaulting to 1, rendered with the existing `render_group` selection (`group(depth: N) { fullPath webUrl fullName }`) - `group` filter compiling to the engine's `groupId: [String!]` argument - Group GIDs or numeric ids (not paths, which are scope), matching the group and all of its descendants (subgroups and projects); the framework filter is `descendants` from https://gitlab.com/gitlab-org/gitlab/-/merge_requests/255052 - Target GLQL: `dimensions: group` (panel) or `dimensions: group(depth=2)`, `metrics: usersCount, creditsUsedSum`, `sort: usersCount desc` ### Compiler work this needs (shared with #227) - **Integer parameter kind.** `ParameterConstraint` was `Enum` (string), `Range` (float) or `List`. A user-typed `depth=2` is emitted verbatim, but the compiler-side default applied when `depth` is omitted went through `Display` and would render as `depth: 1.0`, which the `Int` argument rejects. Landed in !530 as `ParameterConstraint::Int { min, max }` with a `ParameterDefault::Int`, mirroring the `ListItem::Int` added by #213 and reusing its `parse_graphql_int` grammar. Published in `schema.json` as `kind: "Number"` with integer bounds, matching how list items publish - **Rendering hook for parameterised object dimensions.** `render_group` exists (`src/analyzer/sources/shared.rs`) but the parameterised rendering path only emitted scalar leaves (`name(params)`); it needed to emit `name(params) { sub-selection }` for association dimensions. Landed in !530 as the `field_selection_set` hook on `SourceAnalyzer` - **Sort carries the parameter.** The engine keys the row on the depth (`group_id_1`, `group_id_2`), so `orderBy` needs `parameters: { depth: N }` or fails with `the specified identifier is not available: 'group'`. Sort resolution already inherits the selected dimension's parameters, so this followed once the kind existed; covered by tests for the default and for an explicit depth - Schema builder + `src/schema/schema.json` describe the int kind ### Open questions - **Row cap.** Group comparison over a large hierarchy can exceed the 100-row page cap; charts don't paginate yet (#170, compiler half in !513) ### Notes - Flows tracked directly in a project at the requested depth bucket by project namespace ID, which resolves to `group: null`. A single response can hold several null-group rows; charts should drop them. This is engine behaviour, documented on the dimension - The frontend renders the dimension through the existing `Group: LinkPresenter` mapping, which needs `webUrl` and `fullName` — both are in the `render_group` selection ### Blocked by All merged: - Framework: gitlab!254110 (traversal_path dimension), gitlab!255052 (descendants filter) - DuoWorkflows: gitlab!255369 (dimension and filter, merged 2026-09-18) ### References - Adoption tab GLQL scan: https://gitlab.com/groups/gitlab-org/-/work_items/23420#note_3834970807 - Tracking: #188. Sibling DAP Impact issues: #209, #213, #214, #215, #220 - https://gitlab.com/gitlab-org/glql/-/work_items/212 (DuoWorkflows twin by rcrespo3) was closed as a duplicate in favour of this issue on 2026-09-16