dsfr-data-query - Composants

Composant de transformation de donnees. Filtre, groupe, agrege et trie les donnees 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 donnees et les redistribue aux composants de visualisation via le systeme d'evenements.

Voir les exemples live dans le Guide utilisateur

Fonctionnement

<dsfr-data-query> est un pur transformateur de donnees. Il recoit les donnees 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 donnees 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	(meme 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"`	Agregations. Fonctions : `count` `sum` `avg` `min` `max`. Modes `generic` / `tabular`
`order-by`	String	`"champ:asc"` ou `"champ:desc"`	Tri des resultats. Champs agreges : `"champ__fn:desc"` ou `"alias:desc"`
`limit`	Number	Entier positif. `0` = illimite	Nombre maximum de resultats
`transform`	String	`"results"`, `"data.items"`	Chemin JSONPath pour extraire les donnees de la reponse API
`server-side`	Boolean	Presence = `true`	Active le mode server-side pilotable (une page a la fois, ecoute les commandes des composants en aval)
`page-size`	Number	Entier positif. Defaut : `20`	Taille de page en mode server-side
`refresh`	Number	Entier en secondes. `0` = off	Intervalle de rafraichissement automatique

Syntaxe detaillee des attributs cles

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

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

`order-by`

Format : champ:direction ou champ (defaut : asc).
Pour trier des resultats agreges, utiliser le nom du champ de sortie.

order-by="nom:asc"
order-by="population__sum:desc"       <!-- champ agrege sans alias -->
order-by="total:desc"                 <!-- champ agrege 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 donnees existantes

Recupere les donnees 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 agreger

Regroupe les donnees 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 : requete 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 : requete 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'agregation. 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-cle-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 cles 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 requete 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>

Evenements

Le composant emet les memes evenements que <dsfr-data-source> :

dsfr-data-loaded : Donnees transformees disponibles
dsfr-data-loading : Traitement en cours
dsfr-data-error : Erreur de traitement ou de requete

Methodes publiques

Methode	Retour	Description
`reload()`	void	Force le rechargement / re-traitement des donnees
`getData()`	Array	Retourne les donnees 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 agregations a la source via les attributs de <dsfr-data-source>.

Nommage des champs agreges : En mode generic, les champs agreges 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.