dsfr-data-join - Composants

Composant de jointure multi-sources. Joint deux jeux de données sur une ou plusieurs clés pivot pour produire un dataset enrichi. Ne fait aucun fetch HTTP : c'est un pur transformateur.

Invisible : Ce composant ne rend rien visuellement. Il attend que ses deux sources aient emis leurs données, les joint en memoire, puis redistribue le resultat via le systeme d'événements.

Voir les exemples live dans le Guide utilisateur

Position dans le pipeline

<dsfr-data-join> se place entre les sources et les composants de transformation/visualisation. Il souscrit a deux <dsfr-data-source> (ou tout composant emettant dsfr-data-loaded), les joint, et emet le resultat sous son propre id.

dsfr-data-source (A)  ──────┐
                             ├──► dsfr-data-join ──► dsfr-data-query ──► dsfr-data-chart
dsfr-data-source (B)  ──────┘

Attributs

Attribut	Type	Format / Valeurs	Description
`id`	String	`id="enriched"`	Identifiant unique (requis). Les composants aval l'utilisent pour s'abonner aux données jointes.
`left`	String	`left="id-source-a"`	ID de la source gauche (source principale)
`right`	String	`right="id-source-b"`	ID de la source droite
`on`	String	Voir formats ci-dessous	Clé(s) de jointure. - Clé commune : on="code_dept" - Clé différente : on="dept_code=code" (gauche=droite) - Multi-clé : on="annee,code_region"
`type`	JoinType	`inner` \| `left` \| `right` \| `full`	Type de jointure : inner \| left \| right \| full
`prefix-left`	String	`prefix-left="pop_"`	Préfixe pour les champs de la source gauche en cas de collision
`prefix-right`	String	`prefix-right="budget_"`	Préfixe pour les champs de la source droite en cas de collision

Format de l'attribut `on`

Clé commune

Quand le champ porte le même nom dans les deux sources :

on="code_dept"

Clé de nommage different

Quand le champ a un nom different dans chaque source (gauche=droite) :

on="dept_code=code"

Multi-clé

Jointure sur plusieurs champs (separes par virgule) :

on="annee,code_region"
on="annee, dept_code=code"

Types de jointure

Type	Description	Equivalent SQL
`inner`	Seuls les enregistrements presents dans les deux sources	`INNER JOIN`
`left`	Tous les enregistrements gauche ; champs droite a `null` si absent	`LEFT JOIN`
`right`	Tous les enregistrements droite ; champs gauche a `null` si absent	`RIGHT JOIN`
`full`	Union de tous les enregistrements ; `null` pour les champs manquants	`FULL OUTER JOIN`

Exemples

Enrichir un dataset avec des données d'une autre source

Jointure gauche entre un dataset de population et un dataset de budgets, sur le code departement. Voir l'exemple live

<dsfr-data-source id="pop" api-type="opendatasoft"
  dataset-id="population-dept" base-url="https://data.economie.gouv.fr">
</dsfr-data-source>

<dsfr-data-source id="budget" api-type="tabular"
  resource="abc123-budget-dept">
</dsfr-data-source>

<dsfr-data-join id="enriched"
  left="pop" right="budget"
  on="code_dept" type="left"
  prefix-right="budget_">
</dsfr-data-join>

<dsfr-data-chart source="enriched" type="bar"
  label-field="nom_dept" value-field="budget_montant">
</dsfr-data-chart>

Jointure avec transformation aval

Apres la jointure, un <dsfr-data-query> peut agréger et trier les données fusionnees.

<dsfr-data-join id="joined"
  left="src1" right="src2"
  on="code_region" type="inner">
</dsfr-data-join>

<dsfr-data-query id="q" source="joined"
  aggregate="population:sum:total,budget:sum:total_budget"
  group-by="nom_region" order-by="total:desc">
</dsfr-data-query>

<dsfr-data-chart source="q" type="bar" horizontal
  label-field="nom_region" value-field="total">
</dsfr-data-chart>

Clés de nommage different

Quand le champ de jointure n'a pas le même nom dans les deux sources :

<dsfr-data-join id="merged"
  left="src-a" right="src-b"
  on="dept_code=code" type="inner">
</dsfr-data-join>

Événements

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

dsfr-data-loaded : Données jointes disponibles
dsfr-data-loading : En attente d'une ou plusieurs sources
dsfr-data-error : Erreur d'une source ou de la jointure

Méthodes publiques

Méthode	Retour	Description
`getData()`	Array	Retourne les données jointes actuelles
`isLoading()`	Boolean	Indique si le composant attend encore des données
`getError()`	Error \| null	Retourne l'erreur eventuelle

Conseils d'utilisation

Collisions de noms : Si un champ existe dans les deux sources avec le même nom (hors clé de jointure), le prefix-right est applique au champ droit (défaut : right_). Definissez prefix-left pour prefixer aussi les champs gauche.

Relations 1-N : Si plusieurs enregistrements de la source droite correspondent a une clé de la source gauche, autant de lignes sont générées (comportement SQL standard).

Recalcul automatique : Si l'une des sources emet de nouvelles données (rechargement, filtre, pagination), la jointure est recalculee automatiquement.

Empiler plutôt que joindre : `dsfr-data-concat`

La jointure juxtapose des colonnes : deux tables, une clé commune. Quand les sources ont les mêmes colonnes et qu'il faut mettre leurs lignes bout à bout (une source par millésime, par région, par série), c'est <dsfr-data-concat>. Il attend que toutes ses sources aient répondu, et origin-field garde la trace de la source de chaque ligne : le résultat se branche tel quel sur le series-field d'un graphique, sans pivot ni jointure.

Attribut	Type	Format / Valeurs	Description
`sources`	String	—	Ids des sources (ou transformateurs) à empiler, séparés par des virgules, dans l'ordre d'empilement. Au moins deux.
`origin-field`	String	—	Colonne ajoutée à chaque ligne, qui dit de quelle source elle vient (facultatif). Sa valeur est l'id de la source, ou le libellé que lui donne `origin-labels`. Un nom de colonne déjà présent dans les données est une erreur de configuration : on écraserait une donnée.
`origin-labels`	String	—	Valeur écrite dans `origin-field` pour chaque source : `"id:libellé \| id2:libellé2"`. Une source non citée garde son id. Un `:` ou un `\|` littéral dans un libellé s'échappe en `%3A` / `%7C`.

<dsfr-data-concat id="ventes" sources="v2023, v2024"
  origin-field="millesime" origin-labels="v2023:2023 | v2024:2024">
</dsfr-data-concat>
<dsfr-data-chart source="ventes" type="line"
  label-field="mois" value-field="montant" series-field="millesime">
</dsfr-data-chart>

Des schémas divergents sont une erreur de configuration qui liste, par source, les colonnes en trop et en moins : rien n'est empilé plutôt qu'un tableau aux colonnes vides. Aucune commande aval (page, filtre, tri) n'est relayée aux sources, faute de savoir à laquelle l'adresser : derrière un empilement, un filtre ou un regroupement s'exécute côté client, et un filtre serveur se pose sur chaque source. Si une seule source est tronquée (max-records), le résultat est marqué tronqué au volet Diagnostic.