> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/v-4.5/projet-data-and-ia/datasets/gerer-les-datasets.md).
# Gérer les Datasets
Un dataset correspond à une table de données structurées que vous pouvez exploiter pour vos analyses, transformations et visualisations.
Cleyrop vous permet de créer des datasets de plusieurs manières : en important des fichiers locaux, en vous connectant à des sources de données externes, ou en exploitant les résultats de vos Dataflows.
Une fois créés, vos datasets peuvent être **rafraîchis** pour maintenir vos données à jour, **publiés au catalogue** pour les partager avec d'autres utilisateurs, ou **exposés via API** pour alimenter vos applications métier.
***
## Créer un Dataset
### Créer un Dataset depuis un import local
Pour créer un Dataset depuis un import local d'un ou plusieurs fichier(s) texte avec séparateur ou Excel :
* Dans le menu Bibliothèque, onglet Datasets
* Cliquez sur le bouton Ajouter depuis une Datasource, choisissez "Import Local", puis :
* soit glisser-déposer vos fichiers dans la zone prévue à cet effet
* soit cliquer sur Parcourir pour sélectionner vos fichiers
Vous pouvez définir les paramètres de collecte :
* **Schéma du dataset** : il sera basé sur le schéma extrait du premier fichier. Si vous avez plusieurs fichiers vous pouvez choisir le fichier sur lequel s'appuyer pour le schéma de référence. Vous pouvez choisir d'ignorer les types, toutes les colonnes seront en string.
{% hint style="warning" %}
**Si vous importez plusieurs fichiers en même temps, la politique de schéma appliquée est la *****fusion de schémas*****. Concrètement :**
* **Correspondance des colonnes existantes :**\
Les colonnes portant le *même nom* que celles du schéma de référence doivent également avoir le *même type* ➝ *Si le type ne correspond pas, le fichier est rejeté.*
* **Colonnes supplémentaires ou manquantes :**\
Des colonnes en plus ou en moins sont autorisées ➝ *Les colonnes manquantes seront simplement renseignées avec des valeurs vides.*
{% endhint %}
* **En-tête** : si votre fichier contient une ligne d'en-tête, cochez cette case pour que les noms de colonnes soient automatiquement détectés
* **Encodage** : l'encodage de votre fichier. Par défaut, l'encodage est UTF-8
* **Ajouter une colonne** : avec le nom du fichier ou avec la date d'import
* Ignorer les **lignes vides**
* Ignorer les types du schema : toutes les colonnes seront au **type string** (configuration utile lorsque la cohérence entre les données et le type reconnu n'est pas assuré)
**Cas fichiers texte avec séparateur :**
* **Séparateur** : le caractère qui sépare les colonnes de votre fichier. - Par défaut, le séparateur est un point virgule.
* **Compression** : si votre fichier est compressé, choisissez le type de compression - Par défaut, le fichier n'est pas compressé
{% hint style="info" %}
Les formats supportés sont : `.csv`, `.txt`, `.tsv`, `.tab`, `.dsv` et `.psv`. Définissez le séparateur correspondant à votre fichier.
{% endhint %}
**Cas fichier excel :**
Vous pouvez à tout moment visualiser sur votre fichier de référence l'impact du choix des paramètres
* **Feuille** : la feuille de votre fichier Excel à importer - Par défaut, la première feuille est sélectionnée
* **Format** : le format de votre fichier Excel - Par défaut, le format est XLSX
* Nombre de lignes ou colonnes à ignorer
Vous pouvez à tout moment visualiser sur votre fichier de référence l'impact du choix des paramètres
Vous pouvez enfin qualifier votre Dataset en renseignant :
* **Nom** : le nom d'affichage
{% hint style="info" %}
L'ID unique du dataset est généré à partir du Nom et ne pourra plus être modifié par la suite
{% endhint %}
* **Description** : donner plus d'informations pour que les autres utilisateurs puissent comprendre le contenu du dataset
* **Responsable** : Data Owner
* **Sensibilité** : sensibilité de votre Dataset entre Interne, Restreinte et Sensible. Les datasets restreints et sensibles sont visibles au catalogue mais soumis à autorisation pour être utilisés
{% hint style="success" %}
Choisir sa sensibilité :
* Les datasets de sensibilité Interne publiés au catalogue sont utilisables par tous les utilisateurs
* Un héritage de la sensibilité est appliqué au maximum de la sensibilité des parents
{% endhint %}
* **Classification** : la classification permet d'identifier le niveau de traitement des données et leurs usage de prédilection : bronze - brutes, silver - traitées ou gold - de référence / prêtes au usages métiers
* **Labels** : vous pouvez choisir un label dans la liste de ceux existant ou en rejouter un en l'écrivant. Vous pouvez gérer les labels en cliquant sur les ... à côté du nom d'un label
\
Cliquez sur `Créer` pour créer votre Dataset.
### Créer un Dataset depuis une Datasource
#### Ajouter une Datasource au projet
Pour pouvoir utiliser une Datasource comme origine d'un dataset au sein d'un projet, il faut préalablement obtenir l'autorisation de pouvoir l'utiliser dans le projet.
* Depuis la bibliothèque, allez dans l'onglet `Datasources`
* Cliquez sur le bouton `Ajouter une Datasource`. Vous pouvez rechercher une Datasource dans la liste en renseignant un ou plusieurs mots-clés dans la barre de recherche ou en filtrant par sensibilité ou type de connecteur
* Cliquez sur `Demander l'accès` puis expliquez votre demande dans le champ `Commentaire` et cliquez sur `Envoyer`.
Une demande d'accès est envoyée aux Platform Managers.
Vous recevrez une notification suite au traitement de la demande pour confirmer ou non, l'accès.
#### Créer le Dataset
Depuis la bibliothèque, allez dans l'onglet `Dataset`
* Choisissez la Datasource dans la liste des Datasources autorisées du projet
* Selon la Datasource choisie, vous devrez définir certains paramètres de collecte
**Depuis une Datasource SQL / Snowflake ...**
* Sélectionnez les tables ou vues
* Vous pouvez prévisualiser les données (une requête select \* ... limit 50 sera envoyé à la datasource
* **Filtrage SQL personnalisé** : à l'étape de Traitement, vous pouvez saisir une requête SQL pour n'importer qu'un sous-ensemble de données. Si le champ est vide, la table entière est importée.
{% hint style="warning" %}
**Règles de syntaxe acceptées** : Seules les requêtes simples sont prises en charge : `SELECT [colonnes] FROM [table] WHERE [condition] GROUP BY [col] ORDER BY [col] LIMIT [n]`. Les jointures et les sous-requêtes ne sont pas autorisées. La table indiquée dans le `FROM` doit correspondre à la table sélectionnée dans le formulaire.
{% endhint %}
**Depuis une Datasource sFTP ou Dépôt**
* Vous devrez définir les règles d'accès aux fichiers : chemin d'accès et règles de sélection sur le nom des fichiers.
* Suivre les mêmes étapes de configuration que : [#creer-un-dataset-depuis-un-import-local](#creer-un-dataset-depuis-un-import-local "mention")
* Lors d’un rafraîchissement du Dataset, ces paramètres seront réutilisés pour accéder aux fichiers
**Depuis une Datasource API**
* À l'étape **Ingestion**, vous pouvez surcharger certains paramètres définis dans la datasource :
* **Fin de l'URL (endpoint)** : précisez ou surchargez l'endpoint à appeler (ex : `/users`, `/posts`)
* **Activer le protocole OData** : à cocher si votre API supporte le protocole OData pour le filtrage natif
* **Paramètres** : ajoutez ou surchargez des paramètres de requête (ex : `limit: 100`)
* **En-têtes** : ajoutez ou surchargez des en-têtes HTTP
* Configurer la réponse JSON : vous pouvez définir comment les données JSON retournées par l'API seront interprétées :
* **Chemin des éléments (JSON Path) :** définit le point d'entrée dans la structure JSON. Il utilise la syntaxe JSON Path :
* `$` : racine de la réponse (par défaut)
* `$[*]` : tous les éléments d'un tableau à la racine
* `$[*].sous_objet` : le sous-objet de chaque élément
* **Récupérer le schéma automatiquement :** cliquez sur **Récupérer le schéma** pour interroger l'API et détecter automatiquement la structure de la réponse. Le panneau Aide JSON Path affiche alors les colonnes disponibles avec leur type :
* `#` : numérique
* `T` : texte
* `{}` : object JSON imbriqué
* **Naviguer dans les objets imbriqués :** lorsque votre réponse JSON contient des objets imbriqués (type `{}`), cliquez sur l'icône à droite de l'objet pour naviguer dans ses sous-champs. Le Chemin des éléments est mis à jour automatiquement.
**Définir les paramètres de Rafraîchissement :**
* **Mode de rafraîchissement** : Ajout des nouvelles données aux données existantes ou Remplacement des données existantes par les nouvelles données
* **Fréquence de rafraîchissement** : pour automatiser selon une récurrence définie
* Si un filtrage SQL personnalisé a été configuré à la création, il est réappliqué à chaque rafraîchissement. La requête SQL utilisée est visible depuis la fiche de Rafraichissement du dataset.
{% hint style="warning" %}
**Lors d'un rafraichissement, la politique de schéma appliquée est la *****fusion de schémas***** :**
* **Correspondance des colonnes existantes :**\
Les colonnes portant le *même nom* que celles du schéma du Dataset doivent également avoir le *même type*. ➝ *Si le type ne correspond pas, le fichier est rejeté.*
* **Colonnes supplémentaires ou manquantes :**\
Des colonnes en plus ou en moins sont autorisées ➝ *Les colonnes manquantes seront simplement renseignées avec des valeurs vides.*
{% endhint %}
Vous pouvez enfin qualifier votre Dataset en renseignant :
* **Nom** : le nom d'affichage
{% hint style="info" %}
L'ID unique du Dataset est généré à partir du Nom et ne pourra plus être modifié par la suite
{% endhint %}
* **Description** : donner plus d'informations pour les autres utilisateurs puissent comprendre le contenu du Dataset
* **Responsable** : Data Owner
* **Classification** : la classification permet d'identifier le niveau de traitement des données et leurs usage de prédilection : bronze - brutes, silver - traitées ou gold - de référence / prêtes au usages métiers
* **Labels** : vous pouvez choisir un label dans la liste de ceux existant ou en rajouter un en l'écrivant. Vous pouvez gérer les labels en cliquant sur les ... à côté du nom d'un label
La **Sensibilité** Interne, Restreinte et Sensible sera héritée de la sensibilité de la Datasource.
#### Créer un Dataset depuis une source Business Central
**Configuration de l'Ingestion**
* **Enable OData protocol** : Cochez cette case pour activer les fonctions de filtrage natives.
* **End of URL (endpoint)** : C'est ici que vous spécifiez la table et la société.
* *Exemple pour les factures :* `/companies(7659dea5-7a01-f111-a202-6045bdfd9645)/salesInvoices`.
**Exemples de tables courantes**
Table
Endpoint API v2.0
Clients
/companies(ID)/customers
Articles
/companies(ID)/items
Journal Comptable
/companies(ID)/generalLedgerEntries
Fournisseurs
/companies(ID)/vendors
**Ressource utile :** [Documentation officielle des API Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/) : Pour trouver tous les noms de tables disponibles.
### **Créer un Dataset depuis un Dataflow**
Un dataset peut être créé directement depuis un Dataflow configuré pour produire des données transformées. Vous pouvez choisir quels datasets de sortie vous souhaitez rendre disponible dans la bibliothèque de votre projet.
**Pour créer un dataset depuis un Dataflow** :
1. [Créez un Dataflow](/docs/v-4.5/projet-data-and-ia/dataflow/creer-un-dataflow.md) et ajoutez une transformation avec un Dataset de Sortie avec un dataset de sortie
2. Configurez votre [Dataset de sortie](/docs/v-4.5/projet-data-and-ia/dataflow/creer-un-dataflow/configurer-un-dataset-de-sortie.md)
3. Exécutez le Dataflow pour générer les premières données
4. Cliquez sur **Référencer** (au dessus du dataset de sortie ou depuis la fiche Détails )pour rendre le dataset de sortie disponible dans la bibliothèque du projet.
5. Après la mise en production de votre Dataflow, le dataset marqué pour référencement apparaît dans votre bibliothèque pour être utilisé dans le projet
Le dataset sera alimenté à chaque exécution du Dataflow. Pour en savoir plus sur l'[exécution et l'automatisation](/docs/v-4.5/projet-data-and-ia/dataflow/executer-deployer-et-automatiser.md) de votre Dataflow.
## Ajouter des descriptions aux colonnes
Chaque colonne d'un dataset peut être documentée avec une description textuelle pour expliquer sa signification métier, sa logique de transformation ou ses contraintes particulières.
{% hint style="info" %}
Pour les responsables du Dataset
{% endhint %}
Pour ajouter ou modifier une description:
1. Accédez à l'onglet **Schéma** de la fiche d'un dataset
2. Cliquez sur le bouton :pen: Editer
3. Cliquez sur la colonne concernée et saisissez votre texte dans le champ **Description**.
Les descriptions sont persistantes et accessibles via l'interface et l'API. La modification d'une description n'impacte ni les données ni les pipelines.
💡 **Bon à savoir** : Pour les datasets issus de Dataflow, les descriptions peuvent être éditées en mode Brouillon. Une fois le Dataflow en production, elles ne peuvent être modifiées que depuis la fiche dataset après le merge en production, et non dans les branches de développement.
## **Rafraîchir un Dataset**
Le rafraîchissement permet de mettre à jour les données d'un dataset.
### **Rafraîchir un dataset issus de sources de données**
{% hint style="success" %}
Le rafraîchissement réapplique automatiquement la **configuration d'import** (transformations, séparateurs...).
{% endhint %}
#### **Rafraîchissement manuel**
1. Ouvrez la fiche du dataset
2. Cliquez sur l'icône :arrows-rotate-reverse: Rafraîchir sur la page d'accueil ou en haut à droite (visible uniquement si vous disposez des droits nécessaires)
3. Le rafraîchissement démarre immédiatement
#### **Rafraîchissement automatique**
Vous pouvez définir une fréquence de rafraîchissement des données à la création ou à la modification d'un dataset en cliquant sur Editer depuis la fiche Dataset (visible uniquement si vous avez les autorisations)
1. Accédez aux paramètres du dataset
2. Editer le dataset
3. Configurez la fréquence souhaitée dans la partie "Récurrence"
### Rafraîchir un dataset issu d'un import local
Vous pouvez ajouter de nouveaux fichiers à un dataset existant en suivant un processus guidé.
**Import multi-fichiers** :
1. Ouvrez la fiche du dataset
2. Cliquez sur :arrows-rotate-reverse: "Rafraîchir" (visible uniquement si vous disposez des droits nécessaires)
3. Choisissez le mode de rafraîchissement pour cet import :
1. **Append** : ajoute les nouvelles lignes aux données existantes
2. **Replace** : remplace intégralement les données du dataset
4. Sélectionnez 1 à n fichiers à importer
{% hint style="info" %}
Les fichiers ajoutés doivent être du même type que l'import initial.
{% endhint %}
**Validation et gestion des écarts** :
Le système effectue automatiquement les vérifications suivantes pour chaque fichier :
* **Compatibilité du schéma** : vérification des types de données. En cas d'incompatibilité, un message explicite indique la colonne et, si possible, les lignes concernées.
* **Écarts de colonnes** : affichage clair des colonnes supplémentaires (présentes dans le fichier mais absentes du dataset) et des colonnes manquantes (attendues par le dataset mais absentes du fichier), avec rappel de la politique de schéma configurée.
**Aperçu de la configuration** :
Avant de valider, vous pouvez consulter :
* Les transformations qui seront appliquées
* Le séparateur utilisé
* La feuille sélectionnée (pour les fichiers Excel)
Une fois validé, le rafraîchissement apparaît dans la liste des rafraîchissements avec :
* L'utilisateur ayant déclenché l'opération
* La liste des fichiers importés
* Les informations détaillées (configuration appliquée, statut, logs)
### Rafraîchir un dataset issu de Dataflow
Pour rafraîchir un dataset créé depuis un Dataflow, vous pouvez, si vous avez les autorisations :
* Exécuter manuellement le Dataflow source
* Définir une récurrence d'exécution
* Configurer un trigger événementiel à l'ajout d'un fichier dans les Données de travail
Pour plus d'informations, consultez la page [Exécuter, déployer et automatiser](/docs/v-4.5/projet-data-and-ia/dataflow/executer-deployer-et-automatiser.md).
## Surveiller les rafraîchissements
Chaque rafraîchissement génère une fiche détaillée accessible depuis la fiche du dataset > Onglet Rafraichissement > Clic sur la ligne du Rafraîchissement.
Vous pourrez y retrouver les informations suivantes :
* Le **Mode de rafraichissement** : Append ou Replace
* Nombre de **lignes** et **colonnes** traitées par étape (ingestion / transformation)
* **Configuration appliquée** : rappel des paramètres utilisés
* **Statut** :
* ✅ **Succès** : toutes les données ont été traitées
* ⚠️ **Attention** :
* au moins un fichier présente un problème, mais certaines données ont été importées
* toutes les données ont déjà été traitées
* ❌ **Échec** : l'import n'a pas pu être réalisé
* **Logs** : détails techniques pour investiguer en cas de problème
* Liste des fichiers traités dans le cas d'un source fichier. En cas de problème sur un fichier, vous verrez apparaître :triangle-exclamation: avec plus d'informations au survol de l'icone :
* Schéma incompatible : le fichier n'a pas été importé
* Fichier déjà traité
En cas de statut **Échec** ou **Attention**, vous pouvez afficher les logs de l'étape d'ingestion pour identifier la cause du problème.
{% hint style="info" %}
Les dates de rafraîchissement incluent désormais l'heure en plus de la date, et sont harmonisées sur tous les types de connecteurs (API, Fichier, SQL).
{% endhint %}
{% hint style="info" %}
**Bon à savoir** : Pour des raisons de performance, seule la première erreur détectée est identifiée et loguée. Le fichier complet n'est pas scanné.
{% endhint %}
### S'abonner aux alertes
1. Depuis la liste des Datasets de votre projet ou du Catalogue
2. Cliquez sur :bell: `S'abonner` et choisir Qualité et/ou Rafraîchissement
Vous recevrez alors une notification in-app et mail à la remonté d'une alerte ou à l'échec d'un rafraîchissement. Vous pouvez retrouver l'ensemble de vos souscriptions dans l'onglet :gear: `Gestion des notifications`.
{% hint style="info" %}
Gestion des notifications
* L'option d'abonnement aux échecs de rafraîchissement est proposée automatiquement à la création d'un Dataset
* L'abonnement aux règles de Qualité n'est proposé que si au moins une règle qualité est définie sur le dataset
* À la création d'une règle de Qualité, une invitation à s'abonner est affichée si vous n'êtes pas encore abonné
* Le propriétaire d'un Dataset peut désactiver son abonnement automatique aux règles Qualité depuis la Gestion des notifications
{% endhint %}
## Ajouter un Dataset à la bibliothèque depuis le catalogue
Pour ajouter un Dataset depuis le catalogue, il faut se rendre dans le menu `Datasets`. Cliquez sur le bouton `Ajouter un Dataset` puis sur `Depuis le catalogue`. Vous pouvez rechercher un Dataset dans le catalogue en renseignant un ou plusieurs mots-clés dans la barre de recherche ou en utilisant les filtres.
* Pour les Datasets de sensibilité **Interne** cliquez sur `Ajouter` pour l'ajouter au projet.
* Pour les Dataset de sensibilité **Sensible** ou **Restreint** cliquez sur `Demander l'accès` pour demander l'accès au Dataset puis expliquez votre demande dans le champ `Commentaire` et cliquez sur `Envoyer`.
Au traitement de votre demande par un platform manager, vous recevrez une notification.
## Exporter un Dataset
Lors de l'export d'un dataset au format CSV, une fenêtre de configuration s'affiche avant le téléchargement. Vous pouvez y choisir le séparateur de colonnes et activer l'encadrement des valeurs texte par des guillemets.
**Options disponibles à l'export**
* **Séparateur** : choisissez le caractère qui séparera les colonnes dans le fichier exporté (virgule par défaut, point-virgule, tabulation, pipe, etc.).
* **Guillemets** : si activé, toutes les valeurs de type texte sont encadrées par des guillemets doubles. Les guillemets présents dans les valeurs sont automatiquement doublés (conformément à la norme RFC 4180).