Aggregation

List endpoints support aggregation of results. You can use this to request a summarised view of the resources that would usually be returned by a particular request. Currently, the only supported aggregation function is counting.

To request an aggregate result, use the query parameters _count and _groupBy. The values of these parameters should be either:

Dot-separated view paths (eg. friend.name), or
The root path, @id.

You can specify each parameter multiple times to perform any number of aggregations and groupings.

Note

When you supply aggregation parameters, parameters which alter the presentation of the results (eg. _projection, _view) will be ignored. However, parameters which alter the result set, such as filters, will be applied as usual.

Note

If the list endpoint usually applies a default, or “soft” limit to the number of results, it is ignored for aggregate requests. In that case, they may take longer than similar requests to the same endpoint. You can mitigate this by supplying a _limit query parameter.

Note

This feature currently supported for JSON and CSV result formats. Aggregate results in other formats are available but are experimental and should not be relied upon.

Example

To count the total number of records in a list:

/path?_count=@id

JSON response:

items: [{
  "count": 142
}]

To count the number of values for a certain property on each record:

/path?_groupBy=@id&_count=incomingConnection

JSON response:

items: [{
  "@id": "http://training.epimorphics.com/transport/london-underground/station/upney",
  "incomingConnection.count": 2
}, {
  ...
}]