## Goal Let an analytics GLQL query aggregate across several groups and/or projects, so the dashboard group/project filters at `/explore/analytics_dashboards` can drive panels. Needed for ~DAPImpact_v1. ## Backend API (GitLab >= 19.3, experiment) Shipped in [#600674](https://gitlab.com/gitlab-org/gitlab/-/work_items/600674) via [!246878](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246878) and [!248073](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/248073). - Every aggregation engine field under `analytics` accepts `descendantsScope: { groupFullPaths: [ID!], projectFullPaths: [ID!] }`. Full paths, not GIDs. - At most 20 paths combined, after case-insensitive dedup. - The two lists are OR-ed with each other and AND-ed with all other filters. A project inside a listed group is redundant, not an error. - Roots: - `project(fullPath:) { analytics }` - the argument is rejected. - `group(fullPath:) { analytics }` - optional; listed paths must be descendants of the group. - `organization { analytics }` - at least one path is required (org-wide without paths is [#611273](https://gitlab.com/gitlab-org/gitlab/-/work_items/611273)). `id` defaults to the current organization, which both `/api/glql` and `/api/v4/glql` set. Gated by `read_organization_analytics` (any organization member), then every path is checked against the engine's own ability. - Unknown or inaccessible paths fail the whole request: "The following sources are not accessible: a, b". ```graphql query GLQL { organization { analytics { duoCodeSuggestions(descendantsScope: { groupFullPaths: ["gitlab-org", "gitlab-com"] }) { aggregated(...) { count nodes { ... } } } } } } ``` ## Design Scope can be set in three ways, in order of precedence: 1. **Bindings** ([#154](https://gitlab.com/gitlab-org/glql/-/work_items/154)) - a filter binding on `project` / `group` / `namespace` replaces the scope written in the query. Bindings are just another way to write the filters below and carry no scope logic of their own. 2. **The query** - `project` and `group` accept a scalar or a list. 3. **The scope hint** (`CompileContext.project` / `group`) - the group or project the page is on. Stays single-valued, is used only when the query carries no scope, and is ignored when the query carries a list. | Query | Root | `descendantsScope` | |---|---|---| | `group = "a"` | `group(fullPath: "a")` | none (unchanged) | | `group in ("a", "b")` | `organization` | `groupFullPaths: ["a", "b"]` | | `project in ("a/x", "b/y")` | `organization` | `projectFullPaths: ["a/x", "b/y"]` | | `group = "a" and project in ("a/x", "a/y")` | `group(fullPath: "a")` | `projectFullPaths: ["a/x", "a/y"]` | | `group in (...) and project in (...)` | `organization` | both lists, union (as the backend does) | A single-element list is treated as the scalar form. Lists are analytics mode only: standard sources, and the `namespace` root used by the Projects source, have no multi-scope backend and return a compile error. ## Compiler changes - `extract_context` accepts `in` with list values on `project` / `group`; `MutuallyExclusiveFilters` is relaxed for scalar `group` + list `project`. It also sets the root (`Organization`, or the scalar group) at extraction time rather than in codegen: `resolve_scope_hint` only fills an empty `Context.scope`, so this is what makes the hint ignored when a list is present, with no separate rule needed. - `Context.scope` stays the GraphQL root; add `descendants { groups, projects }` next to it and a path-less `ScopeRoot::Organization`. Sources declare list support with `SourceAnalyzer::supports_multi_scope()` (on by default for analytics-mode analyzers, overridable per source; published as `multi_scope` in the schema document). `allowed_scopes()` stays the set of roots a caller can pass, so `organization` is not in it, and standard sources reject lists with a dedicated error. - Analytics codegen emits the `organization` root and the `descendantsScope` input object (the first non-scalar argument in analytics codegen). Mirror the 20-path cap at compile time; the backend stays authoritative. - Transform accepts `organization` as a response root, adds the matching `InvalidScope` variant, and surfaces the "sources are not accessible" GraphQL error. - Once the query accepts lists, list values in scope-field filter bindings work with no further binding changes. - Requires GitLab >= 19.3; document it the way pipelines analytics documents >= 19.2. Lands as MRs in the #154 train, after the scalar scope filter-binding MRs. ## Frontend (gitlab-org/gitlab) - `explore/analytics_dashboards`: `dashboard_filters.vue` mounts the groups/projects filters without `multi-select`, `details.vue` keeps only the first selection, and `filters.groups[]` / `filters.projects[]` reach `visualizations/glql.vue` but it declares no `filters` prop. Turn those arrays into `group` / `project` filter bindings and stop passing the singular `scope` prop when bindings are present. - Send full paths (the `groups[]` URL param carries numeric IDs; the resolved group objects have `fullPath`). - Because the backend ORs groups and projects, do not send a group together with a cherry-picked project inside it. Auto-selecting the parent group ([#602450](https://gitlab.com/gitlab-org/gitlab/-/work_items/602450)) would do exactly that. - Presenters and the executor's `?group=` / `?project=` params derive the namespace from the URL; fine for stat and chart panels. ## Out of scope - Standard-mode multi group (`type = Issue and group in (...)`, [#624802](https://gitlab.com/gitlab-org/gitlab/-/work_items/624802)) - no backend for it. - Org-wide aggregation without listing sources ([#611273](https://gitlab.com/gitlab-org/gitlab/-/work_items/611273)). - New GLQL sources for `deployments` / `duoWorkflows`. - Single-scope escape hatch ([#39](https://gitlab.com/gitlab-org/glql/-/work_items/39)). ## Related - [#186](https://gitlab.com/gitlab-org/glql/-/work_items/186) - closed, folded in here. - [#154](https://gitlab.com/gitlab-org/glql/-/work_items/154) control bindings, [&22615](https://gitlab.com/groups/gitlab-org/-/work_items/22615), [&21859](https://gitlab.com/groups/gitlab-org/-/work_items/21859) dashboard view filtering, [#569421](https://gitlab.com/gitlab-org/gitlab/-/work_items/569421) research.