feat(database-adapter): validate groupBy queries, share contract with ClickHouse

The Database adapter does not push aggregation through utopia-php/database
(no groupBy on the base Query class), so groupBy queries continue to be
elided from the converted query list - callers get raw rows just as they
do today with groupByInterval. The change is in validation: rejecting
malformed groupBy use up front means the negative-case contract is
identical on both backends.

- validateGroupByQueries() runs at the top of convertQueriesToDatabase.
  Rejects groupBy attributes outside the union of EVENT_COLUMNS and
  GAUGE_COLUMNS (the Database adapter shares one collection for both
  types). Rejects groupBy without an accompanying groupByInterval.
- Negative-case integration tests live in UsageBase so both adapters
  exercise them: unknown attribute throws, groupBy-without-interval
  throws.

Author: lohanidamodar

src/Usage/Adapter/Database.php

@@ -367,9 +367,13 @@ public function sumDaily(array $queries = [], string $attribute = 'value'): int
      *
      * @param array<Query> $queries
      * @return array<DatabaseQuery>
+     * @throws \Exception When a groupBy attribute is not a valid dimension column,
+     *                    or when groupBy is used without groupByInterval.
      */
     private function convertQueriesToDatabase(array $queries): array
     {
+        $this->validateGroupByQueries($queries);
+
         $dbQueries = [];
         foreach ($queries as $query) {
             $method = $query->getMethod();
@@ -474,15 +478,62 @@ private function convertQueriesToDatabase(array $queries): array
                     break;
 
                 case UsageQuery::TYPE_GROUP_BY_INTERVAL:
-                    // groupByInterval is not supported by the Database adapter.
-                    // Silently skip — callers get raw (non-aggregated) results.
+                case UsageQuery::TYPE_GROUP_BY:
+                    // groupByInterval and groupBy are not pushed down to the
+                    // Database adapter; callers get raw (non-aggregated) results.
+                    // Validation runs in validateGroupByQueries() before this loop.
                     break;
             }
         }
 
         return $dbQueries;
     }
 
+    /**
+     * Validate groupBy / groupByInterval interactions in the supplied queries.
+     *
+     * Mirrors the ClickHouse adapter contract: groupBy attributes must exist on
+     * the matching schema (event vs gauge — we default to the broader event set
+     * for the Database adapter since both share one collection), and groupBy
+     * must always be paired with groupByInterval so the cloud-facing API stays
+     * consistent across backends.
+     *
+     * @param array<Query> $queries
+     * @throws \Exception
+     */
+    private function validateGroupByQueries(array $queries): void
+    {
+        $hasGroupBy = false;
+        $hasGroupByInterval = false;
+        $allowed = array_unique(array_merge(Metric::EVENT_COLUMNS, Metric::GAUGE_COLUMNS));
+
+        foreach ($queries as $query) {
+            $method = $query->getMethod();
+
+            if ($method === UsageQuery::TYPE_GROUP_BY_INTERVAL) {
+                $hasGroupByInterval = true;
+                continue;
+            }
+
+            if ($method !== UsageQuery::TYPE_GROUP_BY) {
+                continue;
+            }
+
+            $hasGroupBy = true;
+            $attribute = $query->getAttribute();
+
+            if (!in_array($attribute, $allowed, true)) {
+                throw new \Exception(
+                    "Invalid groupBy attribute '{$attribute}'. Allowed: " . implode(', ', $allowed)
+                );
+            }
+        }
+
+        if ($hasGroupBy && !$hasGroupByInterval) {
+            throw new \Exception('groupBy requires groupByInterval to be specified');
+        }
+    }
+
     /**
      * @param array<Query> $queries
      * @param string|null $type

tests/Usage/UsageBase.php

@@ -639,4 +639,27 @@ public function testGroupByIntervalWithLimitOffset(): void
 
         $this->assertGreaterThanOrEqual(1, count($results));
     }
+
+    public function testGroupByUnknownAttributeThrows(): void
+    {
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessageMatches("/groupBy attribute 'not_a_column'/");
+
+        $this->usage->find([
+            UsageQuery::groupByInterval('time', '1h'),
+            UsageQuery::groupBy('not_a_column'),
+            Query::equal('metric', ['gbi-requests']),
+        ], Usage::TYPE_EVENT);
+    }
+
+    public function testGroupByWithoutGroupByIntervalThrows(): void
+    {
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessageMatches('/groupBy requires groupByInterval/');
+
+        $this->usage->find([
+            UsageQuery::groupBy('service'),
+            Query::equal('metric', ['gbi-requests']),
+        ], Usage::TYPE_EVENT);
+    }
 }