Parcourir les aide-mémoire · Python
Lire et écrire des fichiers CSV, Parquet et JSON
Lisez et écrivez des fichiers CSV, Parquet et JSON avec pandas en maîtrisant le schéma, les dates, les valeurs nulles, la compression, l’encodage et un comportement des fichiers sûr en production.
Sur cette page
- Problème
- Réponse rapide
- Code / commandes
- 1. Lire un CSV avec des types et des dates explicites
- 2. Ne lire que les colonnes CSV nécessaires
- 3. Maîtriser la gestion des valeurs nulles dans un CSV
- 4. Conserver les chaînes vides lorsque c’est nécessaire
- 5. Lire un CSV avec un encodage explicite
- 6. Lire un gros CSV par morceaux
- 7. Écrire un CSV sans l’index du DataFrame
- 8. Écrire un CSV encodé en UTF-8
- 9. Écrire une sélection de colonnes CSV dans un ordre maîtrisé
- 10. Formater les horodatages lors de l’écriture d’un CSV
- 11. Lire un fichier Parquet
- 12. Lire une sélection de colonnes Parquet
- 13. Lire un Parquet partitionné avec des filtres lorsque c’est pris en charge
- 14. Écrire un fichier Parquet
- 15. Écrire un Parquet compressé
- 16. Écrire un jeu de données Parquet partitionné
- 17. Lire une structure JSON standard (tableau ou objet)
- 18. Lire du JSON Lines
- 19. Écrire des enregistrements JSON
- 20. Écrire du JSON Lines
- 21. Maîtriser le format des horodatages JSON
- 22. Lire du JSON issu d’une structure imbriquée de type API
- 23. Normaliser des tableaux imbriqués avec des métadonnées
- 24. Inspecter le schéma juste après la lecture
- 25. Valider les colonnes clés après l’ingestion
- 26. Valider le nombre de lignes après un aller-retour d’écriture
- 27. Écrire dans un chemin temporaire avant de remplacer un fichier de production
- 28. Éviter d’ajouter à un CSV à l’aveugle
- 29. N’ajouter l’en-tête qu’à la création d’un CSV
- 30. Comparer le choix du format de fichier selon la charge de travail
- Interpréter le résultat
- Points à vérifier
- Les identifiants perdent leurs zéros initiaux
- La colonne de dates reste du texte
- Un aller-retour CSV modifie les dtypes
- Le fichier Parquet est bien plus petit que le CSV
- La lecture Parquet reste lente
- Le JSON produit des colonnes ou un nombre de lignes inattendus
- Le nombre de valeurs nulles change après la lecture d’un CSV
- Notes de production
- CSV n’a pas de véritable schéma
- Parquet est généralement plus adapté aux analyses répétées
- Les dépendances Parquet comptent
- JSON n’est pas tabulaire par nature
- Les écritures de fichiers ne sont pas des transactions
- Le stockage objet ne se comporte pas comme un disque local
- Éviter les nombreux petits fichiers Parquet
- La compression échange du CPU contre du stockage et des E/S
- Erreurs fréquentes
- 1. Laisser pandas inférer le type des identifiants
- 2. Écrire l’index du DataFrame par accident
- 3. Considérer que CSV conserve le schéma
- 4. Raisonner façon errors="ignore" face à des fichiers défectueux
- 5. Supposer qu’en JSON un objet correspond à une ligne
- 6. Ajouter à un CSV depuis plusieurs processus
- 7. Partitionner un Parquet sur des colonnes à forte cardinalité
- 8. Écrire directement par-dessus un fichier de production
- 9. Supposer que le filtrage des prédicats Parquet à la source a toujours lieu
- Étape suivante
- Pour aller plus loin
Problème
Vous devez charger ou exporter des données avec pandas et souhaitez un comportement prévisible avec CSV, Parquet et JSON.
La difficulté n’est pas d’appeler read_csv() ou to_parquet().
Les problèmes en production viennent généralement :
- d’une mauvaise inférence des types
- de différences dans l’analyse des dates
- de zéros initiaux perdus
- de problèmes d’encodage
- d’incohérences dans les valeurs nulles
- de fichiers d’une taille inattendue
- d’une confusion entre JSON orienté lignes et JSON Lines
- de dérives de schéma
- d’un comportement d’écrasement dangereux
- de fichiers CSV qui semblent corrects mais changent de sens une fois rouverts
L’objectif est de choisir le bon format et de rendre explicite le comportement d’ingestion et d’écriture.
Réponse rapide
Utilisez CSV lorsque l’interopérabilité compte avant tout :
import pandas as pd
df = pd.read_csv(
"orders.csv",
dtype={"customer_id": "string"},
parse_dates=["order_time"],
)
Utilisez Parquet lorsque vous voulez un stockage analytique typé et en colonnes :
df = pd.read_parquet(
"orders.parquet",
columns=["order_id", "customer_id", "amount", "order_time"],
)
Écrivez en Parquet pour une réutilisation analytique efficace :
df.to_parquet(
"orders.parquet",
index=False,
compression="snappy",
)
Utilisez JSON Lines pour des enregistrements de type flux ou événements :
df.to_json(
"events.jsonl",
orient="records",
lines=True,
date_format="iso",
)
Choisissez le format en fonction du prochain consommateur, pas par habitude.
Code / commandes
1. Lire un CSV avec des types et des dates explicites
import pandas as pd
df = pd.read_csv(
"orders.csv",
dtype={
"order_id": "string",
"customer_id": "string",
"country": "string",
},
parse_dates=["order_time"],
)
Utilisez un dtype= explicite pour les identifiants qui ne doivent pas être interprétés comme des nombres.
Cela évite que des valeurs telles que :
000123
deviennent :
123
2. Ne lire que les colonnes CSV nécessaires
df = pd.read_csv(
"orders.csv",
usecols=[
"order_id",
"customer_id",
"amount",
"order_time",
],
parse_dates=["order_time"],
)
Cela réduit :
- l’utilisation de la mémoire
- le travail d’analyse
- la dépendance accidentelle à des colonnes sans intérêt
Utilisez usecols= lorsque la source est plus large que ce dont le traitement a besoin.
3. Maîtriser la gestion des valeurs nulles dans un CSV
Par défaut, pandas reconnaît plusieurs valeurs courantes assimilées à des valeurs nulles.
Vous pouvez ajouter des valeurs propres à la source :
df = pd.read_csv(
"orders.csv",
na_values=[
"",
"NULL",
"N/A",
"-9999",
],
)
Ne classez des valeurs sources comme manquantes que si vous connaissez leur signification.
Si un "NULL" littéral est une valeur métier valide, ne le convertissez pas automatiquement.
4. Conserver les chaînes vides lorsque c’est nécessaire
Si les chaînes vides doivent rester distinctes des valeurs manquantes :
df = pd.read_csv(
"orders.csv",
keep_default_na=False,
)
Cela modifie le comportement par défaut de détection des valeurs nulles.
Ne l’utilisez que lorsque la sémantique de la source exige cette distinction.
5. Lire un CSV avec un encodage explicite
df = pd.read_csv(
"customers.csv",
encoding="utf-8",
)
Si la source utilise un autre encodage connu :
df = pd.read_csv(
"legacy_customers.csv",
encoding="cp1252",
)
Ne devinez pas les encodages en silence dans un pipeline de production.
6. Lire un gros CSV par morceaux
for chunk in pd.read_csv(
"large_orders.csv",
chunksize=100_000,
):
process(chunk)
Utilisez la lecture par morceaux lorsque le CSV complet ne tient pas confortablement en mémoire.
N’oubliez pas qu’un traitement morceau par morceau peut modifier la conception de l’algorithme.
Par exemple, une déduplication globale ou un classement global nécessite de conserver un état d’un morceau à l’autre.
7. Écrire un CSV sans l’index du DataFrame
df.to_csv(
"orders.csv",
index=False,
)
Cela évite de créer involontairement une colonne telle que :
Unnamed: 0
lorsque le fichier est relu plus tard.
8. Écrire un CSV encodé en UTF-8
df.to_csv(
"orders.csv",
index=False,
encoding="utf-8",
)
Pour les flux de travail orientés Excel qui ont besoin d’un BOM UTF-8 :
df.to_csv(
"orders.csv",
index=False,
encoding="utf-8-sig",
)
N’utilisez utf-8-sig que lorsque l’outil en aval en tire profit.
9. Écrire une sélection de colonnes CSV dans un ordre maîtrisé
df.to_csv(
"orders.csv",
columns=[
"order_id",
"customer_id",
"amount",
"order_time",
],
index=False,
)
Le schéma d’export devient ainsi délibéré.
10. Formater les horodatages lors de l’écriture d’un CSV
df.to_csv(
"orders.csv",
index=False,
date_format="%Y-%m-%dT%H:%M:%S",
)
Faites attention aux horodatages avec fuseau horaire.
Une chaîne formatée peut perdre l’information de fuseau horaire si le format ne l’inclut pas.
Si le consommateur a besoin des décalages horaires, préférez une représentation ISO qui les conserve.
11. Lire un fichier Parquet
df = pd.read_parquet(
"orders.parquet",
)
Parquet conserve les informations de schéma mieux que CSV.
Les types couramment conservés comprennent :
- les entiers
- les nombres à virgule flottante
- les booléens
- les chaînes
- les horodatages
Le comportement exact dépend du moteur Parquet et du schéma sous-jacent.
12. Lire une sélection de colonnes Parquet
df = pd.read_parquet(
"orders.parquet",
columns=[
"order_id",
"customer_id",
"amount",
"order_time",
],
)
C’est l’un des principaux avantages de Parquet.
L’élagage des colonnes peut réduire considérablement les E/S lorsque vous n’avez besoin que d’une partie d’un jeu de données très large.
13. Lire un Parquet partitionné avec des filtres lorsque c’est pris en charge
df = pd.read_parquet(
"orders_dataset/",
filters=[
("country", "==", "US"),
("year", "==", 2026),
],
)
Le filtrage à la source (filter pushdown) dépend :
- de l’organisation du stockage
- des métadonnées Parquet
- de la prise en charge par le moteur
- de l’expression de filtre
Ne supposez pas que chaque filtre évite de lire tous les fichiers.
14. Écrire un fichier Parquet
df.to_parquet(
"orders.parquet",
index=False,
)
Pour des données analytiques destinées à être réutilisées, Parquet est généralement un meilleur choix par défaut que CSV.
15. Écrire un Parquet compressé
df.to_parquet(
"orders.parquet",
index=False,
compression="snappy",
)
Les autres options de compression prises en charge dépendent du moteur Parquet installé.
Les choix courants comprennent :
snappygzipbrotlizstd
Choisissez en fonction de la compatibilité, du taux de compression et du coût CPU.
Ne supposez pas que la compression la plus forte est la meilleure pour chaque charge de travail.
16. Écrire un jeu de données Parquet partitionné
df.to_parquet(
"orders_dataset/",
index=False,
partition_cols=[
"year",
"month",
],
)
Utilisez le partitionnement lorsque les lecteurs en aval filtrent fréquemment sur ces colonnes.
Évitez les colonnes de partition à très forte cardinalité.
Les mauvais exemples de partitionnement comprennent souvent :
- l’identifiant client
- l’identifiant de transaction
- l’horodatage exact
Ils peuvent créer trop de petits fichiers ou répertoires.
17. Lire une structure JSON standard (tableau ou objet)
df = pd.read_json(
"records.json",
)
Ne l’utilisez que lorsque la structure JSON correspond à ce qu’attend read_json().
Inspectez un JSON que vous ne connaissez pas avant de supposer qu’il se traduit directement en lignes.
18. Lire du JSON Lines
JSON Lines contient un objet JSON par ligne.
df = pd.read_json(
"events.jsonl",
lines=True,
)
Ce format est courant pour :
- les journaux d’événements
- les exports en flux
- les API
- les pipelines de données en mode ajout
19. Écrire des enregistrements JSON
df.to_json(
"records.json",
orient="records",
date_format="iso",
)
Sur le plan conceptuel :
[
{"order_id":"A1","amount":10.5},
{"order_id":"A2","amount":20.0}
]
Utilisez orient="records" lorsque les systèmes en aval attendent une liste d’objets représentant des lignes.
20. Écrire du JSON Lines
df.to_json(
"events.jsonl",
orient="records",
lines=True,
date_format="iso",
)
Cela produit un enregistrement par ligne.
C’est généralement plus facile à diffuser en flux et à traiter par ajout qu’un seul grand tableau JSON.
21. Maîtriser le format des horodatages JSON
Préférez les horodatages ISO pour des échanges lisibles par un humain :
df.to_json(
"events.json",
orient="records",
date_format="iso",
)
Sans contrôle explicite, les choix de sérialisation JSON peuvent différer de ce qu’attendent les consommateurs en aval.
Vérifiez :
- la représentation du fuseau horaire
- la précision
- la sémantique date seule ou horodatage
22. Lire du JSON issu d’une structure imbriquée de type API
Le JSON imbriqué nécessite souvent une normalisation.
Exemple :
payload = {
"results": [
{
"id": 1,
"customer": {
"name": "Ana",
"country": "US",
},
}
]
}
Normalisez :
df = pd.json_normalize(
payload["results"]
)
Les colonnes obtenues peuvent comprendre :
id
customer.name
customer.country
Utilisez json_normalize() lorsque des objets imbriqués font partie de la structure de l’enregistrement.
23. Normaliser des tableaux imbriqués avec des métadonnées
payload = {
"orders": [
{
"order_id": "A1",
"items": [
{"sku": "X", "qty": 2},
{"sku": "Y", "qty": 1},
],
}
]
}
Normalisez les lignes d’articles :
items = pd.json_normalize(
payload["orders"],
record_path="items",
meta=["order_id"],
)
Comprenez la granularité obtenue :
une ligne par article
et non :
une ligne par commande
L’expansion des structures imbriquées peut modifier considérablement le nombre de lignes.
24. Inspecter le schéma juste après la lecture
print(df.shape)
print(df.dtypes)
df.info()
Vérifiez ensuite :
print(df.head())
print(df.isna().sum().sort_values(ascending=False).head(20))
Un fichier chargé sans erreur n’est pas forcément un fichier chargé correctement.
25. Valider les colonnes clés après l’ingestion
required = [
"order_id",
"customer_id",
]
missing_required = df[required].isna().sum()
print(missing_required)
Vérifiez l’unicité lorsque c’est pertinent :
assert not df["order_id"].duplicated().any()
N’imposez l’unicité que lorsque la granularité métier exige que la clé soit unique.
26. Valider le nombre de lignes après un aller-retour d’écriture
Exemple :
df.to_parquet(
"orders.parquet",
index=False,
)
check = pd.read_parquet(
"orders.parquet",
)
assert len(check) == len(df)
Pour les pipelines critiques, validez aussi :
- le nombre de clés
- le nombre de valeurs nulles
- les dtypes
- les agrégats importants
Le nombre de lignes seul ne suffit pas.
27. Écrire dans un chemin temporaire avant de remplacer un fichier de production
Évitez autant que possible les fichiers finaux partiellement écrits.
Exemple de modèle en local :
from pathlib import Path
target = Path("orders.parquet")
temp = Path("orders.parquet.tmp")
df.to_parquet(
temp,
index=False,
)
temp.replace(target)
Sur les systèmes de fichiers locaux, remplacer le fichier après une écriture réussie est plus sûr qu’écrire directement par-dessus le fichier final.
L’atomicité et le comportement d’écrasement diffèrent sur les systèmes distants et le stockage objet.
28. Éviter d’ajouter à un CSV à l’aveugle
Ajouter des données :
df.to_csv(
"orders.csv",
mode="a",
header=False,
index=False,
)
peut être valide, mais seulement si :
- le schéma est identique
- l’ordre des colonnes est identique
- l’encodage correspond
- aucun autre processus n’écrit en parallèle
- des écritures partielles sont acceptables
L’ajout à un CSV n’applique aucun contrôle de schéma.
Utilisez-le avec prudence.
29. N’ajouter l’en-tête qu’à la création d’un CSV
from pathlib import Path
path = Path("orders.csv")
df.to_csv(
path,
mode="a",
header=not path.exists(),
index=False,
)
Cela évite des lignes d’en-tête répétées dans les flux simples d’ajout en local.
Évitez tout de même ce modèle avec des processus d’écriture concurrents en production.
30. Comparer le choix du format de fichier selon la charge de travail
Utilisez ce modèle mental :
Interopérabilité humains/outils -> CSV
Stockage analytique typé -> Parquet
Échanges API/événements/documents -> JSON / JSON Lines
Ce n’est pas absolu, mais c’est un solide point de départ.
Interpréter le résultat
| Format | Point fort | Risque principal |
|---|---|---|
| CSV | Universel et lisible par un humain | Aucun schéma intégré ; l’inférence des types peut changer le sens |
| Parquet | Typé, en colonnes, compressé, efficace pour l’analytique | Moins lisible par un humain ; la compatibilité des moteurs et outils compte |
| JSON | Échange hiérarchique flexible | Verbeux ; la structure imbriquée peut compliquer le chargement tabulaire |
| JSON Lines | Un enregistrement par ligne, adapté au flux | Reste verbeux ; le schéma peut varier d’un enregistrement à l’autre |
Options pandas importantes :
| Option | Pourquoi c’est important |
|---|---|
dtype= |
Empêche une inférence des types non souhaitée |
parse_dates= |
Analyse les colonnes de dates connues pendant la lecture |
usecols= |
Ne lit que les colonnes nécessaires |
na_values= |
Ajoute des marqueurs de valeurs manquantes propres à la source |
keep_default_na= |
Contrôle la reconnaissance intégrée des valeurs nulles par pandas |
columns= |
Restreint les colonnes lues ou écrites en Parquet |
filters= |
Peut activer le filtrage des prédicats à la source (predicate pushdown) en Parquet |
compression= |
Contrôle la compression en sortie |
orient= |
Définit la forme du JSON |
lines=True |
Lit ou écrit du JSON Lines |
Points à vérifier
Les identifiants perdent leurs zéros initiaux
La source a probablement été inférée comme numérique.
Utilisez :
dtype={"customer_id": "string"}
La colonne de dates reste du texte
Soit :
- elle n’a pas été analysée
- les valeurs sources sont incohérentes
- le format est inattendu
Inspectez les échecs d’analyse avant de remplacer les données d’origine.
Un aller-retour CSV modifie les dtypes
C’est normal, sauf si vous restaurez explicitement le schéma.
CSV ne stocke pas de schéma pandas.
Le fichier Parquet est bien plus petit que le CSV
C’est souvent attendu, car Parquet est compressé et organisé en colonnes.
Ne jugez pas l’exactitude sur la seule taille du fichier.
La lecture Parquet reste lente
Vérifiez :
- le nombre de fichiers
- le problème des petits fichiers
- les colonnes sélectionnées
- le filtrage à la source
- la latence du stockage
- le codec de compression
- l’organisation des partitions
Le JSON produit des colonnes ou un nombre de lignes inattendus
La source est peut-être imbriquée.
Inspectez la hiérarchie JSON et définissez la granularité de sortie voulue avant de normaliser.
Le nombre de valeurs nulles change après la lecture d’un CSV
Vérifiez :
na_valueskeep_default_na- les chaînes vides
- les valeurs littérales telles que
"NA"
L’interprétation des valeurs nulles dans un CSV est configurable et peut changer le sens métier.
Notes de production
CSV n’a pas de véritable schéma
Un fichier CSV ne distingue pas par nature :
00123
de :
123
ni :
2026-10-04
d’une simple chaîne.
Conservez le schéma séparément ou spécifiez-le au moment de la lecture.
Parquet est généralement plus adapté aux analyses répétées
Parquet prend en charge :
- les colonnes typées
- la compression
- l’élagage des colonnes
- le filtrage des prédicats à la source dans les lecteurs compatibles
- des lectures complètes efficaces
C’est généralement un format analytique interne plus solide que CSV.
Les dépendances Parquet comptent
pandas s’appuie sur un moteur Parquet tel que :
pyarrowfastparquet
Les fonctionnalités disponibles et la compatibilité peuvent différer.
Pour les charges de travail pandas modernes, pyarrow est couramment utilisé.
JSON n’est pas tabulaire par nature
Les objets et tableaux imbriqués exigent une stratégie d’aplatissement explicite.
Avant la normalisation, définissez :
Que doit représenter une ligne de sortie ?
Les écritures de fichiers ne sont pas des transactions
Écrire un fichier local ou distant n’apporte pas automatiquement l’atomicité d’une base de données.
Pour une sortie critique :
- écrivez dans un emplacement temporaire
- validez
- promouvez ou renommez lorsque c’est pris en charge
- évitez les processus d’écriture concurrents
- utilisez un format de stockage ou une couche de tables avec une sémantique transactionnelle lorsque c’est nécessaire
Le stockage objet ne se comporte pas comme un disque local
Des chemins tels que :
s3://...
abfss://...
gs://...
peuvent être pris en charge par des intégrations de systèmes de fichiers, mais :
- la sémantique du renommage diffère
- les identifiants d’accès comptent
- les nouvelles tentatives comptent
- le comportement de cohérence dépend du service
- les écritures concurrentes exigent une conception délibérée
Ne supposez pas le comportement d’un système de fichiers local.
Éviter les nombreux petits fichiers Parquet
Les petits fichiers créent une surcharge de métadonnées et de planification dans les systèmes analytiques.
Regroupez les données dans des fichiers de taille adaptée au moteur en aval au lieu d’écrire un fichier par ligne ou par événement.
La compression échange du CPU contre du stockage et des E/S
Le meilleur codec dépend :
- de la fréquence de lecture
- de la fréquence d’écriture
- du coût de stockage
- du budget CPU
- de la compatibilité en aval
Mesurez avec votre charge de travail.
Erreurs fréquentes
1. Laisser pandas inférer le type des identifiants
Les identifiants sont souvent des chaînes, même lorsqu’ils ne contiennent que des chiffres.
Utilisez des dtypes explicites.
2. Écrire l’index du DataFrame par accident
Cela produit couramment des colonnes indésirables lorsque le fichier est rechargé.
Utilisez :
index=False
sauf si l’index fait volontairement partie du contrat de données.
3. Considérer que CSV conserve le schéma
Ce n’est pas le cas.
Définissez les types à la lecture.
4. Raisonner façon errors="ignore" face à des fichiers défectueux
Une conversion silencieuse ou une analyse permissive peut masquer des problèmes de qualité des données.
Inspectez délibérément les enregistrements rejetés ou mal formés.
5. Supposer qu’en JSON un objet correspond à une ligne
Les tableaux imbriqués peuvent multiplier les enregistrements.
Définissez la granularité cible avant de normaliser.
6. Ajouter à un CSV depuis plusieurs processus
Des ajouts concurrents peuvent corrompre ou entremêler la sortie.
Utilisez un processus d’écriture coordonné ou un système de stockage conçu pour la concurrence.
7. Partitionner un Parquet sur des colonnes à forte cardinalité
Cela crée trop de petites partitions ou de petits fichiers.
Partitionnez sur des champs qui servent les modèles d’élagage courants et dont la cardinalité reste gérable.
8. Écrire directement par-dessus un fichier de production
Une écriture en échec peut laisser une sortie incomplète.
Utilisez un modèle d’écriture préparée puis promue lorsque le système de fichiers ou le modèle de stockage le permet.
9. Supposer que le filtrage des prédicats Parquet à la source a toujours lieu
La prise en charge du filtrage dépend de l’organisation, des métadonnées, du moteur et de l’expression.
Vérifiez le comportement pour les charges de travail importantes.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.