Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Bucket Objects

Aggregate Objects

This endpoint performs aggregation operations on objects in a bucket.

**Aggregation Framework**: Provides MongoDB-style aggregation operations:
- GROUP BY: Group objects 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 objects by status or category
- Calculate daily/monthly upload statistics
- Analyze content distribution and trends
- Generate reports with multiple metrics

**Note**: This endpoint works with both MongoDB objects and Qdrant documents
using the same interface. The system automatically selects the appropriate
aggregation provider.
post/v1/buckets/{bucket_identifier}/objects/aggregate

Path parameters

bucket_identifierstring required

The unique identifier of the bucket.

The unique identifier of the bucket.

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 objects by status",
  "group_by": [
    {
      "alias": "status",
      "field": "status"
    }
  ],
  "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 pipeline stages, execution time, etc.

Example response

{
  "query_info": {
    "execution_time_ms": 45,
    "pipeline_stages": 5
  },
  "results": [
    {
      "group": {
        "status": "completed"
      },
      "metrics": {
        "total": 1523
      }
    },
    {
      "group": {
        "status": "pending"
      },
      "metrics": {
        "total": 87
      }
    }
  ],
  "total_groups": 2
}