Summarize numeric fields
Compute a mean, total, minimum, or maximum for numeric data in a model.
Prisma · Function
aggregate
Prisma Client's aggregate() calculates summary values such as averages, sums, minimums, and maximums over numeric model fields. Filtering, ordering, and limiting can be combined with the calculation.
How it works
Call aggregate() on a model delegate to calculate aggregate values across the records that match the query. Select numeric fields with _avg, _sum, _min, or _max; filtering, ordering, and limiting can shape the records included before the calculation.
Syntax
await prisma.<model>.aggregate({ _avg?: { <numberField>: true }, _sum?: { <numberField>: true }, _min?: { <numberField>: true }, _max?: { <numberField>: true }, where?, orderBy?, take? })Parameters
| Name | Type | Description |
|---|---|---|
_avg / _sum / _min / _max | object | Aggregate selections such as _avg, _sum, _min, and _max, each containing numeric fields set to true. |
where | object | Conditions that determine which records participate in the calculation. |
orderBy | object | Ordering applied to the records considered by the query. |
take | number | Maximum number of records included in the query. |
Returns
A promise resolving to an aggregate result object, with requested aggregate keys such as _avg, _sum, _min, and _max; nullable-field aggregations can contain a number or null.
Key points
- The method belongs to Prisma Client's aggregation features, alongside record counting and distinct-value selection.
- An
_avgselection calculates the average for a chosen numeric field. - Use
whereandorderByalongside aggregate selections when the calculation needs a filtered or ordered input set. - The returned aggregate object exposes the computed value through the selected aggregate key and field.
Common mistakes
- When the selected numeric field is nullable, handle a possible
nullresult instead of assuming a number. - Aggregate numeric operations apply to number fields such as
IntandFloat; do not select unsupported field types.
Example: Aggregate a filtered set of users
const aggregations = await prisma.user.aggregate({
_avg: { age: true },
where: { email: { contains: "prisma.io" } },
orderBy: { age: "asc" },
take: 10,
});
console.log("Average age:", aggregations._avg.age);Computes the average age for the first ten matching users, ordered by age.
When to use it
Aggregate filtered records
Restrict calculations to records matching conditions such as an email-domain filter.
Analyze a limited result set
Calculate a metric from a bounded, ordered subset of records.
Interview questions
QWhat does Prisma Client's aggregate() method do?
aggregate() computes summary values over the records matched by a model query. The result contains the requested aggregate keys, such as _avg, _sum, _min, or _max, with the selected fields beneath them.
Follow-up: How would you restrict the input rows? Add query arguments such as where, orderBy, and take to shape the records included in the aggregation.
QHow do you request an average with aggregate()?
Use _avg, _sum, _min, and _max to select calculations for numeric model fields. For example, { _avg: { age: true } } returns the average age in the _avg.age property.
Follow-up: What should the type handling account for? A nullable aggregated field may produce either a number or null, so callers should handle both cases.
QCan aggregate() be combined with other query constraints?
The query can combine an aggregate selection with filtering, ordering, and a row limit. This lets the calculation operate on a deliberately selected subset rather than every record.
Follow-up: When is groupBy() more appropriate? Use grouping when separate aggregate results are needed for each group instead of one result over the matched rows.
Related
countgroupBydistinctwhereorderBy