Prisma Aggregation API

openapi: 3.2.0
info:
  title: Prisma Client Aggregation API
  description: Auto-generated, type-safe query builder for Node.js and TypeScript that provides programmatic database access. Prisma Client exposes CRUD operations (findUnique, findMany, create, update, delete, upsert), aggregation functions (count, aggregate, groupBy), and advanced query features including filtering, pagination, sorting, relation loading, and transactions. This specification documents the REST-equivalent operations that Prisma Client generates for database models, supporting PostgreSQL, MySQL, SQLite, SQL Server, MongoDB, and CockroachDB.
  version: 1.0.0
  contact:
    name: Prisma Support
    email: support@prisma.io
    url: https://www.prisma.io/support
  license:
    name: Apache-2.0
    url: https://opensource.org/licenses/Apache-2.0
  termsOfService: https://www.prisma.io/terms
servers:
- url: https://localhost:3000/api
  description: Local development server. Prisma Client is typically used as a library, not a REST API. This specification documents the operations available when exposed via a REST layer.
tags:
- name: Aggregation
  description: Count, aggregate, and groupBy operations for analytics
paths:
  /{model}/count:
    get:
      operationId: count
      summary: Prisma Count matching records
      description: Returns the count of records matching the filter criteria. Optionally provides field-level counts showing how many non-null values exist for each specified field.
      tags:
      - Aggregation
      parameters:
      - $ref: '#/components/parameters/ModelName'
      - name: where
        in: query
        description: JSON-encoded filter conditions
        schema:
          type: string
      - name: select
        in: query
        description: JSON-encoded field selection for field-level counts
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved count
          content:
            application/json:
              schema:
                oneOf:
                - type: integer
                  description: Total count when no field selection
                - type: object
                  description: Field-level counts
                  additionalProperties:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /{model}/aggregate:
    get:
      operationId: aggregate
      summary: Prisma Aggregate records
      description: Performs aggregate calculations on matching records. Supports _count, _avg, _sum, _min, and _max operations on numeric fields with optional filtering and ordering.
      tags:
      - Aggregation
      parameters:
      - $ref: '#/components/parameters/ModelName'
      - name: where
        in: query
        description: JSON-encoded filter conditions
        schema:
          type: string
      - name: _count
        in: query
        description: Fields to count or true for total count
        schema:
          type: string
      - name: _avg
        in: query
        description: JSON-encoded specification of fields to average
        schema:
          type: string
      - name: _sum
        in: query
        description: JSON-encoded specification of fields to sum
        schema:
          type: string
      - name: _min
        in: query
        description: JSON-encoded specification of fields to find minimum
        schema:
          type: string
      - name: _max
        in: query
        description: JSON-encoded specification of fields to find maximum
        schema:
          type: string
      responses:
        '200':
          description: Successfully performed aggregation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /{model}/groupBy:
    get:
      operationId: groupBy
      summary: Prisma Group records and aggregate
      description: Groups records by one or more fields and applies aggregate functions within each group. Supports filtering groups with having conditions and ordering groups by field values or aggregate results.
      tags:
      - Aggregation
      parameters:
      - $ref: '#/components/parameters/ModelName'
      - name: by
        in: query
        required: true
        description: JSON-encoded list of fields to group by
        schema:
          type: string
      - name: where
        in: query
        description: JSON-encoded filter conditions applied before grouping
        schema:
          type: string
      - name: having
        in: query
        description: JSON-encoded filter conditions applied after grouping
        schema:
          type: string
      - name: orderBy
        in: query
        description: JSON-encoded sort specification for groups
        schema:
          type: string
      responses:
        '200':
          description: Successfully grouped and aggregated records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupByResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: The request was invalid or malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrismaError'
    InternalServerError:
      description: An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrismaError'
  schemas:
    AggregateResult:
      type: object
      description: Result of an aggregation operation
      properties:
        _count:
          type: object
          description: Count of records or field-level counts
          additionalProperties:
            type: integer
        _avg:
          type: object
          description: Average values for numeric fields
          additionalProperties:
            type: number
        _sum:
          type: object
          description: Sum of numeric field values
          additionalProperties:
            type: number
        _min:
          type: object
          description: Minimum values per field
          additionalProperties: true
        _max:
          type: object
          description: Maximum values per field
          additionalProperties: true
    GroupByResult:
      type: object
      description: A single group result from a groupBy operation
      additionalProperties: true
    PrismaError:
      type: object
      description: Error response from Prisma Client. Error codes follow the Pxxxx format documented at https://www.prisma.io/docs/orm/reference/error-reference
      properties:
        code:
          type: string
          description: Prisma error code (e.g., P2002 for unique constraint violation)
          pattern: ^P[0-9]{4}$
          examples:
          - P2002
          - P2025
        message:
          type: string
          description: Human-readable error description
        meta:
          type: object
          description: Additional error context
          additionalProperties: true
      required:
      - code
      - message
  parameters:
    ModelName:
      name: model
      in: path
      required: true
      description: The Prisma model name (e.g., user, post, comment) as defined in the Prisma schema file
      schema:
        type: string
        examples:
        - user
        - post
externalDocs:
  description: Prisma Client API Reference
  url: https://www.prisma.io/docs/orm/reference/prisma-client-reference