dsfr-data-query - Composants

Composant de transformation de données. Filtre, groupe, agrège et trie les données recues d'une <dsfr-data-source> avant de les transmettre aux composants de visualisation. Ne fait aucun fetch HTTP : c'est un pur transformateur.

Invisible : Ce composant ne rend rien visuellement. Il transforme les données et les redistribue aux composants de visualisation via le systeme d'événements.

Voir les exemples live dans le Guide utilisateur

Fonctionnement

<dsfr-data-query> est un pur transformateur de données. Il recoit les données d'une <dsfr-data-source> (ou <dsfr-data-normalize>) via l'attribut source et applique des transformations client-side (filter, group-by, aggregate, sort, limit).

Attributs

Attribut	Type	Format / Valeurs	Description
`id`	String	`id="mon-query"`	Identifiant unique (requis). Les composants de visualisation l'utilisent pour s'abonner aux données transformees.
`source`	String	`source="id-source"`	ID de la `<dsfr-data-source>` ou `<dsfr-data-normalize>` a ecouter (requis)
`where`	String	`"champ:op:val, ..."`	Filtres. Plusieurs filtres separes par `,` (logique ET)
`filter`	String	(même format que `where`)	Alias pour `where`
`group-by`	String	`"champ1, champ2"`	Champs de regroupement separes par virgule
`aggregate`	String	`"champ:fn"` ou `"champ:fn:alias"`	Agrégations. Fonctions : `count` `sum` `avg` `min` `max`. Modes `generic` / `tabular`
`order-by`	String	`"champ:asc"` ou `"champ:desc"`	Tri des resultats. Champs agrégés : `"champ__fn:desc"` ou `"alias:desc"`
`limit`	Number	Entier positif. `0` = illimite	Nombre maximum de resultats

Attributs retires (#277, #279) : transform, page-size et refresh se configurent sur <dsfr-data-source> ; server-side est sans objet (le relais de commandes vers la source est toujours actif).

Syntaxe detaillee des attributs clés

`where` / `filter` (modes generic et tabular)

Format : champ:operateur:valeur. Plusieurs filtres separes par , (logique ET).

where="population:gt:5000"
where="population:gt:5000, region:in:IDF|OCC|BRE"
where="email:isnull"                 <!-- pas de valeur pour isnull/isnotnull -->
where="region:in:IDF|OCC|BRE"        <!-- separateur | pour in/notin -->

Les valeurs "true"/"false" sont parsees en booleen, les chaines numériques en nombre.

`aggregate`

Format de base : champ:fonction — le champ de sortie est nomme champ__fonction.
Avec alias : champ:fonction:alias — le champ de sortie porte le nom de l'alias.

aggregate="population:sum"            <!-- sortie : population__sum -->
aggregate="population:sum:total"      <!-- sortie : total -->
aggregate="pop:sum:total, pop:count:nb"  <!-- deux agrégations -->

Fonctions : count (nombre de lignes), sum, avg, min, max.

`order-by`

Format : champ:direction ou champ (défaut : asc).
Pour trier des resultats agrégés, utiliser le nom du champ de sortie.

order-by="nom:asc"
order-by="population__sum:desc"       <!-- champ agrège sans alias -->
order-by="total:desc"                 <!-- champ agrège avec alias -->

Operateurs de filtre

Utilisables dans les attributs where / filter (format "champ:operateur:valeur") :

Operateur	Description	Exemple
`eq`	Egal a	`status:eq:active`
`neq`	Different de	`status:neq:archived`
`gt`	Strictement superieur	`population:gt:5000`
`gte`	Superieur ou egal	`population:gte:5000`
`lt`	Strictement inferieur	`population:lt:1000`
`lte`	Inferieur ou egal	`population:lte:1000`
`contains`	Contient (insensible a la casse)	`nom:contains:paris`
`notcontains`	Ne contient pas	`nom:notcontains:test`
`in`	Dans une liste (separateur `\|`)	`region:in:IDF\|OCC\|BRE`
`notin`	Pas dans une liste	`region:notin:IDF\|OCC`
`isnull`	Est null/undefined	`email:isnull`
`isnotnull`	N'est pas null	`email:isnotnull`

Exemples

Mode generic : filtrer et trier des données existantes

Recupere les données d'une <dsfr-data-source> et les filtre/trie cote client. Ici on filtre les 10 premieres lignes triees par nom. Voir l'exemple live

<dsfr-data-source
  id="raw-data"
  url="https://mon-api.gouv.fr/records"
  transform="results"
></dsfr-data-source>

<dsfr-data-query
  id="filtered-data"
  source="raw-data"
  where="population:gt:5000"
  order-by="nom:asc"
  limit="10"
></dsfr-data-query>

<dsfr-data-chart
  source="filtered-data"
  type="bar"
  label-field="nom"
  value-field="population"
></dsfr-data-chart>

Mode generic : grouper et agréger

Regroupe les données par region et calcule la somme de la population et le nombre d'enregistrements par groupe. Voir l'exemple live

<dsfr-data-source
  id="communes"
  url="https://mon-api.gouv.fr/communes"
  transform="results"
></dsfr-data-source>

<dsfr-data-query
  id="stats-region"
  source="communes"
  group-by="region"
  aggregate="population:sum, population:count"
  order-by="population__sum:desc"
  limit="10"
></dsfr-data-query>

<dsfr-data-chart
  source="stats-region"
  type="bar"
  label-field="region"
  value-field="population__sum"
></dsfr-data-chart>

OpenDataSoft : requête serveur via dsfr-data-source

Utilise <dsfr-data-source> pour interroger une API OpenDataSoft, puis <dsfr-data-query> pour le tri et la limite cote client. Voir l'exemple live

<dsfr-data-source
  id="ods-src"
  api-type="opendatasoft"
  dataset-id="demographyref-communes-2021"
  base-url="https://data.opendatasoft.com"
  select="sum(pop_municipale) as total_pop, nom_reg"
  where="pop_municipale > 5000"
  group-by="nom_reg"
></dsfr-data-source>

<dsfr-data-query
  id="ods-stats"
  source="ods-src"
  order-by="total_pop:desc"
  limit="15"
></dsfr-data-query>

<dsfr-data-chart
  source="ods-stats"
  type="bar"
  label-field="nom_reg"
  value-field="total_pop"
></dsfr-data-chart>

OpenDataSoft : requête data.economie.gouv.fr via dsfr-data-source

Utilise <dsfr-data-source> pour interroger une API OpenDataSoft, puis <dsfr-data-query> pour le groupement et l'agrégation. Voir l'exemple live

<dsfr-data-source
  id="ods-src"
  api-type="opendatasoft"
  dataset-id="rappelconso-v2-gtin-trie"
  base-url="https://data.economie.gouv.fr"
  server-side page-size="100"
></dsfr-data-source>

<dsfr-data-query
  id="ods-stats"
  source="ods-src"
  group-by="categorie_produit"
  aggregate="libelle:count:nombre"
  order-by="nombre:desc"
  limit="8"
></dsfr-data-query>

<dsfr-data-chart
  source="ods-stats"
  type="pie"
  label-field="categorie_produit"
  value-field="nombre"
></dsfr-data-chart>

Combinaison de filtres multiples

Plusieurs filtres peuvent etre combines en les separant par des virgules. Tous les filtres doivent etre satisfaits (logique ET). Voir l'exemple live

<dsfr-data-query
  id="filtered"
  source="raw-data"
  where="population:gte:10000, region:in:IDF|OCC|BRE, status:eq:active"
  order-by="population:desc"
  limit="20"
></dsfr-data-query>

Dataset prive avec headers

L'attribut headers sur <dsfr-data-source> permet de passer des headers HTTP (API key, Bearer token) pour acceder a des datasets prives. Voir l'exemple live

<dsfr-data-source
  id="private-src"
  api-type="opendatasoft"
  dataset-id="mon-dataset-prive"
  base-url="https://mon-instance.opendatasoft.com"
  headers='{"apikey":"ma-clé-api"}'
></dsfr-data-source>

<dsfr-data-query
  id="private-data"
  source="private-src"
  group-by="region"
  aggregate="population:sum:total"
  order-by="total:desc"
></dsfr-data-query>

<dsfr-data-chart
  source="private-data"
  type="bar"
  label-field="region"
  value-field="total"
></dsfr-data-chart>

Securite : les headers sont visibles dans le code source HTML. Ne les utilisez que pour des clés a acces restreint (lecture seule) ou dans des contextes proteges (intranet, applications internes).

Rafraichissement automatique

L'attribut refresh sur <dsfr-data-source> permet de re-executer la requête a intervalles reguliers.

<dsfr-data-source
  id="live-src"
  api-type="opendatasoft"
  dataset-id="mon-dataset"
  base-url="https://data.opendatasoft.com"
  select="count(*) as total"
  refresh="30"
></dsfr-data-source>

<dsfr-data-query
  id="live-stats"
  source="live-src"
></dsfr-data-query>

Événements

Le composant emet les mêmes événements que <dsfr-data-source> :

dsfr-data-loaded : Données transformees disponibles
dsfr-data-loading : Traitement en cours
dsfr-data-error : Erreur de traitement ou de requête

Methodes publiques

Méthode	Retour	Description
`reload()`	void	Force le rechargement / re-traitement des données
`getData()`	Array	Retourne les données transformees actuelles
`isLoading()`	Boolean	Indique si un traitement est en cours
`getError()`	Error \| null	Retourne l'erreur eventuelle

Conseils d'utilisation

Pipeline recommande : Utilisez <dsfr-data-source> pour le fetch HTTP et <dsfr-data-query> pour les transformations client-side (filter, group-by, aggregate, sort). Pour les gros volumes, deleguer les agrégations a la source via les attributs de <dsfr-data-source>.

Nommage des champs agrégés : En mode generic, les champs agrégés sont nommes automatiquement champ__fonction (ex: population__sum, population__count). Vous pouvez definir un alias avec le format "champ:fonction:alias".

Chainabilite : Un <dsfr-data-query> peut servir de source a un autre <dsfr-data-query> en utilisant son id comme attribut source, permettant de construire des pipelines de transformation.