docs: spec parité API decp.info / tabular-api data.gouv.fr (#78)
Opérateurs manquants : differs + agrégation (groupby/count/sum/avg/min/max), renommage du param réservé count -> count_results. or hors périmètre. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Colin Maudry
@@ -0,0 +1,189 @@
|
|||||||
|
# Parité de l'API decp.info avec tabular-api (data.gouv.fr) — opérateurs manquants
|
||||||
|
|
||||||
|
**Date :** 2026-06-22
|
||||||
|
**Périmètre :** `count_results` + `differs` + suite d'agrégation. **Hors périmètre :** le paramètre réservé `or` (itération dédiée ultérieure).
|
||||||
|
|
||||||
|
## Contexte
|
||||||
|
|
||||||
|
L'API `/api/v1/data` de decp.info reproduit le schéma de requête de
|
||||||
|
`tabular-api` (`datagouv/api-tabular`), qui sert la même donnée DECP sur
|
||||||
|
data.gouv.fr. L'objectif est d'atteindre la parité sur les **opérateurs**
|
||||||
|
de filtrage/agrégation, pour qu'une requête écrite pour data.gouv.fr
|
||||||
|
fonctionne à l'identique sur decp.info.
|
||||||
|
|
||||||
|
Source faisant autorité du comportement cible : `api_tabular/core/query.py`
|
||||||
|
du dépôt `datagouv/api-tabular`. Tous les comportements ci-dessous ont été
|
||||||
|
vérifiés en direct contre la ressource DECP
|
||||||
|
`22847056-61df-452d-837d-8b8ceadbfc52`.
|
||||||
|
|
||||||
|
### Écart constaté
|
||||||
|
|
||||||
|
Opérateurs présents chez data.gouv.fr et absents de decp.info :
|
||||||
|
|
||||||
|
| Mot-clé | Nature |
|
||||||
|
| ----------------------------------- | ----------------------------------- |
|
||||||
|
| `differs` | opérateur de filtre |
|
||||||
|
| `groupby` | drapeau d'agrégation (sans valeur) |
|
||||||
|
| `count`, `sum`, `avg`, `min`, `max` | drapeaux d'agrégation (sans valeur) |
|
||||||
|
|
||||||
|
De plus, le paramètre réservé `count=true|false` de decp.info entre en
|
||||||
|
collision avec l'opérateur d'agrégation `count` de data.gouv.fr.
|
||||||
|
|
||||||
|
État courant pertinent :
|
||||||
|
|
||||||
|
- `src/api/filters.py` : `OPERATORS`, `RESERVED_PARAMS`, `build_where()`.
|
||||||
|
- `src/api/routes.py` : route `data()`, doc swagger des paramètres.
|
||||||
|
- `src/db.py` : `query_marches()`, `count_marches()`.
|
||||||
|
|
||||||
|
## Objectifs
|
||||||
|
|
||||||
|
1. Renommer le paramètre réservé `count` → `count_results` (valeurs
|
||||||
|
`true|false`, défaut `true`), libérant `count` comme opérateur.
|
||||||
|
2. Ajouter l'opérateur de filtre `differs`.
|
||||||
|
3. Ajouter les opérateurs d'agrégation `groupby`, `count`, `sum`, `avg`,
|
||||||
|
`min`, `max`, avec la même forme de réponse que data.gouv.fr.
|
||||||
|
|
||||||
|
Non-objectifs : le paramètre `or` (grammaire récursive imbriquée), les
|
||||||
|
opérateurs `groupby`/agrégats appliqués via `or`, toute évolution du
|
||||||
|
benchmark (sera traitée après).
|
||||||
|
|
||||||
|
## Conception
|
||||||
|
|
||||||
|
### 1. Renommage `count` → `count_results`
|
||||||
|
|
||||||
|
- `RESERVED_PARAMS` : `{"page", "page_size", "columns", "count_results"}`.
|
||||||
|
- `routes.data()` : lire `request.args.get("count_results", "true")`.
|
||||||
|
- Doc swagger : remplacer le paramètre `count` par `count_results`, même
|
||||||
|
description (« inclure le total `COUNT(*)` ; `false` pour accélérer »).
|
||||||
|
- Le mot `count` n'est donc plus réservé ; il est interprété comme
|
||||||
|
opérateur d'agrégation (section 3).
|
||||||
|
|
||||||
|
**Rupture de contrat assumée :** un client qui passait `count=false`
|
||||||
|
verra ce paramètre ré-interprété. Acceptable : l'API est privée et
|
||||||
|
l'objectif est explicitement la parité avec data.gouv.fr. À documenter
|
||||||
|
dans le message de commit.
|
||||||
|
|
||||||
|
### 2. Opérateur `differs`
|
||||||
|
|
||||||
|
Sémantique data.gouv.fr : `col__differs=val` → PostgREST `isdistinct`, soit
|
||||||
|
`IS DISTINCT FROM` (≠ null-safe : `NULL differs 44` est vrai).
|
||||||
|
|
||||||
|
- Ajouter `"differs"` à `OPERATORS`.
|
||||||
|
- Dans `build_where()`, après coercition de la valeur :
|
||||||
|
`where_parts.append('"col" IS DISTINCT FROM ?')` ; `params.append(v)`.
|
||||||
|
- DuckDB supporte nativement `IS DISTINCT FROM`.
|
||||||
|
|
||||||
|
### 3. Opérateurs d'agrégation
|
||||||
|
|
||||||
|
#### Forme des requêtes (vérifiée)
|
||||||
|
|
||||||
|
Drapeaux **sans valeur** dans la query string :
|
||||||
|
`?acheteur_departement_code__groupby&uid__count&montant__sum&montant__avg&montant__min&montant__max`
|
||||||
|
|
||||||
|
Une valeur (`__groupby=1`) est un cas d'erreur côté data.gouv.fr ; on
|
||||||
|
n'impose pas cette stricte interdiction mais on accepte la forme sans
|
||||||
|
valeur (Werkzeug fournit alors la valeur `""`).
|
||||||
|
|
||||||
|
Opérateurs : `groupby`, `count`, `sum`, `avg`, `min`, `max`.
|
||||||
|
|
||||||
|
#### Forme de la réponse (vérifiée)
|
||||||
|
|
||||||
|
```
|
||||||
|
SELECT <cols groupby>, FN("<col>") AS "<col>__<op>", ...
|
||||||
|
FROM decp
|
||||||
|
WHERE <filtres>
|
||||||
|
GROUP BY <cols groupby>
|
||||||
|
LIMIT <page_size> OFFSET <offset>
|
||||||
|
```
|
||||||
|
|
||||||
|
- Colonnes de sortie : la colonne `groupby` garde son nom ; chaque agrégat
|
||||||
|
est nommé `"<colonne>__<opérateur>"` (ex. `uid__count`, `montant__sum`).
|
||||||
|
- `meta` : `{"page", "page_size"}` **sans `total`** (data.gouv.fr n'en
|
||||||
|
renvoie pas en mode agrégation). `count_results` est ignoré dans ce mode.
|
||||||
|
- Pas de tri par défaut.
|
||||||
|
- Les filtres `WHERE` (y compris `differs`) restent appliqués.
|
||||||
|
|
||||||
|
#### Contraintes répliquées
|
||||||
|
|
||||||
|
- `columns` + agrégation → erreur 400 (`columns ne peut pas être combiné avec des agrégateurs`). Vérifié identique chez data.gouv.fr.
|
||||||
|
- Un agrégat (`count`/`sum`/…) sans `groupby` est autorisé (agrégat global,
|
||||||
|
une ligne).
|
||||||
|
|
||||||
|
#### Architecture
|
||||||
|
|
||||||
|
Nouvelle fonction de parsing dans `src/api/filters.py` :
|
||||||
|
|
||||||
|
```
|
||||||
|
parse_aggregators(args, schema) -> AggregationSpec | None
|
||||||
|
```
|
||||||
|
|
||||||
|
- Retourne `None` si aucun opérateur d'agrégation présent → la route suit
|
||||||
|
le chemin existant.
|
||||||
|
- Sinon retourne les colonnes `groupby` et la liste des agrégats
|
||||||
|
`(fonction_sql, colonne, alias)`.
|
||||||
|
- Valide que chaque colonne existe dans le schéma ; opérateur inconnu →
|
||||||
|
`FilterError`.
|
||||||
|
|
||||||
|
`build_where()` est inchangé pour WHERE/ORDER ; il continue d'ignorer les
|
||||||
|
clés réservées et **doit ignorer les drapeaux d'agrégation** (ne pas les
|
||||||
|
traiter comme des filtres). Comme les drapeaux d'agrégation arrivent comme
|
||||||
|
`(col__op, "")`, et que `op` ∈ agrégateurs, `build_where` les saute.
|
||||||
|
|
||||||
|
Nouvelle fonction dans `src/db.py` :
|
||||||
|
|
||||||
|
```
|
||||||
|
aggregate_marches(select_sql, where_sql, params, group_by, limit, offset) -> pl.DataFrame
|
||||||
|
```
|
||||||
|
|
||||||
|
- `select_sql` et `group_by` sont des fragments SQL construits depuis des
|
||||||
|
noms de colonnes validés contre le schéma (jamais de valeur utilisateur
|
||||||
|
libre) ; les valeurs de filtre passent par le binding `?`.
|
||||||
|
|
||||||
|
Orchestration dans `routes.data()` :
|
||||||
|
|
||||||
|
```
|
||||||
|
agg = parse_aggregators(args, schema)
|
||||||
|
where_sql, params, order_sql = build_where(args, schema) # filtres seuls
|
||||||
|
if agg:
|
||||||
|
if columns: -> abort(400)
|
||||||
|
df = aggregate_marches(agg.select_sql, where_sql, params, agg.group_by, page_size, offset)
|
||||||
|
meta = {"page", "page_size"} # pas de total
|
||||||
|
else:
|
||||||
|
<chemin existant>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sécurité SQL
|
||||||
|
|
||||||
|
Les noms de colonnes proviennent du schéma DuckDB validé (`col in schema`),
|
||||||
|
jamais interpolés depuis une valeur arbitraire ; les fonctions d'agrégation
|
||||||
|
sont une liste blanche fixe (`COUNT/SUM/AVG/MIN/MAX`). Les valeurs de
|
||||||
|
filtre restent liées par paramètres `?`. Aucun chemin n'interpole de valeur
|
||||||
|
utilisateur dans le SQL.
|
||||||
|
|
||||||
|
## Tests
|
||||||
|
|
||||||
|
Tests existants à adapter (renommage `count` → `count_results`).
|
||||||
|
|
||||||
|
Nouveaux tests (`tests/` API) :
|
||||||
|
|
||||||
|
- `differs` : exclut les lignes égales, inclut les NULL.
|
||||||
|
- agrégation `groupby` + `count` : nombre de groupes, noms de colonnes
|
||||||
|
`col__count`.
|
||||||
|
- agrégation multiple `groupby`+`count`+`sum`+`avg`+`min`+`max` : alias et
|
||||||
|
types corrects, `meta` sans `total`.
|
||||||
|
- agrégat sans `groupby` : une ligne.
|
||||||
|
- `groupby` + filtre `WHERE` : le filtre s'applique avant l'agrégation.
|
||||||
|
- `columns` + agrégation : 400.
|
||||||
|
- `count_results=false` : réponse sans `total` (chemin non-agrégé).
|
||||||
|
- non-régression : opérateurs existants inchangés.
|
||||||
|
|
||||||
|
Comparaison de référence : pour quelques requêtes, les valeurs agrégées
|
||||||
|
doivent correspondre à celles renvoyées par data.gouv.fr sur la même
|
||||||
|
ressource (aux différences de fraîcheur de données près).
|
||||||
|
|
||||||
|
## Gestion des erreurs
|
||||||
|
|
||||||
|
- Opérateur inconnu, colonne inconnue → `FilterError` → 400 (existant).
|
||||||
|
- `columns` + agrégation → 400 avec message explicite.
|
||||||
|
- Valeur non coercible pour `differs` → `FilterError` (existant via
|
||||||
|
`_coerce`).
|
||||||
Reference in New Issue
Block a user