Bound aggregation engine requests by range span, dimensions and metrics
Part of Project Bulkhead. Issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/636113
What does this MR do and why?
Puts a ceiling on what one aggregation engine GraphQL request (project.analytics.*, group.analytics.* and the organization equivalents) can ask ClickHouse to do. Today the engines accept a request with no date range at all, or one spanning decades with daily buckets, selecting every dimension and metric the engine defines; validate_request! on the engine resolver is an empty hook.
Behind the aggregation_engine_request_limits feature flag, validate_request! now rejects a request with a GraphQL argument error when:
- it carries no date range start. At least one of the engine's date range filters must have its
*Fromend set (for examplecreatedAtFrom). A range with a start and no end is measured up to the current time, sotimestamp >= -30din GLQL passes; a range with only an end does not count, because it still reads from the beginning of the table. - a date range spans more than
MAX_DATE_RANGE_SPAN(366 days). - it selects more than
MAX_DIMENSIONS(10) dimensions or more thanMAX_METRICS(20) metrics.
Engines without a date range filter (the ActiveRecord engine only supports exact_match) skip the range check. With the flag off nothing changes.
Business impact
Today an aggregation-engine request may carry no date range, span decades, and select every dimension and metric; anyone with read_cycle_analytics (anonymous users on public projects included) can send it, and each result page re-runs the aggregation on the ClickHouse cluster shared by every customer's Value Stream, DORA and AI dashboards. With aggregation_engine_request_limits enabled for a top-level group (default off), the resolver rejects such requests before any SQL runs, with a GraphQL argument error the caller sees in errors[] (a GLQL block renders it in place of its view): a date range start is required: set createdAtFrom or metricMergedAtFrom (argument names per engine), the createdAt date range may not span more than 366 days, too many dimensions requested: 11 of a maximum of 10, or too many metrics requested: 21 of a maximum of 20. The built-in dashboards and GLQL panels were checked and all pass. Who benefits: every customer sharing the analytics ClickHouse cluster, whose dashboards slow down when one caller runs a full-table aggregation. Two caveats: for MergeRequests, Deployments, Pipelines and AgentPlatformSessions the range bounds the rows aggregated, not the rows read (follow-up below), and user-authored GLQL blocks without any date predicate start failing once the flag is on, so the rollout issue asks for a search for those first. Flag off: nothing changes.
Queries this change generates
The MR adds no SQL; it stops requests before compilation. Rejected before SQL (flag on), error text from validate_request!:
| Request | Error |
|---|---|
no *From on any date filter |
a date range start is required: set createdAtFrom or metricMergedAtFrom |
createdAtFrom to createdAtTo > 366 days |
the createdAt date range may not span more than 366 days |
| 11 dimensions | too many dimensions requested: 11 of a maximum of 10 |
| 21 metrics | too many metrics requested: 21 of a maximum of 20 |
A start-only range (timestamp >= -30d in GLQL) is measured up to Time.current and passes.
What a bounded request still compiles to, captured from ee/spec/requests/api/graphql/analytics/merge_requests_spec.rb (log/clickhouse.log; per-column argMax list elided). GraphQL:
query {
group(fullPath: "<group_path>") {
analytics {
mergeRequests(createdAtFrom: "2026-01-01T00:00:00Z", createdAtTo: "2026-01-25T00:00:00Z", targetBranch: ["main"]) {
aggregated(orderBy: [{ identifier: "stateId", direction: ASC }]) {
nodes { dimensions { targetBranch stateId } totalCount throughputCount }
}
}
}
}
}Compiled ClickHouse SQL (the range lands on the output of the de-duplication subquery, as the "date range filter placement" example pins):
SELECT inner.aeq_target_branch, inner.aeq_state_id,
COUNT(*) AS aeq_total_count,
countIf(inner.aeq_throughput_count_secondary = 1) AS aeq_throughput_count
FROM (
SELECT dedup.target_branch AS aeq_target_branch, dedup.state_id AS aeq_state_id,
state_id = 3 AS aeq_throughput_count_secondary, dedup.traversal_path, dedup.id
FROM (
SELECT merge_requests.traversal_path, merge_requests.id,
argMax(merge_requests.target_branch, merge_requests._siphon_replicated_at) AS target_branch,
argMax(merge_requests.created_at, merge_requests._siphon_replicated_at) AS created_at,
argMax(merge_requests.state_id, merge_requests._siphon_replicated_at) AS state_id,
/* ... one argMax per column ... */
FROM merge_requests
WHERE startsWith(merge_requests.traversal_path, '<org_id>/<group_id>/')
GROUP BY ALL
HAVING argMax(merge_requests._siphon_deleted, merge_requests._siphon_replicated_at) = 0
) dedup
WHERE dedup.target_branch IN ('main')
AND dedup.created_at BETWEEN <from_epoch> AND <to_epoch>
GROUP BY ALL
) inner
GROUP BY ALL
ORDER BY aeq_state_id ASC
LIMIT 501 OFFSET 0Survivable threshold
- 366 days. A full year, with a day of slack for leap years, is the longest window the built-in dashboards offer. Longer spans are what turns one request into a full-table aggregation; a client that needs more than a year can issue several requests, each of which is bounded on its own.
- What the span cap bounds, per engine. The engine places a range filter according to the table's primary key (
lib/gitlab/database/aggregation/click_house/engine.rb,pk_filter?andbuild_base_query):- Contributions (
created_at) and DuoWorkflows (created_at): the column is in the primary key, so the range lands in the deduplication subquery'sWHEREand bounds the rows read. - AiUsageEvents and DuoToolCalls (
timestamp), CodeSuggestions (timestamp): no deduplication, the range is aWHEREon a table partitioned by month on that column, so it prunes partitions. - MergeRequests (
created_at,metricMergedAt), Deployments (created_at,finished_at), Pipelines (started_at,finished_at): the primary key istraversal_path, id[, partition_id], so the range is applied to the output of the deduplication subquery, after ClickHouse has read and merged every row under the requested path. AgentPlatformSessions (createdEventAt,merge_column: true) compiles toHAVING. For these four engines the cap bounds the rows aggregated and returned, not the rows read; the read is bounded by the path scope alone.ee/spec/models/analytics/aggregation_engines/merge_requests_spec.rb("date range filter placement") pins this for MergeRequests, so the description cannot drift from the SQL. Bounding the read for these engines is a follow-up below.
- Contributions (
- 10 dimensions, 20 metrics. Every request from the built-in dashboards selects at most two dimensions and four metrics. The caps leave room for ad hoc queries while stopping the "everything at once" request. No engine defines more than 10 dimensions (DuoWorkflows has exactly 10), so grouping by every dimension stays possible. Two engines define more than 20 metrics (DuoWorkflows 34, MergeRequests 19 including the measurement sub-metrics); selecting every one of them in a single request is the only shape the cap rejects.
Checked against the caps: the AI impact and Duo and SDLC trends dashboards (app/assets/javascripts/explore/analytics_dashboards/metrics/**/*.graphql, ee/app/assets/javascripts/explore/analytics_dashboards/graphql/fragments/duo_feature_retention.fragment.graphql), the DAP impact and Duo and SDLC trends GLQL panels (ee/lib/gitlab/analytics/dashboards/system/*.yaml, each panel is bound either through dateField, which glql.js turns into a from/to binding, or through interpolated %{startDate}/%{previousStartDate}/%{endDate} placeholders) and the merge request throughput query. All of them send both ends of a date range and select at most two dimensions and four metrics.
Rollout
- Rollout issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/637724
- The flag is off by default. Rollback is turning the flag off; requests are then validated exactly as before.
- The flag is checked against the top-level group of the project or group in the query (
request_limits_actor), so enabling it for one group covers every project and subgroup under it. The organization entry point uses the organization as its actor and has to be enabled on its own.merge_requests_spec.rb("when request limits are enabled for a top-level group only") pins both. - Embedded analytics GLQL blocks (issues, epics, wikis) and user-authored GLQL panels are passed to the engines as written: neither
lib/api/glql.rbnor the compiler adds a date range. With the flag on, a block whose query has no date predicate at all renders the error "a date range start is required: set timestampFrom" in place of the view; a block withtimestamp >= -30d, the usual way to write one, keeps working. Before enabling, search for embedded analytics blocks without a date predicate.
Verification
ee/spec/requests/api/graphql/analytics/merge_requests_spec.rb, "when request limits are enabled": real queries through the schema for no range, end-only, start-only, exactly 366 days, 367 days, an end-only range next to a bounded one on the other filter, 11 aliased dimensions, 21 aliased metrics, and the flag off; "when request limits are enabled for a top-level group only": the flag enabled for one group limits a project and a subgroup under it, not a project under another group nor the organization entry point, which is limited once the flag is enabled for the organization. Locally: 14 examples, 0 failures.ee/spec/requests/api/graphql/analytics/ai_analytics/agent_platform_sessions_spec.rb: a start-only range on itsmerge_columndate filter with the flag on. Locally: 1 example, 0 failures.ee/spec/models/analytics/aggregation_engines/merge_requests_spec.rb, "date range filter placement": thecreated_atrange is applied after the deduplication subquery. Locally: 1 example, 0 failures.spec/graphql/resolvers/analytics/aggregation/engine_resolver_spec.rb: one direct call for an engine without a date range filter, a branch no mounted engine can reach through a request. Locally, together withspec/lib/gitlab/database/aggregation/graphql/mounter_spec.rb: 9 examples, 0 failures.- The other engine request specs stub the flag off because their fixtures send no date range.
Follow-ups
- ClickHouse query limits (
max_execution_time,max_memory_usage) for the analytics user, so a query Rails has stopped waiting for also stops in ClickHouse.ClickHouse::Client.selecttakes no per-query settings today, so this is a framework change. - A short-lived cache keyed on the query, so OFFSET paging and repeated identical requests do not re-run the aggregation.
- Cap the positive filter lists the same way as exclusion lists (
MAX_EXCLUSION_VALUES). - Make the span cap bound the read for MergeRequests, Deployments, Pipelines and AgentPlatformSessions: apply immutable date columns (
created_at,started_at) inside the deduplication subquery, add a date partition or minmax skip index on them, and give AgentPlatformSessions aWHERE-level predicate (for examplesession_year). Until then the read on those engines is bounded by the path scope only. - Docs:
doc/development/aggregation_engines.mdnow shows thevalidate_request!override callingsuperand documents the limits; the engine request specs other than MergeRequests keep the flag stubbed off because their fixtures and window-metric expectations (retention, previous period) were written without a date range.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.