feat(aggregation): ad-hoc time-bucket aggregation across REST + GraphQL

[rubenvdlinde]

Summary

• Ad-hoc, client-controlled aggregation primitive that buckets register-schema rows by a field (categorical) or by a date_trunc interval with optional from/to bounds, available on both REST and GraphQL with the same { groups: [{ key, value }], backend, cached } response shape.
• Unblocks the openconnector dashboard rebuild (6 charts) and the nextcloud-vue CnChartWidget.dataSource bucket: { field, interval, fromVar, toVar } shorthand.
• Complementary to (not overlapping with) the in-flight aggregations-backend-native change — that one ships Solr/ES translators for the named annotation path; this one wires AggregationQuery.dateBucket through to Postgres / REST / GraphQL for the ad-hoc path. Same value object, two surfaces.

Spec change

openspec/changes/add-time-bucket-aggregation/ — proposal, design (9 decisions), aggregation-api new capability spec, graphql-api delta spec, tasks.md (43/43 ticked). openspec validate add-time-bucket-aggregation --strict passes.

kind: code per ADR-032 — no schema register patches, pure runtime extension.

Backend changes

Area	Change
lib/Service/Aggregation/AggregationRunner.php	New public runAdhoc(Register, Schema, AggregationQuery) + runAdhocByRef(...) + findSchema(). tryNativeAggregation() extended with ?array $dateBucket → emits date_trunc(?, "$field")::text AS bucket, ... GROUP BY bucket ORDER BY bucket. New bucketInPhp() + truncateTimestamp() + coerceBucketKey() for non-Postgres fallback.
lib/Service/Aggregation/TimeseriesRequestValidator.php (NEW)	Shared validator for REST + GraphQL: field allow-list against Schema::getProperties() + _created/_updated/_deleted_at, interval vocabulary, sub-day-requires-date-time rule, metric/metricField pairing. Throws InvalidArgumentException with client-safe messages.
lib/Controller/AggregationController.php	New timeseries() action. 400/403/404 translation. Constructor now takes the validator.
lib/Service/GraphQL/SchemaGenerator/TypeMapperHandler.php	New GroupByInput / TimeInterval enum / AggregationMetric enum / GroupBucket types via lazy getters. getListArgs() + getConnectionType() extended.
lib/Service/GraphQL/GraphQLResolver.php	resolveList() calls new private resolveGroupBy() when args.groupBy is supplied. Validation / RBAC failures surface as GraphQL field-errors.
appinfo/routes.php	New aggregation#timeseries route at /api/objects/aggregations/{register}/{schema}/timeseries, ordered before the existing {name} wildcard.

Tests

• 12 TimeseriesRequestValidatorTest cases — categorical pass, time-bucket pass, empty field, unknown field, magic metadata cols, sub-day-on-date-only, missing bounds, unparseable bounds, unknown interval, non-count without metricField, non-count with unknown metricField, sum over declared field.
• 5 AggregationControllerTimeseriesTest cases — 404 (schema), 400 (validation), 403 (RBAC), 200 (happy path body parity), 404 (register).
• AggregationControllerTest constructor updated for the new validator dependency.
• Full Unit Tests suite (12 243 tests / 25 991 assertions) green inside the dev container.

Quality gates (strict)

Gate	Status
PHPCS	clean on all touched lib files
PHPMD	clean — targeted @SuppressWarnings on bucketInPhp, resolveList, and validate for legitimate branching-density cases
Psalm	No errors found!
PHPStan level 8	clean. Baseline reclassified the pre-existing string === null entry to int === null after refactoring three call sites away from a redundant $entity instanceof ObjectEntity ? ... : ... ternary
PHPUnit	full Unit Tests suite green

Docs

• docs/technical/aggregation-api.md — both surfaces, validation rules, response shape, status codes, Postgres index guidance, decision matrix between named-annotation and ad-hoc primitive.
• openspec/platform-capabilities.md — ad-hoc primitive companion sentence on the aggregations row.

Deferred work (issues filed at planning time)

• Multi-field groupBy on ad-hoc aggregation #1606 Multi-field groupBy
• Running / cumulative aggregates on time-bucket primitive #1607 Running / cumulative aggregates
• Multi-metric ad-hoc aggregation (count + sum in one request) #1608 Multi-metric in one request
• MySQL / SQLite native time-bucket aggregation #1609 Native MySQL / SQLite bucketing
• Cache ad-hoc time-bucket aggregations in AggregationCache #1610 Caching ad-hoc queries

Test plan

• Pull the branch, dev-container composer install, restart Nextcloud
• curl 'http://localhost:8080/index.php/apps/openregister/api/objects/aggregations/{register}/{schema}/timeseries?field=_created&interval=DAY&from=2026-05-01T00:00:00Z&to=2026-05-22T00:00:00Z' -u admin:admin -H 'OCS-APIRequest: true' returns {groups: [...], backend: "postgres", cached: false}
• Same query in GraphQL: query { <schema>(groupBy: { field: "_created", interval: DAY, from: "...", to: "..." }) { totalCount groups { key value } } } returns matching groups
• 400 path: omit field → REST 400; GraphQL field-error on groups
• 403 path: a user without list permission on the schema gets 403
• Sum of groups[*].value equals totalCount when metric: COUNT
• CI: PHPCS / PHPMD / Psalm / PHPStan / PHPUnit all green

[github-actions]

Quality Report — ConductionNL/openregister @ 399e365

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		❌
stylelint		❌
composer			❌	✅ 162/162
npm			✅	✅ 532/532
PHPUnit					⏭️
Newman					⏭️
Playwright					⏭️

---

Quality workflow — 2026-05-21 12:36 UTC

Download the full PDF report from the workflow artifacts.