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"}} } ```