> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/database/aggregates.md).

# Aggregates

Saved MongoDB aggregation pipelines that your app runs by id.

**Where:** Database → Aggregates · `/projects/<project>/db/aggregates`

An **aggregate** is a saved MongoDB aggregation pipeline for one collection: it groups, counts, joins and reshapes records. Your app runs it by its id (`maggr_…`), so you can change the pipeline in Cloud without a new app release.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-4ab95c9502f43383434127df5141be20a27713ad%2Faggregates-list-1.png?alt=media" alt="Aggregates list with the columns ID, Name and Schema and one row: maggr_5W9f2eefrp0I3UwXVxDP2o, Books per genre, books; Add New at the top right"><figcaption><p>Database → Aggregates.</p></figcaption></figure>

## Columns, search and filters

| Column | What it shows                                                                                                                   |
| ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| ID     | The aggregate id (`maggr_5W9f2eefrp0I3UwXVxDP2o`) — the one your app passes to `executeAggregate`. Click it to open the editor. |
| Name   | The name.                                                                                                                       |
| Schema | The collection the pipeline runs on.                                                                                            |

The list has no search or filters. Reading needs `database:read` on the aggregates of a schema (`database:aggregate:<schemaId>`); creating and changing need `database:create` / `database:update` there.

## What you can do here

* [Create an aggregate](/codemash/cloud/database/aggregates/new.md) — **Add New**: write the pipeline, **TEST** it on live data, save it.
* [Edit an aggregate](/codemash/cloud/database/aggregates/edit.md) — click the id.
* [Delete an aggregate](/codemash/cloud/database/aggregates/delete.md) — **Delete** in the editor.

**Running** an aggregate needs `database:read` on its collection and on every collection the pipeline joins (`$lookup`, `$graphLookup`, `$unionWith`, also nested and inside `$facet`). Pipelines are read-only: `$out`, `$merge`, `$where`, `$function` and `$accumulator` are refused (`CM-ERRORS-DATABASE-031`) when you save and every time it runs. A schema that an aggregate starts from or joins cannot be deleted (`CM-ERRORS-SCHEMA-018`).

## Do it from code

```ts
const { list } = await norbix.hub.database.getDatabaseAggregates({ schemaId: 'sch_7lPCzWonEvTQsheGDCaKq' });
console.log(list.items.map((a) => `${a.viewId} ${a.displayName}`));
```

```sh
norbix hub database aggregates get --schemaId sch_7lPCzWonEvTQsheGDCaKq
```

API: [Get Database Aggregates](/codemash/api-reference/database/aggregates/get-database-aggregates.md) · [Execute Aggregate](/codemash/api-reference/database/collections/execute-aggregate.md)