Jeux de données des sources externes

À quoi ça sert

Une source de données externe est une base de données ou une API de votre organisation — distincte de Deltia — que Deltia lit en lecture seule : « Collections des sources de données externes que vos rôles permettent de lire, à adopter puis cartographier pour les graphiques. » Une fois la source déclarée et testée dans l'administration des connecteurs, un administrateur du module KPI la prépare ici : un auteur de widget peut alors composer un graphique sur vos propres données, à côté de celles de Deltia, et l'assistant IA répondre à des questions dessus si votre organisation l'y autorise.

Deux étapes séparent la source d'un premier graphique : adopter une ou plusieurs de ses collections, puis publier le mapping qui déclare ce que chaque champ signifie. Rien n'est interrogeable avant qu'elles soient faites. La page est réservée aux administrateurs du module KPI, depuis l'onglet « Jeux de données » de « Configuration KPI ».

La source elle-même — son adresse, ses identifiants, son test, sa synchronisation — se déclare dans « Connecteurs », « Administration », onglet « Sources de données » : voir Sources de données externes.

Concepts clés

• Source de données — la connexion à une base ou à une API, déclarée dans l'administration des connecteurs. L'onglet « Jeux de données » ne liste que les sources que vos rôles permettent de lire.
• Collection — un ensemble de données que la source contient, tel qu'il existe réellement dans votre base. Une source en liste toutes celles que le compte utilisé peut lire.
• Adoption — le choix de rendre une collection utilisable dans Deltia. Adopter une collection en prélève un échantillon (les premiers et les derniers documents), sans la modifier ni la copier.
• Jeu de données — une collection adoptée. C'est elle qui apparaît ensuite dans le choix de la source d'un graphique, une fois son mapping publié.
• Mapping — la déclaration de ce que signifie chaque champ observé dans l'échantillon : son rôle (dimension, mesure, date ou ignoré), son type, et s'il est exposé.
• Champ exposé — un champ du mapping utilisable dans un graphique et visible par l'assistant IA. Un champ non exposé reste invisible des deux.
• Conversion — la règle qui force un champ dont le type observé varie (texte et nombre, par exemple) vers un type unique, pour pouvoir le sommer ou le filtrer sans ignorer silencieusement les valeurs de l'autre type.
• Mesure nommée — un calcul figé (une somme, une moyenne…) déclaré une fois dans le mapping et que les graphiques réutilisent par son nom.
• Additivité — indique si une mesure nommée peut être sommée sur un regroupement (« Additive »), jamais (« Non additive », un taux par exemple) ou seulement sous condition (« Semi-additive »).
• Grain — une phrase qui décrit ce qu'est une ligne de la collection, par exemple « une ligne par commande ».
• Contexte pour l'assistant — un texte libre qui explique à l'assistant IA comment lire les données (unité d'un montant, valeurs à exclure…).
• Publication — l'action qui rend un mapping utilisable par les graphiques. Republier un mapping s'applique à tous les graphiques qui lisent déjà ce jeu de données.
• Mode expert — un mode du mapping où l'on colle un mapping complet déjà préparé, au lieu de le construire champ par champ.

Comment faire

Ouvrir les jeux de données

1. Dans le menu, ouvrez « KPI », puis « Administration ».
2. Cliquez sur l'onglet « Jeux de données ».

Chaque source lisible avec vos rôles figure sur une ligne, avec son nom et son adresse. « Aucune source de données externe accessible avec vos rôles. » s'affiche si aucune ne l'est ; un administrateur du module Connecteurs y trouve alors « Déclarer une source de données », qui ouvre l'administration des connecteurs. Un administrateur du module KPI qui n'administre pas les connecteurs ne voit que les sources que ses rôles lui ouvrent.

Parcourir les collections d'une source

1. Sur la ligne de la source, cliquez sur « Collections ».

La liste affiche tout ce que la source contient : nombre de documents, nombre de champs, date du dernier échantillonnage, et un badge « Non lisible par ce compte » pour une collection que les identifiants fournis ne peuvent pas lire — elle n'est alors pas proposée à l'adoption. « Voir les champs » déplie, pour une collection déjà échantillonnée, chaque champ avec ses types observés et sa présence. Un champ situé dans un tableau porte l'étiquette « tableau » : une ligne y correspondra par élément, pas par document. Un champ dont le type observé varie porte un avertissement : un total dessus ignorerait silencieusement les valeurs d'un des types.

Adopter une collection

1. Depuis la liste des collections d'une source, cliquez sur « Adopter » sur la ligne voulue.

Le message « Collection adoptée » confirme l'opération, et la collection rejoint vos jeux de données. Adopter ne rend rien interrogeable : il reste à mapper puis publier ses champs.

Mapper les champs d'une collection

1. Depuis la liste des collections adoptées, cliquez sur « Mapper » (ou « À mapper » si rien n'a encore été enregistré).
2. Dans l'onglet « Champs », cherchez un champ avec « Rechercher un champ » ou filtrez la liste : « Tous », « Exposés », « Mesures », « À corriger », « Masqués ». Les champs sont groupés en « Champs principaux », « Ventilation » (les champs situés dans un tableau) et « Peu utiles ».
3. Cliquez sur un champ pour le configurer. Son « Rôle du champ » est unique : « Dimension » (on regroupe ou on filtre dessus), « Mesure » (on la calcule), « Date » (axe temporel) ou « Masqué » (absent des graphiques et invisible pour l'assistant). Un champ masqué garde son rôle.
4. Renseignez au besoin le « Libellé », la « Description » et les « Synonymes » (séparés par des virgules : les mots qu'une personne, ou l'assistant, emploierait pour le désigner).
5. Si le champ mélange plusieurs types, « Les valeurs ne se lisent pas telles quelles » s'affiche avec les types observés : choisissez une conversion dans « Lecture des valeurs » (« Aucune », « En nombre », « En date » ou « En texte »).
6. Dans « Réglages avancés », réglez si besoin le « Type logique », la « Valeur absente » (« Ignorée » ou « Comptée comme zéro ») et « Ce champ contient l'identité du lecteur », qui permet à un graphique de dire « les miens ».
7. Pour traiter plusieurs champs d'un coup, cochez-les (ou « Sélectionner les {n} champs affichés ») puis cliquez sur « Exposer », « En dimension », « En mesure », « En date » ou « Masquer ».
8. Dans l'onglet « Mesures », cliquez sur « Ajouter une mesure » (voir « Définir une mesure nommée » ci-dessous).
9. Dans l'onglet « Contexte et dates », renseignez le « Grain » et, si vous le pouvez, le « Contexte pour l'assistant » — « le réglage le plus rentable de cet écran ». Choisissez un « Champ de date par défaut » (la date qu'utilise une série temporelle quand le graphique n'en choisit pas) et, si la source en porte une, un « Champ de fraîcheur » (la date de dernière mise à jour des lignes), parmi les champs Date.
10. Cliquez sur « Enregistrer » pour garder un brouillon, ou sur « Enregistrer et publier » pour le rendre utilisable immédiatement.

À l'ouverture, un mapping jamais enregistré propose une répartition automatique des champs à partir de l'échantillon : rien n'est retenu tant que vous n'avez pas cliqué sur « Enregistrer ». Un mapping compte au maximum 100 champs exposés ; « {n} champs exposés sur {max} » l'indique en continu. Quitter l'écran avec des modifications non enregistrées demande une confirmation. Un champ masqué mais lu par une mesure nommée est signalé : « Masqué, mais lu par {mesures} : l'enregistrement sera refusé tant qu'il le reste. » L'étiquette « À convertir » repère les champs qu'un enregistrement refuserait, et « Voir les champs à corriger » du bandeau de révocation ouvre la liste filtrée sur eux.

Définir une mesure nommée

1. Dans l'onglet « Mesures », cliquez sur « Ajouter une mesure », ou choisissez une mesure existante. Chaque mesure se lit comme une phrase : « Somme de … », « Moyenne de … », « Nombre de lignes »…
2. Renseignez le « Libellé » et le « Calcul » : agrégation et champ. L'agrégation « Rapport » divise un « Numérateur » par un « Dénominateur », avec une « Échelle » (1000 pour un CPM, 100 pour un pourcentage) : le rapport est recalculé pour chaque regroupement, il n'est jamais sommé ni moyenné. Un rapport dont un opérande n'est pas additif (une fréquence, rapport des impressions à la couverture) est refusé sur une plateforme publicitaire, une base Mongo ou une base Oracle.
3. Sous « Ne compter que… », restreignez au besoin ce que la mesure compte (par exemple en excluant les lignes annulées). Sur un rapport, le filtre s'applique aux deux termes. Seuls les champs exposés sont proposés.
4. Choisissez le « Format d'affichage » : « Nombre », « Pourcentage » ou « Montant », avec la devise et les décimales.
5. Renseignez au besoin la « Description » et le « Contexte pour l'assistant » (par exemple « en centimes », « hors annulations »).
6. Dans « Réglages avancés », réglez l'« Additivité » (« Additive », « Non additive », « Semi-additive ») et le « Nom technique ».

L'additivité d'un rapport est imposée. Les graphiques et l'assistant désignent la mesure par son nom technique : le changer casse ceux qui l'utilisent. Les mesures « Ratio » et « Filtrée » portent une pastille dans la liste.

Publier un mapping

1. Ouvrez le mapping de la collection.
2. Cliquez sur « Enregistrer et publier ».

« Mapping publié » confirme l'opération et affiche « Publié (révision {n}) ». Publier applique le mapping à tous les graphiques qui lisent déjà ce jeu de données ; un mapping jamais publié affiche « Jamais publié » et le jeu de données reste absent du choix des graphiques.

Utiliser le mode expert du mapping

1. Dans l'écran de mapping, ouvrez l'onglet « Mode expert (JSON) ».
2. Collez un mapping déjà préparé, au format JSON attendu.
3. Cliquez sur « Appliquer au brouillon ».
4. Vérifiez le résultat, puis « Enregistrer » ou « Enregistrer et publier ».

Le JSON collé remplace le brouillon ; les champs qu'il ne cite pas restent dans le mapping, non exposés. Un JSON invalide, un format refusé, un champ absent de la collection ou cité deux fois affiche l'erreur correspondante sans rien appliquer.

Consulter les index manquants

1. Depuis le mapping d'une collection, ouvrez « Index de la collection ».

L'écran liste les champs interrogeables que l'index existant ne couvre pas, et pour chacun la commande à transmettre à l'administrateur de votre base, par exemple db.commandes.createIndex({ "client_id": 1 }) ; « Copier la commande » la met dans le presse-papiers. « Tous les champs interrogeables sont couverts par un index. » s'affiche sinon. Deltia ne peut créer aucun index lui-même : la collection appartient au client. Une source API, dont les lignes sont copiées dans Deltia, n'a aucun index à conseiller : l'écran n'affiche rien.

Ré-échantillonner une collection

1. Depuis la liste des collections, cliquez sur « Ré-échantillonner » sur la collection voulue.

« Schéma ré-échantillonné » confirme l'opération. Si la base a changé depuis la dernière publication du mapping — un champ disparu, ou un champ dont le type ne correspond plus à son rôle — le mapping publié est automatiquement révoqué : « Publication révoquée : la source a changé depuis la dernière publication. » Les graphiques qui lisaient ce jeu de données cessent alors de s'afficher, jusqu'à ce que le mapping soit revu et republié.

Retirer une collection

1. Depuis la liste des collections, cliquez sur « Retirer » sur la collection voulue.
2. Confirmez : « Retirer cette collection ? » — « « {nom} » ne sera plus disponible pour les graphiques. La collection elle-même n'est pas touchée. »

Le message « Collection retirée » confirme l'opération. Seule l'adoption dans Deltia disparaît ; les données de votre base ne sont pas modifiées.

Référence

Rôles, types et conversions d'un champ mappé

Les messages d'erreur de déclaration d'une source (hôte refusé, trop de tests, nom déjà pris…) sont décrits dans Sources de données externes.

Messages d'erreur

Limites

Questions fréquentes

L'assistant IA voit-il automatiquement mes sources de données ? Seulement celles dont au moins un jeu de données a un mapping publié, et seulement si votre organisation autorise l'assistant IA sur le module KPI. Une organisation sans source publiée ne se voit jamais proposer cette possibilité.

Puis-je adopter une collection sans la mapper tout de suite ? Oui. L'adoption et le mapping sont deux étapes séparées ; une collection adoptée mais non mappée reste indiquée « À mapper » et n'apparaît pas encore dans le choix des graphiques.

Que se passe-t-il pour les graphiques existants si je modifie un mapping publié ? La nouvelle version s'applique immédiatement à tous les graphiques qui lisent ce jeu de données, y compris ceux créés avant la modification.

La suppression d'une source est-elle réversible ? Non. Les graphiques qui la lisaient cessent de s'afficher ; il faut la redéclarer dans l'administration des connecteurs, puis refaire l'adoption et le mapping de ses collections.

Où déclarer une source, la tester ou la supprimer ? Dans « Connecteurs », « Administration », onglet « Sources de données ». L'ancien onglet « Sources de données » de l'administration KPI s'appelle désormais « Jeux de données » ; un ancien signet vers l'onglet de déclaration ouvre directement la page des connecteurs.

Puis-je adopter une collection d'une source API qui n'a encore rien importé ? Non : « Cette collection ne contient aucun enregistrement à analyser. Synchronisez la source, puis réessayez. »