feat: add max param to count() for bounded counts

Push the count cap down into the DB layer so callers that only need a
capped total (e.g. rendering "5000+") can stop ClickHouse early instead
of scanning the full filtered set. ClickHouse wraps the count in a
LIMIT-bounded subquery; Database delegates to utopia-php/database's
existing $max arg.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lohanidamodar

src/Usage/Adapter.php

@@ -97,11 +97,17 @@ abstract public function find(array $queries = [], ?string $type = null): array;
     /**
      * Count metrics using Query objects.
      *
+     * When $max is non-null the count is bounded at the database level —
+     * the adapter must stop counting once $max rows have been matched.
+     * This keeps large counts cheap for endpoints that only need a capped
+     * total. When $max is null the count is unbounded.
+     *
      * @param array<\Utopia\Query\Query> $queries
      * @param string|null $type Metric type: 'event', 'gauge', or null (count both)
+     * @param int|null $max Optional upper bound for the count (inclusive)
      * @return int
      */
-    abstract public function count(array $queries = [], ?string $type = null): int;
+    abstract public function count(array $queries = [], ?string $type = null, ?int $max = null): int;
 
     /**
      * Sum metric values using Query objects.

src/Usage/Adapter/ClickHouse.php

@@ -1625,33 +1625,39 @@ private function parseAggregatedResults(string $result, string $type = 'event'):
     /**
      * Count metrics using Query objects.
      *
+     * When $max is non-null the count is bounded at the database level via
+     * a `LIMIT {max}` inside a subquery — ClickHouse stops scanning once
+     * that many rows have been matched, keeping large counts cheap.
+     *
      * @param array<Query> $queries
      * @param string|null $type 'event', 'gauge', or null (both)
+     * @param int|null $max Optional upper bound (inclusive) for the count
      * @return int
      * @throws Exception
      */
-    public function count(array $queries = [], ?string $type = null): int
+    public function count(array $queries = [], ?string $type = null, ?int $max = null): int
     {
         $this->setOperationContext('count()');
 
         if ($type !== null) {
-            return $this->countFromTable($queries, $type);
+            return $this->countFromTable($queries, $type, $max);
         }
 
         // Count from both tables
-        return $this->countFromTable($queries, Usage::TYPE_EVENT)
-             + $this->countFromTable($queries, Usage::TYPE_GAUGE);
+        return $this->countFromTable($queries, Usage::TYPE_EVENT, $max)
+             + $this->countFromTable($queries, Usage::TYPE_GAUGE, $max);
     }
 
     /**
      * Count metrics from a specific table.
      *
      * @param array<Query> $queries
      * @param string $type
+     * @param int|null $max Optional upper bound (inclusive) for the count
      * @return int
      * @throws Exception
      */
-    private function countFromTable(array $queries, string $type): int
+    private function countFromTable(array $queries, string $type, ?int $max = null): int
     {
         $tableName = $this->getTableForType($type);
         $fromTable = $this->buildTableReference($tableName);
@@ -1665,10 +1671,20 @@ private function countFromTable(array $queries, string $type): int
         $whereClause = $whereData['clause'];
         $params = $whereData['params'];
 
-        $sql = "
-            SELECT COUNT(*) as total FROM {$fromTable}{$whereClause}
-            FORMAT JSON
-        ";
+        if ($max !== null) {
+            $params['max'] = $max;
+            $sql = "
+                SELECT COUNT(*) as total FROM (
+                    SELECT 1 FROM {$fromTable}{$whereClause} LIMIT {max:UInt64}
+                ) sub
+                FORMAT JSON
+            ";
+        } else {
+            $sql = "
+                SELECT COUNT(*) as total FROM {$fromTable}{$whereClause}
+                FORMAT JSON
+            ";
+        }
 
         $result = $this->query($sql, $params);
         $json = json_decode($result, true);

src/Usage/Adapter/Database.php

@@ -455,18 +455,24 @@ public function find(array $queries = [], ?string $type = null): array
     /**
      * Count metrics using Query objects.
      *
+     * When $max is non-null the count is bounded at the database level —
+     * utopia-php/database accepts a `$max` argument that pushes the cap
+     * down into the underlying SQL.
+     *
      * @param array<Query> $queries
      * @param string|null $type
+     * @param int|null $max Optional upper bound (inclusive) for the count
      * @return int
      */
-    public function count(array $queries = [], ?string $type = null): int
+    public function count(array $queries = [], ?string $type = null, ?int $max = null): int
     {
         /** @var int $count */
-        $count = $this->db->getAuthorization()->skip(function () use ($queries) {
+        $count = $this->db->getAuthorization()->skip(function () use ($queries, $max) {
             $dbQueries = $this->convertQueriesToDatabase($queries);
             return $this->db->count(
                 collection: $this->collection,
-                queries: $dbQueries
+                queries: $dbQueries,
+                max: $max
             );
         });
 

src/Usage/Usage.php

@@ -173,14 +173,19 @@ public function find(array $queries = [], ?string $type = null): array
     /**
      * Count metrics using Query objects.
      *
+     * When $max is non-null the count is bounded at the database level.
+     * Callers that only need a capped total (e.g. to render "5000+") should
+     * pass $max so the adapter can short-circuit the count for large tables.
+     *
      * @param array<\Utopia\Query\Query> $queries
      * @param string|null $type Metric type: 'event', 'gauge', or null (count both)
+     * @param int|null $max Optional upper bound for the count (inclusive)
      * @return int
      * @throws \Exception
      */
-    public function count(array $queries = [], ?string $type = null): int
+    public function count(array $queries = [], ?string $type = null, ?int $max = null): int
     {
-        return $this->adapter->count($queries, $type);
+        return $this->adapter->count($queries, $type, $max);
     }
 
     /**