Skip to main content
View as Markdown

Filtrage, tri et pagination

GET /api/tables/:tableId/records renvoie une enveloppe paginée et accepte un riche ensemble de paramètres de requête pour paginer, trier, filtrer, sélectionner des champs, regrouper et agréger des enregistrements — afin que vous puissiez façonner de grands ensembles de données sans écrire de points de terminaison personnalisés. Chaque paramètre est facultatif ; combinez-les librement.

GET /api/tables/tasks/records?limit=10&offset=0&sort=priority:desc,name:asc&fields=id,name,status

La réponse est toujours l'enveloppe de liste (jamais un simple tableau) :

{
  "records": [{ "id": "1", "fields": {} }],
  "pagination": { "total": 128, "limit": 10, "offset": 0 }
}

Référence des paramètres de requête

Paramètre Description Exemple
limit Nombre maximal d'enregistrements à renvoyer ?limit=20
offset Nombre d'enregistrements à ignorer ?offset=40
page Numéro de page (indexé à partir de 1) — alternative à offset ?page=3
sort Champ(s) et direction de tri ?sort=name:asc,created_at:desc
order Ordre de tri (asc/desc) pour un tri sur un seul champ ?sort=name&order=desc
fields Noms de champs séparés par des virgules à inclure ?fields=id,name,status
filter Expression de filtre (JSON) ?filter={"status":"active"}
view Appliquer la configuration d'une vue enregistrée ?view=2
groupBy Regrouper les enregistrements par un champ ?groupBy=status
aggregate Fonctions d'agrégation ?aggregate=sum:amount,count:id
q Requête de recherche en texte libre ?q=invoice
format Valeurs de champ raw (défaut) ou display ?format=display
timezone Fuseau horaire IANA pour la mise en forme des dates ?timezone=Europe/Paris
includeDeleted true pour inclure les lignes supprimées de façon réversible ; only pour la corbeille uniquement ?includeDeleted=true

Pagination

Deux styles de pagination équivalents sont pris en charge. Utilisez limit + offset pour un balayage de style curseur, ou limit + page pour des interfaces paginées par numéro. pagination.total est le nombre de toutes les lignes correspondantes (indépendant de la page), de sorte qu'un client peut calculer le nombre de pages comme ceil(total / limit).

GET /api/tables/tasks/records?limit=20&offset=40   # lignes 41–60
GET /api/tables/tasks/records?limit=20&page=3       # lignes 41–60 (indexé à partir de 1)

Tri

Triez par un ou plusieurs champs, chacun avec une direction, en utilisant des segments field:direction séparés par des virgules. Le champ le plus à gauche est la clé de tri primaire.

GET /api/tables/tasks/records?sort=priority:desc,name:asc

Pour un seul champ de tri, vous pouvez plutôt répartir le champ et la direction entre sort et order (?sort=name&order=desc). La forme field:direction est préférée car elle se compose proprement pour les tris à plusieurs clés.

Sélection de champs

Demandez un sous-ensemble de colonnes avec fields. Cela réduit la charge utile de la réponse — utile pour les vues de liste qui n'affichent que quelques colonnes. Les champs que l'appelant ne peut pas lire sont omis, qu'ils figurent ou non dans la liste fields.

GET /api/tables/contacts/records?fields=id,name,status

Filtrage

Passez une expression de filtre JSON dans le paramètre filter. Un objet plat filtre par égalité sur chaque clé :

GET /api/tables/tasks/records?filter={"status":"active"}

Pour des conditions plus riches, les filtres utilisent la même forme structurée que les vues enregistrées — un arbre de groupes and/or dont les feuilles sont des conditions { field, operator, value } :

filters:
  and:
    - field: status
      operator: in
      value: [todo, in_progress]
    - field: priority
      operator: equals
      value: high

Les conditions nomment un field, un operator (par ex. equals, in, greaterThan) et une value. Les opérateurs sont résolus selon le type de champ.

Regroupement et agrégation

groupBy partitionne les enregistrements selon la valeur d'un champ ; aggregate calcule des fonctions de synthèse. Combinez-les pour produire des regroupements agrégés (par ex. le montant total par statut).

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

Chaque entrée aggregate est de la forme function:field — les fonctions prises en charge incluent sum, count, avg, min et max. Lorsqu'elles sont associées à groupBy, les agrégats sont calculés par groupe.

Vues enregistrées

Une vue (?view=2) applique son filtre, son tri et sa configuration de champs stockés côté serveur. Les paramètres de requête explicites se superposent à la vue, permettant à un client d'affiner davantage une vue de base sans la redéfinir.

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

Inclure les enregistrements supprimés

Par défaut, les lignes supprimées de façon réversible sont exclues. Utilisez includeDeleted=true pour fusionner les lignes actives et supprimées, ou includeDeleted=only pour une vue corbeille uniquement. Voir Suppression réversible et restauration pour le flux complet de récupération.

Pages associées