Python SDK
from cognite.client.data_classes.documents import SourceFileProperty
count = client.documents.aggregate_cardinality_properties(SourceFileProperty.metadata)
from cognite.client.data_classes.documents import DocumentProperty
count = client.documents.aggregate_cardinality_values(DocumentProperty.type)
from cognite.client.data_classes import filters
from cognite.client.data_classes.documents import DocumentProperty
is_plain_text = filters.Equals(DocumentProperty.mime_type, "text/plain")
plain_text_author_count = client.documents.aggregate_cardinality_values(DocumentProperty.author, filter=is_plain_text)
from cognite.client.data_classes.documents import DocumentProperty
from cognite.client.data_classes import aggregations
agg = aggregations
is_not_text = agg.Not(agg.Prefix("text"))
type_count_excluded_text = client.documents.aggregate_cardinality_values(DocumentProperty.type, aggregate_filter=is_not_text)
count = client.documents.aggregate_count()
from cognite.client.data_classes import filters
from cognite.client.data_classes.documents import DocumentProperty
is_pdf = filters.Equals(DocumentProperty.mime_type, "application/pdf")
pdf_count = client.documents.aggregate_count(filter=is_pdf)
client.documents.aggregate_count(
filter=filters.InAssetSubtree(
property=DocumentProperty.asset_external_ids,
values=['Plant_1', 'Plant_2'],
)
)
from cognite.client.data_classes.documents import SourceFileProperty
result = client.documents.aggregate_unique_values(SourceFileProperty.metadata)
from cognite.client.data_classes.documents import DocumentProperty
result = client.documents.aggregate_unique_values(DocumentProperty.mime_type)
unique_types = result.unique
from cognite.client.data_classes import filters
from cognite.client.data_classes.documents import DocumentProperty
is_abc = filters.Prefix(DocumentProperty.external_id, "abc")
result = client.documents.aggregate_unique_values(DocumentProperty.language, filter=is_abc)
unique_languages = result.unique
from cognite.client.data_classes.documents import DocumentProperty
from cognite.client.data_classes import aggregations
agg = aggregations
is_not_text = agg.Not(agg.Prefix("text"))
result = client.documents.aggregate_unique_values(DocumentProperty.mime_type, aggregate_filter=is_not_text)
unique_mime_types = result.unique
{
"items": [
{
"count": 10
}
]
}Aggregate documents
> **Required capabilities:** `filesAcl:READ`
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
<table>
<tr>
<th> <div style="width:200px"> Aggregate </div> </th>
<th> <div style="width:350px"> Description </div> </th>
<th> Example </th>
</tr>
<tr>
<td> <code>count</code> </td> <td> Count of documents matching the specified filters and search. </td> <td>
```json
{
"search":{
"query":"example",
},
"aggregate":"count",
}
```
<tr>
<td> <code>cardinalityValues</code> </td> <td> Returns an approximate count of
distinct values for the specified properties. </td> <td>
```json
{
"aggregate":"cardinalityValues",
"properties":[
{
"property":[
"mimeType"
]
}
]
}
```
</td>
</tr>
<tr>
<td> <code>cardinalityProperties</code> </td> <td> Returns an approximate count of
distinct properties for a given property path. Currently only implemented for the
<code>["sourceFile", "metadata"]</code> path.</td> <td>
```json
{
"aggregate":"cardinalityProperties",
"path":["sourceFile", "metadata"]
}
```
</td>
</tr>
</td>
</tr>
<tr>
<td> <code>uniqueValues</code> </td> <td> Returns top unique values for specified properties (up to the
requested limit) and the count of each in the property specified in <code>properties</code>.
The list will have the highest count first. </td> <td>
```json
{
"aggregate":"uniqueValues",
"properties":[
{
"property":[
"author"
]
}
]
}
```
</td>
</tr>
<tr>
<td> <code>uniqueProperties</code> </td> <td> Returns top unique properties values for specified properties (up to the
requested limit) and the count of each in the property specified in <code>properties</code>.
The list will have the highest count first.
Currently, the <code>uniqueProperties</code> aggregate is only supported for property
<code>["sourceFile", "metadata"]</code> .</td> <td>
```json
{
"aggregate":"uniqueProperties",
"properties":[
{
"property":[
"sourceFile",
"metadata"
]
}
]
}
```
</td>
</tr>
</table>
### Aggregate filtering
> Only some aggregate types currently support <code>aggregateFilter</code>
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 <code>filter</code> and <code>aggregateFilter</code> to potentially speed up queries, as the <code>aggregateFilter</code> is essentially a post filter.
#### Filter metadata keys by prefix
Here we only show metadata keys which starts with "car".
```json
{
"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".
```json
{
"aggregate": "uniqueValues",
"properties": [{"property": ["sourceFile", "metadata", "car-codes"]}],
"aggregateFilter": {"prefix": {"value": "ctx"}}
}
```
POST
/
documents
/
aggregate
Python SDK
from cognite.client.data_classes.documents import SourceFileProperty
count = client.documents.aggregate_cardinality_properties(SourceFileProperty.metadata)
from cognite.client.data_classes.documents import DocumentProperty
count = client.documents.aggregate_cardinality_values(DocumentProperty.type)
from cognite.client.data_classes import filters
from cognite.client.data_classes.documents import DocumentProperty
is_plain_text = filters.Equals(DocumentProperty.mime_type, "text/plain")
plain_text_author_count = client.documents.aggregate_cardinality_values(DocumentProperty.author, filter=is_plain_text)
from cognite.client.data_classes.documents import DocumentProperty
from cognite.client.data_classes import aggregations
agg = aggregations
is_not_text = agg.Not(agg.Prefix("text"))
type_count_excluded_text = client.documents.aggregate_cardinality_values(DocumentProperty.type, aggregate_filter=is_not_text)
count = client.documents.aggregate_count()
from cognite.client.data_classes import filters
from cognite.client.data_classes.documents import DocumentProperty
is_pdf = filters.Equals(DocumentProperty.mime_type, "application/pdf")
pdf_count = client.documents.aggregate_count(filter=is_pdf)
client.documents.aggregate_count(
filter=filters.InAssetSubtree(
property=DocumentProperty.asset_external_ids,
values=['Plant_1', 'Plant_2'],
)
)
from cognite.client.data_classes.documents import SourceFileProperty
result = client.documents.aggregate_unique_values(SourceFileProperty.metadata)
from cognite.client.data_classes.documents import DocumentProperty
result = client.documents.aggregate_unique_values(DocumentProperty.mime_type)
unique_types = result.unique
from cognite.client.data_classes import filters
from cognite.client.data_classes.documents import DocumentProperty
is_abc = filters.Prefix(DocumentProperty.external_id, "abc")
result = client.documents.aggregate_unique_values(DocumentProperty.language, filter=is_abc)
unique_languages = result.unique
from cognite.client.data_classes.documents import DocumentProperty
from cognite.client.data_classes import aggregations
agg = aggregations
is_not_text = agg.Not(agg.Prefix("text"))
result = client.documents.aggregate_unique_values(DocumentProperty.mime_type, aggregate_filter=is_not_text)
unique_mime_types = result.unique
{
"items": [
{
"count": 10
}
]
}Authorizations
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
Body
application/json
- Count
- CardinalityValues
- CardinalityProperties
- UniqueValues
- UniqueProperties
- All unique properties
- All unique values
Count of documents.
Show child attributes
Show child attributes
A query that matches items matching boolean combinations of other queries.
It is built using one or more boolean clauses, which can be of types: and, or or not
- and
- or
- not
- equals
- in
- containsAny
- containsAll
- range
- prefix
- search
- exists
- geojsonIntersects
- geojsonDisjoint
- geojsonWithin
- inAssetSubtree
Show child attributes
Show child attributes
Count of documents matching the specified filters and search.
Available options:
count Response
The results of an aggregation request. The object returned depends on the aggregate specified.
- Count
- CardinalityValues
- CardinalityProperties
- UniqueValues
- UniqueProperties
- All unique properties
- All unique values
Response for count aggregate.
Required array length:
1 elementShow child attributes
Show child attributes
Last modified on April 23, 2026
Was this page helpful?
⌘I