Aggregate documents

The aggregation API lets you compute aggregated results on documents, such as getting the count of all documents in a project, checking different authors of documents in a project and the count of documents in each of those aggregations. By specifying an additional filter or search, you can aggregate only among documents matching the specified filter or search.

When you don't specify the aggregate field in the request body, the default behavior is to return the count of all matched documents.

Supported aggregates

Aggregate
Description
Example
count Count of documents matching the specified filters and search.
{
    "search":{
        "query":"example",
        
    },
    "aggregate":"count",
    
}
cardinalityValues Returns an approximate count of distinct values for the specified properties.
{
    "aggregate":"cardinalityValues",
    "properties":[
        {
            "property":[
                "mimeType"
            ]
        }
    ]
}
cardinalityProperties Returns an approximate count of distinct properties for a given property path. Currently only implemented for the ["sourceFile", "metadata"] path.
{
    "aggregate":"cardinalityProperties",
    "path":["sourceFile", "metadata"]
}
uniqueValues Returns top unique values for specified properties (up to the requested limit) and the count of each in the property specified in properties. The list will have the highest count first.
{
    "aggregate":"uniqueValues",
    "properties":[
        {
            "property":[
                "author"
            ]
        }
    ]
}
uniqueProperties Returns top unique properties values for specified properties (up to the requested limit) and the count of each in the property specified in properties. The list will have the highest count first.

Currently, the uniqueProperties aggregate is only supported for property ["sourceFile", "metadata"] .

{
    "aggregate":"uniqueProperties",
    "properties":[
        {
            "property":[
                "sourceFile",
                "metadata"
            ]
        }
    ]
}

Aggregate filtering

Only some aggregate types currently support aggregateFilter

Aggregate filtering works directly on the aggregated result. While a normal filter filters relevant documents, aggregate filtering filters the aggregated bucket values. This is useful for e.g. listing metadata keys; while a normal filter will return all metadata keys for related documents, the aggregate filter can be used to reduce the aggregate result even further.

Tip: use both filter and aggregateFilter to potentially speed up queries, as the aggregateFilter is essentially a post filter.

Filter metadata keys by prefix

Here we only show metadata keys which starts with "car".

{
    "aggregate": "uniqueProperties",
    "properties": [{"property": ["sourceFile", "metadata"]}],
    "aggregateFilter": {"prefix": {"value": "car"}}
}

Filter metadata values by prefix

Here we only show metadata values which starts with "ctx", for the given metadata key "car-codes".

{
    "aggregate": "uniqueValues",
    "properties": [{"property": ["sourceFile", "metadata", "car-codes"]}],
    "aggregateFilter": {"prefix": {"value": "ctx"}}
}
Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
One of:

Count of documents.

object
(bool filters (and (object) or or (object) or not (object))) or (leaf filters (equals (object) or in (object) or containsAny (object) or containsAll (object) or range (object) or prefix (object) or search (object) or exists (object) or geojsonIntersects (object) or geojsonDisjoint (object) or geojsonWithin (object) or inAssetSubtree (object))) (DocumentFilter)

A JSON based filtering language. See detailed documentation above.

aggregate
string
Default: "count"

Count of documents matching the specified filters and search.

Value: "count"
Responses
200

The results of an aggregation request. The object returned depends on the aggregate specified.

400

The response for a failed request.

post/documents/aggregate
Request samples
application/json
{
  • "filter": {
    • "equals": {
      }
    },
  • "aggregate": "uniqueValues",
  • "properties": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ]
}