Skip to main content

Analytics & Aggregations

HonoCube allows you to compute analytical metrics, group by dimensions, and generate time-series date histograms directly through the dedicated GET /aggregate endpoint.


Configuration​

Enable aggregations in your resource definition:

export const ordersResource = defineResource({
name: "orders",
table: ordersTable,
aggregate: {
enabled: true,
metrics: ["count", "sum", "avg", "min", "max"], // Allowed metric functions
groupBy: ["status", "category", "country"], // Allowed dimensions
dateIntervals: ["day", "week", "month", "year"], // Allowed time buckets
maxBuckets: 100, // Maximum buckets allowed per query
},
});

Options​

OptionTypeDefaultDescription
enabledbooleanfalseEnables the GET /aggregate endpoint.
metricsArray<"count" | "sum" | "avg" | "min" | "max">AllWhitelist of aggregation functions clients may compute.
groupBystring[]All columnsWhitelist of columns clients may group by.
dateIntervalsArray<"day" | "week" | "month" | "year">AllWhitelist of date histogram bucketing intervals.
maxBucketsnumber100Safety limit on returned grouped rows.

Querying Aggregations​

1. Basic Metrics​

Compute the total number of orders and the sum/average of order amounts:

GET /orders/aggregate?metrics=count,sum(total),avg(total)

Response:

{
"success": true,
"data": {
"count": 1420,
"sum_total": 85200.50,
"avg_total": 60.00
}
}

2. Grouping by Dimensions​

Break down metrics by status:

GET /orders/aggregate?metrics=count,sum(total)&groupBy=status

Response:

{
"success": true,
"data": [
{ "status": "completed", "count": 1200, "sum_total": 78000.00 },
{ "status": "pending", "count": 180, "sum_total": 5400.50 },
{ "status": "cancelled", "count": 40, "sum_total": 1800.00 }
]
}

3. Date Histogram Bucketing​

Generate time-series buckets for charting and analytics:

GET /orders/aggregate?metrics=count,sum(total)&dateField=createdAt&dateInterval=month

Response:

{
"success": true,
"data": [
{ "date": "2026-01-01", "count": 420, "sum_total": 24000.00 },
{ "date": "2026-02-01", "count": 510, "sum_total": 31000.00 },
{ "date": "2026-03-01", "count": 490, "sum_total": 30200.50 }
]
}

4. Combining with Filters​

Aggregation queries respect the same filter parameters as standard list endpoints:

GET /orders/aggregate?metrics=count,sum(total)&groupBy=country&status=completed&createdAt__gte=2026-01-01