Skip to main content

Aggregate objects of resource.

GET 
/:api_prefix/:service_name/admin/:resource_name/aggregate

Premium — provided by the paid habarico-enterprise package; a free-only install does not expose this endpoint.

Computes an aggregation over the resource objects matching the optional filter query parameters. Reuses the same filter_queryset / ComplexFilterBackend as the resource list endpoint, so widget filters apply identically.

Optional endpoint. Available only on resources where the admin opts in via ModelAdmin. Resources without the opt-in return HTTP 404 for this path. The availability is signalled in the resource schema via aggregate_enabled: true (see GlobalResourceSchema).

Aggregation target​

  • count – field is ignored.
  • min / max / sum / avg – field is required and must include the chosen function in its aggregations whitelist (see FieldSchema.aggregations).

Grouping via group_by​

group_by is a repeat-style query parameter (?group_by=field1&group_by=field2:trunc:month). Each item has the form <field>[:<bucket_fn>[:<arg>]]:

  • <field> – plain field name. Each field must include exact in its FieldSchema.group_by whitelist.
  • <field>:trunc:<gran> – date / datetime truncation. gran is one of second, minute, hour, day, week, month, quarter, year. Field must include trunc:<gran> in its group_by whitelist. Bucket labels are ISO 8601 timestamps in the active Django timezone (TIME_ZONE setting, optionally overridden per-request via Django's standard timezone middleware / timezone.activate()). Implemented on the backend with Django ORM TruncSecond / TruncMinute / TruncHour / TruncDay / TruncWeek / TruncMonth / TruncQuarter / TruncYear.
  • <field>:width:<n> – numeric fixed-width bucketing into [0, n), [n, 2n), … Bucket labels are the lower bounds. Field must include width in its group_by whitelist.

With no group_by the response contains a single bucket with the scalar value.

Limits and safety​

  • Whitelist via aggregations / group_by on FieldSchema prevents SQL injection and schema leaks. Fields without an entry are rejected with HTTP 422.
  • Hard limit on the number of returned buckets (default 50) – exceeding the limit yields HTTP 422.
  • Row-level permissions are inherited from get_queryset, so aggregates reflect only rows the current user is allowed to see.

Request​

Responses​

Premium — returned only by the paid habarico-enterprise package.

Aggregate result (HTTP 200). One bucket per combination of group_by keys, or a single bucket when no group_by is requested.