> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregate

> Compute aggregated results on documents, such as counts, distinct values, and unique properties.

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

<AccordionGroup>
  <Accordion title="count">
    Count of documents matching the specified filters and search.

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
        "search": {
            "query": "example"
        },
        "aggregate": "count"
    }
    ```
  </Accordion>

  <Accordion title="cardinalityValues">
    Returns an approximate count of distinct values for the specified properties.

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
        "aggregate": "cardinalityValues",
        "properties": [
            {
                "property": ["mimeType"]
            }
        ]
    }
    ```
  </Accordion>

  <Accordion title="cardinalityProperties">
    Returns an approximate count of distinct properties for a given property path. Currently only implemented for the `["sourceFile", "metadata"]` path.

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
        "aggregate": "cardinalityProperties",
        "path": ["sourceFile", "metadata"]
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
        "aggregate": "uniqueValues",
        "properties": [
            {
                "property": ["author"]
            }
        ]
    }
    ```
  </Accordion>

  <Accordion title="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"]`.

    ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    {
        "aggregate": "uniqueProperties",
        "properties": [
            {
                "property": ["sourceFile", "metadata"]
            }
        ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Aggregate filtering

<Info>
  Only some aggregate types currently support `aggregateFilter`.
</Info>

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.
</Tip>

### Filter metadata keys by prefix

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

```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.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 theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
{
    "aggregate": "uniqueValues",
    "properties": [{"property": ["sourceFile", "metadata", "car-codes"]}],
    "aggregateFilter": {"prefix": {"value": "ctx"}}
}
```