Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Collection Documents

Aggregate Documents

This endpoint performs aggregation operations on documents in a collection.

**Aggregation Framework**: Provides MongoDB-style aggregation operations:
- GROUP BY: Group documents by one or more fields
- Aggregations: COUNT, SUM, AVG, MIN, MAX, COUNT_DISTINCT, etc.
- Date Operations: Truncate or extract date parts for time-series analysis
- Filtering: Pre-aggregation filters (WHERE) and post-aggregation filters (HAVING)
- Sorting & Limiting: Control result ordering and size

**Use Cases**:
- Count documents by feature type or collection
- Calculate daily/monthly processing statistics
- Analyze feature distributions and confidence scores
- Generate reports with multiple metrics

**Note**: This endpoint works with both MongoDB and Qdrant using the same interface.
The system automatically selects the appropriate aggregation provider based on
the underlying metadata store.
post/v1/collections/{collection_identifier}/documents/aggregate

Path parameters

collection_identifierstring required

The unique identifier of the collection.

The unique identifier of the collection.

Request body

filtersobject nullable

Pre-aggregation filters to apply to source data. OPTIONAL, filters data before grouping. Uses same syntax as standard query filters. Applied before GROUP BY.

unwindstring nullable

Array field to unwind before aggregation. OPTIONAL, creates one document per array element. Useful for aggregating over array contents. Example: 'blobs' to analyze each blob separately.

sort_bystring nullable

Field to sort results by. OPTIONAL, can be group_by field or aggregation alias. Defaults to no specific order. Use with sort_direction to control order.

sort_directionstring

Sort direction. OPTIONAL, defaults to 'desc' (descending). Valid values: 'asc' (ascending), 'desc' (descending). Used with sort_by field.

limitinteger nullable

Maximum number of results to return. OPTIONAL, no limit if not specified. Applied after sorting. Useful for 'top N' queries.

Example request

{
  "aggregations": [
    {
      "alias": "total",
      "function": "count"
    }
  ],
  "description": "Count documents by collection",
  "group_by": [
    {
      "alias": "collection",
      "field": "collection_id"
    }
  ],
  "sort_by": "total",
  "sort_direction": "desc"
}

Response

Successful Response

total_groupsinteger required

Total number of unique groups returned.

query_infoobject

Additional information about the query execution. May include collection info, pipeline stages, execution time, etc.

Example response

{
  "query_info": {
    "collection_id": "my-collection",
    "execution_time_ms": 32,
    "pipeline_stages": 4
  },
  "results": [
    {
      "group": {
        "collection": "coll_123"
      },
      "metrics": {
        "total": 523
      }
    },
    {
      "group": {
        "collection": "coll_456"
      },
      "metrics": {
        "total": 187
      }
    }
  ],
  "total_groups": 2
}