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.

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".

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.

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 pour le flux de récupération complet.

Pages associées

• Filtrage, tri et pagination — le reste de la grammaire des requêtes de liste.
• Vues de table — déclarer les configurations de filtre/tri/champs enregistrées.
• Suppression douce et restauration — corbeille, restauration et cascades.
• Présentation des enregistrements — enveloppe de liste et règles transversales.
• Analytique — des agrégats prêts à l'emploi sur l'usage plutôt que sur les enregistrements.