Aggregations
Grouping and summary aggregates over a Dataset's records. These power the
data grid's group-by view; for raw Elasticsearch aggregations use
_search directly.
POST /api/datasets/{id}/_search-aggregates
A search that also computes summary aggregates expressed in fn:field
string form.
Authentication: Required
Request Body:
| Field | Type | Description |
|---|---|---|
aggregations | array | fn:field strings; functions: sum, avg, min, max, value_count, cardinality |
query | object | Elasticsearch query DSL |
_source / sort / from / size / searchType | — | Standard search controls |
report / alias | string | Report context |
Response: the raw search result plus aggRows, label-ready summary rows
for data grids (one per aggregate function).
Search with summary aggregatesPOST /api/datasets/admin:northwind-orders/_search-aggregates
aggregations entries are fn:field strings (sum, avg, min, max, value_count, cardinality). The response is the search result plus aggRows, label-ready summary lines for data grids.
Request body
{
"size": 524288,
"aggregations": [
"sum:orderAmount",
"avg:orderAmount"
]
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_search-aggregates"
}
},
"took": 5,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 2155,
"max_score": null,
"hits": []
},
"aggregations": {
"sum-orderAmount": {
"value": 1354458.5904598236
},
"avg-orderAmount": {
"value": 628.5190674987581
}
},
"aggRows": [
{
"__label": "Total: ",
"__fn": "sum",
"orderAmount": 1354458.5904598236
},
{
"__label": "Average: ",
"__fn": "avg",
"orderAmount": 628.5190674987581
}
]
}
An unknown field in an fn:field expression answers 500 with
"<expr>" is not a valid aggregate expression.
POST /api/datasets/{id}/group
Group records by a field, with bucket totals and optional aggregates. The grid's hierarchical grouping calls this once per level.
Authentication: Required
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
groups | array | Yes | One entry per grouping level: a field name, or { field, interval, sortBy } for date fields |
level | integer | Yes | Which groups entry to group by in this call |
body | object | Yes | Base Elasticsearch search body (its query is combined with the parent filter); {} for none |
parents | array | No | Parent bucket picks when drilling into deeper levels: { group: { field }, value } pairs |
aggs | array | No | fn:field aggregate strings computed per bucket |
timezone | string | No | Timezone for date bucketing (defaults to your session timezone) |
Response: a groups array. Each entry carries the bucket value, its
record total, and one key per requested aggregate ("sum:orderAmount").
Buckets arrive in descending record-count order. Empty values bucket as
__emptystring__ and missing values as __missing__.
Group records (one level)POST /api/datasets/admin:northwind-orders/group
groups entries are a field name or { field, interval, sortBy } for dates; level picks which entry to group by. aggs entries are fn:field strings. parents narrows to a parent bucket when drilling into deeper levels.
Request body
{
"groups": [
"ShipCountry"
],
"level": 0,
"aggs": [
"sum:orderAmount"
],
"body": {}
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/group"
}
},
"groups": [
{
"group": "USA",
"participants": [],
"total": 352,
"value": "USA",
"sum:orderAmount": 263566.9797706604
},
{
"group": "Germany",
"participants": [],
"total": 328,
"value": "Germany",
"sum:orderAmount": 244640.6298866272
},
{
"group": "Brazil",
"participants": [],
"total": 203,
"value": "Brazil",
"sum:orderAmount": 114968.47994995117
},
"… 18 more items (21 total) — omitted from docs"
],
"totals": [
{
"count": 2155,
"sum:orderAmount": 1354458.5904598236
}
]
}
POST /api/datasets/{id}/group-rows
Fetch the underlying rows of one group bucket (drill-down).
Authentication: Required
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
groups | array | Yes | The grouping configuration (as in /group) |
parents | array | Yes | The bucket path to drill into: { group: { field }, value } pairs |
body | object | Yes | Elasticsearch search body for the rows (size, sort, _source, query) |
timezone | string | No | Timezone for date bucket filters |
Response: the raw search result; the group filter is merged into the body's query.
Fetch the rows of a groupPOST /api/datasets/admin:northwind-orders/group-rows
parents entries are { group: { field }, value } pairs; body is an Elasticsearch search body that gets the group filter merged into its query.
Request body
{
"groups": [
"ShipCountry"
],
"parents": [
{
"group": {
"field": "ShipCountry"
},
"value": "Norway"
}
],
"body": {
"size": 524288,
"sort": [
{
"orderAmount": "asc"
}
],
"_source": [
"OrderDate",
"ProductName",
"ShipCountry",
"orderAmount"
]
}
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/group-rows"
}
},
"took": 5,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 16,
"max_score": null,
"hits": [
{
"_index": "docsex.acme.northwind-orders.1700000000000",
"_type": "_doc",
"_id": "doc-1",
"_score": null,
"_source": {
"OrderDate": "2026-01-15T16:20:00.000Z",
"ProductName": "Teatime Chocolate Biscuits",
"ShipCountry": "Norway",
"orderAmount": 18.4
},
"sort": [
18.4
]
},
{
"_index": "docsex.acme.northwind-orders.1700000000000",
"_type": "_doc",
"_id": "doc-2",
"_score": null,
"_source": {
"OrderDate": "2026-01-15T16:20:00.000Z",
"ProductName": "Guaraná Fantástica",
"ShipCountry": "Norway",
"orderAmount": 36
},
"sort": [
36
]
}
]
}
}