feat: add sumDailyBatch() for batch billing queries

Single query with GROUP BY metric for summing multiple metrics
from the daily table. Returns array<string, int>.

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

Author: lohanidamodar

src/Usage/Adapter.php

@@ -133,6 +133,15 @@ abstract public function findDaily(array $queries = []): array;
      */
     abstract public function sumDaily(array $queries = [], string $attribute = 'value'): int;
 
+    /**
+     * Sum multiple event metrics from the pre-aggregated daily table in one query.
+     *
+     * @param array<string> $metrics List of metric names
+     * @param array<\Utopia\Query\Query> $queries Additional filters (e.g. date range)
+     * @return array<string, int> Metric name => sum value
+     */
+    abstract public function sumDailyBatch(array $metrics, array $queries = []): array;
+
     /**
      * Set the namespace prefix for table names.
      *

src/Usage/Adapter/ClickHouse.php

@@ -1648,6 +1648,70 @@ public function sumDaily(array $queries = [], string $attribute = 'value'): int
         return (is_array($json) && isset($json['data'][0]['total'])) ? (int) $json['data'][0]['total'] : 0;
     }
 
+    /**
+     * Sum multiple event metrics from the pre-aggregated daily table in one query.
+     *
+     * @param array<string> $metrics
+     * @param array<Query> $queries
+     * @return array<string, int>
+     * @throws Exception
+     */
+    public function sumDailyBatch(array $metrics, array $queries = []): array
+    {
+        if (empty($metrics)) {
+            return [];
+        }
+
+        $this->setOperationContext('sumDailyBatch()');
+
+        $totals = \array_fill_keys($metrics, 0);
+
+        $fromTable = $this->buildTableReference($this->getEventsDailyTableName());
+
+        // Build metric IN params
+        $metricParams = [];
+        $metricPlaceholders = [];
+        foreach ($metrics as $i => $metric) {
+            $paramName = 'metric_' . $i;
+            $metricParams[$paramName] = $metric;
+            $metricPlaceholders[] = "{{$paramName}:String}";
+        }
+        $metricInClause = implode(', ', $metricPlaceholders);
+
+        $parsed = $this->parseQueries($queries, Usage::TYPE_EVENT);
+        $params = array_merge($metricParams, $parsed['params']);
+
+        $whereData = $this->buildWhereClause($parsed['filters'], $params);
+        $whereClause = $whereData['clause'];
+        $params = $whereData['params'];
+
+        $metricFilter = $this->escapeIdentifier('metric') . " IN ({$metricInClause})";
+        $whereClause = !empty($whereClause)
+            ? $whereClause . ' AND ' . $metricFilter
+            : ' WHERE ' . $metricFilter;
+
+        $sql = "
+            SELECT metric, SUM(value) as total
+            FROM {$fromTable}{$whereClause}
+            GROUP BY metric
+            FORMAT JSON
+        ";
+
+        $result = $this->query($sql, $params);
+        $json = json_decode($result, true);
+
+        if (is_array($json) && isset($json['data']) && is_array($json['data'])) {
+            foreach ($json['data'] as $row) {
+                $metricName = $row['metric'] ?? '';
+                if (isset($totals[$metricName])) {
+                    $totals[$metricName] = (int) ($row['total'] ?? 0);
+                }
+            }
+        }
+
+        return $totals;
+    }
+
     /**
      * Get time series data for metrics with query-time aggregation.
      *

src/Usage/Adapter/Database.php

@@ -284,6 +284,22 @@ public function findDaily(array $queries = []): array
         return $this->find($queries, Usage::TYPE_EVENT);
     }
 
+    /**
+     * Sum multiple metrics from daily table — falls back to individual sumDaily calls.
+     *
+     * @param array<\Utopia\Query\Query> $queries
+     * @return array<string, int>
+     */
+    public function sumDailyBatch(array $metrics, array $queries = []): array
+    {
+        $totals = \array_fill_keys($metrics, 0);
+        foreach ($metrics as $metric) {
+            $metricQueries = array_merge($queries, [Query::equal('metric', [$metric])]);
+            $totals[$metric] = $this->sumDaily($metricQueries);
+        }
+        return $totals;
+    }
+
     /**
      * Sum from daily table — Database adapter falls back to regular sum for events.
      *

src/Usage/Usage.php

@@ -224,6 +224,19 @@ public function sumDaily(array $queries = [], string $attribute = 'value'): int
         return $this->adapter->sumDaily($queries, $attribute);
     }
 
+    /**
+     * Sum multiple event metrics from the pre-aggregated daily table in one query.
+     *
+     * @param array<string> $metrics List of metric names
+     * @param array<\Utopia\Query\Query> $queries Additional filters (e.g. date range)
+     * @return array<string, int> Metric name => sum value
+     * @throws \Exception
+     */
+    public function sumDailyBatch(array $metrics, array $queries = []): array
+    {
+        return $this->adapter->sumDailyBatch($metrics, $queries);
+    }
+
     /**
      * Set the namespace prefix for table names.
      *