feat(aggregate): type, name and decode rows as a read returns them

[abnegate]

Problem

aggregate() returned each row exactly as the driver fetched it:

• Numbers came back as text on MariaDB, MySQL and PostgreSQL. A sum of integers on MariaDB was a DECIMAL string such as "7.0000".
• Booleans came back as 0/1, datetimes in the engine's format, and arrays and objects as JSON.
• Attributes with filters came back still encoded.
• Internal groups came back under their storage column (_uid, _createdAt, _tenant), and joined groups under their bare name.

Every consumer had to rebuild the row against the schema. appwrite/appwrite#14537 does that in Appwrite\Utopia\Database\Aggregation (416 lines). This moves that behaviour into the library so the class can be deleted.

Change

A new Utopia\Database\Aggregation shapes each row from the queries and the collections read.

Aggregates

Aggregate	Type
count, countDistinct, bitAnd, bitOr, bitXor	int
avg, stddev*, variance, varPop, varSamp	float
sum	int over an integer attribute, float otherwise (a whole DECIMAL like "7.0000" becomes 7)
min, max	the attribute's own type (int, float, bool, formatted datetime, decoded JSON)

An aggregate over no rows stays null.

Groups

• Each group is named as a read names its attribute: $id, $createdAt, $permissions, and so on.
• A joined group is qualified by its join alias (o.label, o.$id), including when the queries name it bare and only the join declares it.
• Each group is cast as find() casts it and passed through its attribute's filters (Database::decode), from the joined collection's attribute for a joined group.
• The tenant group is returned as the adapter reads it, as find() returns it.

Other

• The default alias (<method>_<attribute>) is built without a regex.
• fetch() hands back the joined collections it already resolved, so nothing is resolved twice. JoinResolutionTest holds that.

MongoDB, Memory and Redis still refuse aggregates, as before.

Release

This changes what aggregate() returns: value types, and group keys for internal and joined attributes. aggregate() is new in 8.x, and Appwrite applies exactly this shape itself today. The commit is a feat and the change is additive for the API surface, so 8.3.0 (minor) rather than a patch. Anyone reading _uid or a bare joined key from aggregate() rows should switch to $id / alias.key.

Tests

• tests/unit/AggregationTest.php ports Appwrite's AggregationTest and runs every case on SQLite, with stringified fetches (as MariaDB, MySQL and PostgreSQL return them) and native fetches. It covers aggregate typing, statistics as floats, a whole DECIMAL sum as an int, null over no rows, group typing (bool, array, datetime, int, float), internal groups under public names, joined groups qualified (alone, beside a main group of the same name, internal, named bare), joined aggregates typed by the joined attribute, unaliased default names, filter decoding for main and joined groups, and rows carrying no ungrouped internal attribute. 18 of the 22 cases fail against main's aggregate().
• AggregationTests::testAggregateRowsAreTypedNamedAndDecodedAsAReadReturnsThem checks typing and naming on every adapter. It fails on main on MySQL.
• Existing unit and E2E tests that asserted _uid / _tenant keys or bare joined group names now assert the read names ($id, note.$id, it.name, purchase.status, ...).

Verified locally:

• Full E2E matrix in Docker passes on MySQL, MariaDB, Postgres, SharedTables/{MySQL, MariaDB, Postgres, MongoDB, Redis}, Mirror, Pool, Memory, Redis, MongoDB and Schemaless/MongoDB. The one MongoDB failure, testListCollectionsReturnsOnlyReadableDefinitions, came from running three adapters in parallel against the same Mongo instance and passes when run on its own.
• SQLite E2E runs natively. The only failures are cache tests that need Redis, and they fail the same way on main there.
• The unit suite passes in Docker. Pint and both PHPStan configurations are clean.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 50 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: utopia-php/database/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 388a0681-b204-49c2-a314-e0a317c8faf4

📥 Commits

Reviewing files that changed from the base of the PR and between 0555ec9 and d1b9f2f.

📒 Files selected for processing: 14

• src/Database/Aggregation.php
• src/Database/Trait/Documents.php
• tests/e2e/Adapter/Scopes/AggregationTests.php
• tests/e2e/Adapter/Scopes/DocumentTests.php
• tests/e2e/Adapter/Scopes/JoinTests.php
• tests/unit/AggregationTest.php
• tests/unit/Documents/AggregateOrderTest.php
• tests/unit/Documents/AggregateSelectTest.php
• tests/unit/Joins/AggregateMinorsTest.php
• tests/unit/Joins/AggregateResultNamesTest.php
• tests/unit/Joins/JoinInternalColumnsTest.php
• tests/unit/Joins/JoinedAttributeResolutionTest.php
• tests/unit/Joins/JoinedShapesTest.php
• tests/unit/PermissionScope/FullOuterJoinAggregateVisibilityTest.php

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}