# Regroupement et vues enregistrées

Trois façons de tirer davantage d'une seule requête de liste : la synthétiser, réutiliser une configuration stockée, et atteindre les lignes supprimées.

## Regroupement et agrégation

`groupBy` partitionne les enregistrements selon la valeur d'un champ ; `aggregate` calcule des fonctions de synthèse. Combinés, ils produisent des synthèses groupées, comme le montant total par statut.

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

Chaque entrée d'`aggregate` s'écrit **`champ:fonction`** — le champ d'abord, la fonction ensuite. Les fonctions prises en charge sont `sum`, `count`, `avg`, `min` et `max`.

:::callout
**L'ordre est `champ:fonction`, et l'inverser échoue en silence.** `?aggregate=sum:amount` est analysé comme le champ `sum` avec la fonction `amount`, qui n'est pas une fonction connue : l'entrée est donc écartée. Si toutes les entrées sont écartées, le paramètre devient absent et la requête renvoie `200` **sans aucune agrégation** — sans la moindre erreur pour vous le signaler.
:::

Une forme JSON est également acceptée : `?aggregate={"count":true,"sum":["amount"]}`.

Sans `aggregate`, `groupBy` renvoie `groups: [{ name, count }]`. Avec, chaque groupe porte en plus `aggregations`.

## Vues enregistrées

Une vue regroupe un arbre de filtres et un ordre de tri sous un identifiant stable : une requête récurrente tient donc en un paramètre plutôt qu'en une expression réencodée à chaque appel.

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

`?view=` s'apparie sur l'`id` de la vue ou sur son `name`. Une valeur ne correspondant ni à l'un ni à l'autre — ou toute référence de vue sur une table qui n'en déclare aucune — renvoie `404 NOT_FOUND` avec `"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
```

Deux règles régissent l'interaction entre les paramètres explicites et la vue, et elles diffèrent :

| Aspect    | Comportement                                                                          |
| --------- | ------------------------------------------------------------------------------------- |
| `filter`  | **Fusionné** avec le filtre de la vue par `and` — la requête ne peut que restreindre. |
| `sort`    | **Remplace** entièrement le tri de la vue lorsqu'il est présent.                      |
| `fields`  | La configuration de champs de la vue est **ignorée** sur ce point de terminaison.     |
| `groupBy` | Le regroupement de la vue est **ignoré** sur ce point de terminaison.                 |

:::callout
**`?view=` n'applique que les filtres et les tris.** Les `fields` et le `groupBy` d'une vue sont honorés par le point de terminaison dédié `GET /api/tables/:tableId/views/:viewId/records`, pas par la liste des enregistrements avec un paramètre `view`. Si vous avez besoin de la configuration complète de la vue, appelez le point de terminaison de la vue.
:::

## Inclure les enregistrements supprimés

Les lignes supprimées en douceur sont exclues par défaut. Deux paramètres permettent de les atteindre :

| Paramètre              | Résultat                                                |
| ---------------------- | ------------------------------------------------------- |
| `?includeDeleted=true` | Lignes actives **et** supprimées dans un même listing.  |
| `?deleted=true`        | Lignes supprimées uniquement — un listing de corbeille. |

`includeDeleted` est comparé à la chaîne exacte `true` ; toute autre valeur, y compris `only`, est traitée comme « exclure les supprimées ». La corbeille seule s'obtient par `?deleted=true`, ou via le point de terminaison dédié `GET /api/tables/:tableId/trash`.

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

Voir [Suppression douce et restauration](/fr/docs/records-soft-delete) pour le flux de récupération complet.

## Pages associées

- [Filtrage, tri et pagination](/fr/docs/records-filtering-sorting) — le reste de la grammaire des requêtes de liste.
- [Vues de table](/fr/docs/table-views) — déclarer les configurations de filtre/tri/champs enregistrées.
- [Suppression douce et restauration](/fr/docs/records-soft-delete) — corbeille, restauration et cascades.
- [Présentation des enregistrements](/fr/docs/records-overview) — enveloppe de liste et règles transversales.
- [Analytique](/fr/docs/analytics) — des agrégats prêts à l'emploi sur l'usage plutôt que sur les enregistrements.