# Grouping & Saved Views

Three ways to get more out of one list request: summarise it, reuse a stored configuration, and reach rows that have been deleted.

## Grouping & aggregation

`groupBy` partitions records by a field's value; `aggregate` computes summary functions. Combined, they produce grouped roll-ups such as total amount per status.

```
GET /api/tables/orders/records?groupBy=status
GET /api/tables/orders/records?aggregate=amount:sum,amount:count,quantity:avg
GET /api/tables/orders/records?groupBy=status&aggregate=amount:sum
```

Each `aggregate` entry is **`field:function`** — the field first, the function second. Supported functions are `sum`, `count`, `avg`, `min` and `max`.

:::callout
**The order is `field:function`, and getting it backwards fails silently.** `?aggregate=sum:amount` is parsed as field `sum` with function `amount`, which is not a known function, so the entry is discarded. If every entry is discarded the parameter becomes absent and the request returns `200` with **no aggregation at all** — no error to tell you.
:::

A JSON form is also accepted: `?aggregate={"count":true,"sum":["amount"]}`.

Without `aggregate`, `groupBy` returns `groups: [{ name, count }]`. With it, each group additionally carries `aggregations`.

## Saved views

A view bundles a filter tree and a sort order under a stable id, so a recurring query is one parameter rather than a re-encoded expression on every request.

```
GET /api/tables/tasks/records?view=2
```

`?view=` matches on either the view's `id` or its `name`. A value matching neither — or any view reference against a table declaring no views — returns `404 NOT_FOUND` with `"View '<x>' not found"`.

```yaml
tables:
  - id: 1
    name: tasks
    views:
      - id: 2
        name: Active Tasks
        filters:
          and:
            - field: status
              operator: in
              value: [todo, in_progress]
        sorts:
          - field: priority
            direction: desc
```

Two rules govern how explicit parameters interact with the view, and they differ:

| Aspect    | Behaviour                                                                    |
| --------- | ---------------------------------------------------------------------------- |
| `filter`  | **Merged** with the view's filter using `and` — the request can only narrow. |
| `sort`    | **Replaces** the view's sort entirely when present.                          |
| `fields`  | The view's field configuration is **ignored** on this endpoint.              |
| `groupBy` | The view's grouping is **ignored** on this endpoint.                         |

:::callout
**`?view=` applies filters and sorts only.** A view's `fields` and `groupBy` are honoured by the dedicated `GET /api/tables/:tableId/views/:viewId/records` endpoint, not by the records list with a `view` parameter. If you need the full view configuration applied, call the view endpoint.
:::

## Including deleted records

Soft-deleted rows are excluded by default. Two parameters reach them:

| Parameter              | Result                                      |
| ---------------------- | ------------------------------------------- |
| `?includeDeleted=true` | Active **and** deleted rows in one listing. |
| `?deleted=true`        | Deleted rows only — a trash listing.        |

`includeDeleted` is compared against the exact string `true`; any other value, including `only`, is treated as "exclude deleted". Trash-only is `?deleted=true`, or the dedicated `GET /api/tables/:tableId/trash` endpoint.

```
GET /api/tables/tasks/records?includeDeleted=true
GET /api/tables/tasks/records?deleted=true
```

See [Soft Delete & Restore](/en/docs/records-soft-delete) for the full recovery workflow.

## Related pages

- [Filtering, Sorting & Pagination](/en/docs/records-filtering-sorting) — the rest of the list query grammar.
- [Table Views](/en/docs/table-views) — declaring saved filter/sort/field configurations.
- [Soft Delete & Restore](/en/docs/records-soft-delete) — trash, restore, and cascades.
- [Records Overview](/en/docs/records-overview) — list envelope and cross-cutting rules.
- [Analytics](/en/docs/analytics) — pre-built aggregates over usage rather than records.