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.

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

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

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

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

Champs multivalués : explode

Une cellule qui contient une liste (["a", "b"], une ChoiceList Grist, un champ découpé par split sur dsfr-data-normalize) n'est pas une modalité. Sans explode, elle est ramenée en chaîne pour former la clé de groupe : "a,b" devient une modalité à part entière, une COMBINAISON comptée pour une valeur — là où dsfr-data-facets éclate le même champ. Deux composants branchés sur le même champ donnaient donc des chiffres différents sans rien signaler (#736). explode aligne le regroupement sur les facettes.

<dsfr-data-query id="par-theme"
  source="src"
  group-by="themes"
  explode="themes"
  aggregate="montant:sum"
  order-by="montant__sum:desc">
</dsfr-data-query>

Une ligne portant N valeurs compte dans N groupes : les agrégats la comptent donc N fois — c'est voulu, et c'est ce que fait déjà la facette. Les éléments vides sont ignorés, et une cellule sans aucune valeur (tableau vide, null, chaîne vide) ne produit aucune ligne : pas de groupe « non renseigné ». Une cellule scalaire est inchangée. Chaque champ listé doit figurer dans group-by, sinon la configuration est refusée et le champ ignoré : éclater un champ hors regroupement dupliquerait les lignes et gonflerait les sommes. L'éclatement force le regroupement côté client — aucune API du pipeline ne sait éclater un champ multivalué : sur une source volumineuse, penser au plafond de lignes rapatriées.

En attente d'un filtre : require-where

Sur une page d'exploration, afficher le jeu entier avant tout choix de l'utilisateur est au mieux inutile, au pire coûteux. require-where met la requête en attente : elle n'émet aucune ligne, publie dsfr-data-idle, et les afficheurs en aval rendent leur idle-message au lieu du jeu complet.

Ce qui compte comme filtre : le where (ou filter) de CETTE requête — sur un query, c'est la surface de filtrage que la page pilote — et toute clause where non vide reçue par commande (facettes, recherche, dsfr-data-context). Tout retirer fait repasser la requête en attente : jamais de requête « tout » implicite. C'est le pendant client de require-where sur <dsfr-data-source>, qui, lui, empêche le fetch.

Operateurs de filtre

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

Exemples

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

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

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

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

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

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

<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

Méthodes publiques

Conseils d'utilisation