> 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/dataflow/comprendre-les-dataflows/les-bonnes-pratiques.md).

# Les bonnes pratiques

Cette page rassemble les recommandations clés pour créer, maintenir et faire évoluer vos Dataflows en toute sécurité.

Elles couvrent à la fois les aspects techniques (exécution, typage, performance) et collaboratifs (branches, rôles, documentation).

***

## Général

* Créez une **branche par évolution** pour isoler vos tests sans impacter la production.
* Vérifiez toujours le **schéma du dataset de sortie**.
* **Documentez** vos transformations et variables dans leur description pour faciliter la lecture du graphe.
* Gardez une nomenclature cohérente (nommage des transformations, datasets, modules…).

## Typage et schéma

* **Le schéma d’un dataset est commun à toutes les branches.**

  Une fois une colonne créée, son type ne peut plus être modifié sans supprimer la colonne ou le dataset.
* Vérifiez la **compatibilité** des types entre Pandas, Pandas-on-Spark et Polars avant de publier un dataset.
* **Cast explicite recommandé** (par ex. astype("string"), to\_pandas\_on\_spark()…) pour éviter des erreurs implicites.
* Avant chaque merge, comparez le schéma de sortie avec celui de main pour éviter les conflits structurels futurs.

## Performance et exécution

* Privilégiez les **librairies distribuées** : Spark ou Polars plutôt que Pandas pur.
* Évitez les to\_pandas() qui rapatrient les données sur le driver (risque d’OOM).
* Sur Spark, ne recréez **jamais manuellement la SparkSession** : elle est gérée par Cleyrop.
* Utilisez des **clusters adaptés** à la taille des données et testez sur un cluster léger avant production.

## Collaboration et gouvernance

* Définissez **clairement les rôles et responsabilités** : owner de branche, approbateur de fusion, responsable projet.
* Ne fusionnez qu’après **validation fonctionnelle et technique**.
* Utilisez les **variables locales** pour éviter l’utilisation accidentelle de variables de production.
* Activez les **alertes d’échec** sur tous les Dataflows critiques.
* Supprimez régulièrement les **branches obsolètes** et **datasets orphelins**.

## Maintenance et réutilisation

* Utilisez les **modules** pour mutualiser les fonctions ou dictionnaires communs à plusieurs Dataflows.
* Testez systématiquement un module dans un **Dataflow de test** avant déploiement.
* Lors d’un **déploiement de module**, gardez en tête que tous les Dataflows qui l’utilisent seront impactés.
* Nettoyez les **anciens Dataflows** pour garder une vue claire de l’espace projet.

## Visualisation et supervision

* Vous pouvez **prévisualiser les datasets produits** directement depuis le graphe ou la fiche de dernière exécution.
* Chaque prévisualisation affiche le **schéma complet** et les 100 premières lignes du dataset.
* Si la preview ne s’affiche pas, il s’agit souvent d’un problème de schéma ou d'encodage.
* Vérifiez régulièrement les **logs d’exécution** pour identifier les erreurs ou les ralentissements récurrents.