Gegevens inlezen en opslaan

Een CSV-bestand is gewone tekst die is ingedeeld in records en velden. Komma's scheiden meestal de velden en het eerste record levert vaak kolomnamen. Het bestand bevat tekens, geen pandas-gegevensschema, dus bij het inlezen bepaal je ook wat die tekens voorstellen.

Lees een klein bestand in en inspecteer het

Stel dat een bestand dit bevat:

order_id,date,region,units,price
1001,2026-03-02,North,3,4.50
1002,2026-03-02,South,1,12.00
1003,2026-03-03,North,2,7.25

Lees het in en inspecteer het resultaat:

import pandas as pd

df = pd.read_csv("sales.csv")
print(df.head())
print(df.shape)
print(df.dtypes)
df.info()

De vorm is (3, 5): drie gegevensrijen en vijf kolommen. pandas leidt int64 af voor order_id en units en float64 voor price. De kolom date bevat nog tekst. In pandas 3 tonen afgeleide tekstkolommen normaal str; oudere pandas-versies tonen vaak object.

Elke inspectie beantwoordt een andere vraag. head() laat zien of velden bij hun labels passen. shape brengt ontbrekende rijen of een onverwachte extra kolom aan het licht. dtypes controleert de interpretatie en info() voegt het aantal aanwezige waarden toe. Als een kolom die voor getallen is bedoeld als tekst wordt ingelezen, bekijk dan de ruwe waarden: een eenheid, een plaatsaanduiding of een andere decimale notatie kan verhinderen dat een numeriek type wordt afgeleid.

Laat labels bij records passen

Gebruik voor een bestand zonder kopregel waarvan de eerste regel 1001,North,3 is:

df = pd.read_csv(
    "orders.txt",
    header=None,
    names=["id", "region", "units"]
)

Zonder die keuze neemt pandas het eerste record als kopregel. De waarden worden kolomnamen en het record verdwijnt uit de gegevens. Gebruik index_col="order_id" als een bestaande kolom de rijen moet labelen. Gebruik usecols=["region", "units"] om alleen die kolommen in te lezen, of nrows=1000 om de eerste 1.000 gegevensrijen te inspecteren voordat je een groot bestand inleest.

Laat de CSV-leesfunctie aanhalingstekens verwerken

Het record "Smith, Jane",Boston,10 heeft drie velden. De komma binnen de naam tussen aanhalingstekens hoort bij die naam. Twee dubbele aanhalingstekens binnen een veld tussen aanhalingstekens stellen één letterlijk dubbel aanhalingsteken voor: "O'Neil ""Red""" wordt O'Neil "Red". Een veld tussen aanhalingstekens kan zelfs een regeleinde bevatten, dus records en fysieke regels komen niet altijd overeen.

De aanroep line.split(",") splitst de naam en kan deze regels niet verwerken. read_csv verwerkt ze tijdens het inlezen. pd.read_table gebruikt standaard een tab als scheidingsteken; pd.read_fwf verwerkt velden die zijn gedefinieerd door tekenposities.

Zoek het bestand dat Python probeert te vinden

Een relatief pad wordt bepaald vanuit de huidige werkmap van het programma. Als "data/sales.csv" niet kan worden gevonden, inspecteer de werkmap dan met Path.cwd() na from pathlib import Path. Je kunt ook een absoluut pad, een Path-object, een URL of een tekstbestand in het geheugen zoals StringIO aan read_csv doorgeven. Controleer de locatie voordat je inleesopties wijzigt: een ontbrekend bestand en een verkeerd ingelezen bestand zijn verschillende problemen.

Een scheidingsteken scheidt velden; een decimaalteken scheidt het gehele en het decimale deel van een getal. Een scheidingsteken voor duizendtallen groepeert cijfers. Deze drie functies vereisen aparte instellingen, ook als hetzelfde symbool in verschillende bestanden een andere functie heeft.

Inspecteer tekens voordat je opties kiest

Bekijk enkele ruwe regels in een editor. Een .csv-extensie garandeert geen komma's en .txt duidt geen bepaalde indeling aan. Veelgebruikte instellingen zijn:

Je kunt het begin inspecteren zonder het hele bestand in te lezen:

with open("products.csv", encoding="utf-8") as f:
    print(f.readline())
    print(f.readline())

Doorloop een regionale export

Bekijk deze tekst:

product;price;qty
Tea;3,50;1.200
Coffee;12,90;850

De puntkomma's scheiden velden, de komma is het decimaalteken en de punt groepeert duizendtallen. Geef alle drie de conventies expliciet op bij het inlezen:

df = pd.read_csv(
    "products.csv",
    sep=";",
    decimal=",",
    thousands="."
)

De prijzen worden 3,5 en 12,9. De aantallen worden 1200 en 850. Met de standaardkomma als scheidingsteken beschrijft deze kopregel geen drie door komma's gescheiden kolommen. Zelfs nadat je sep=";" hebt gekozen, ben je nog niet klaar: de prijzen blijven tekst en "1.200" kan het decimale getal 1,2 worden. Dat laatste resultaat is een geldig getal met de verkeerde betekenis, dus voor een ernstige fout hoeft geen inleesuitzondering op te treden.

Vergelijk enkele ingelezen waarden met hun brontekst en inspecteer describe() op onwaarschijnlijke bereiken. Een aantal dat je in de duizenden verwacht en dat rond één uitkomt, wijst op een probleem met de getalnotatie. Alleen het scheidingsteken wijzigen lost dat niet op.

Houd veldgrenzen gescheiden van de groepering van getallen

In een bestand met komma's als scheidingsteken moet een gegroepeerd getal zoals "1,234.50" tussen aanhalingstekens staan. De komma binnen het getal maakt er deel van uit. Met thousands="," kan pandas het veld tussen aanhalingstekens lezen als 1234,5. Zonder aanhalingstekens maakt de komma ook een veldgrens; thousands kan de verloren recordstructuur niet herstellen.

Kies een geschikte parser

De standaardparser in C verwerkt veelvoorkomende indelingen snel. De Python-parser ondersteunt detectie van het scheidingsteken met sep=None, reguliere expressies als scheidingsteken en skipfooter. De detectie onderzoekt een deel van het bestand en kan bij een onregelmatig rapport verkeerd kiezen, dus geef een bekend scheidingsteken direct op.

Een scheidingsteken van meer dan één teken wordt doorgaans als reguliere expressie behandeld en vereist de Python-parser; r"\s+" is een bijzonder geval dat ook door de C-parser wordt ondersteund. De PyArrow-parser kan met parallelle threads lezen, maar ondersteunt andere opties. Zo wordt chunksize niet ondersteund met engine="pyarrow". Kies de parser op basis van de opties die je bestand nodig heeft en controleer vervolgens de structuur en waarden van het resultaat.

Automatische typeafleiding kan niet weten of 999 een meting is of een code voor een onbekende waarde. Ook kan die niet weten of voorloopnullen betekenis hebben. Gebruik de definities van de gegevens om inleesopties in te stellen voordat de typeafleiding die waarden verandert.

Geef aan waar markeringen voor ontbrekende waarden gelden

pandas herkent lege velden en ingebouwde markeringen zoals "NA", "N/A", "n/a", "NULL", "NaN" en "None". Een bron kan extra markeringen gebruiken. Stel dat score 88, "n/a", "-" en 999 bevat, waarbij 999 als onbekend is gedefinieerd:

df = pd.read_csv(
    "scores.csv",
    na_values={"score": ["-", "999"]}
)

De scorekolom bevat nu 88,0 en drie ontbrekende waarden. Zonder de markeringen op te geven kan "-" ervoor zorgen dat de kolom tekst blijft; een niet-opgegeven numerieke signaalwaarde kan in berekeningen terechtkomen. Het gemiddelde van 88 en 999 is 543,5, hoewel de enige bekende score 88 is.

Een dictionary beperkt een markering tot de bijbehorende kolom. Een na_values=["999"] voor het hele bestand zou ook een echte productcode 999 verwijderen. Als "NA" een echt label is, gebruik dan keep_default_na=False om de ingebouwde lijst met markeringen uit te schakelen en geef expliciet de markeringen op die wel ontbreken betekenen. Neem bij die instelling "" op als lege velden nog steeds als ontbrekend moeten tellen.

Behoud waarden volgens hun functie

Lees identificatiecodes als tekst:

df = pd.read_csv(
    "visits.csv",
    dtype={"site_code": str, "visits": "Int64"}
)

Een code zoals "00501" moet vijf tekens lang blijven. Als je die als geheel getal inleest, krijg je 501; als je dat gehele getal later naar tekst converteert, krijg je "501", niet de oorspronkelijke code. Gebruik een numeriek type voor waarden waarmee je rekent.

Gewone NumPy-kolommen met gehele getallen kunnen geen NaN bevatten, dus wordt een telkolom met een ontbrekende waarde vaak float64. Het pandas-type "Int64", met een hoofdletter I, ondersteunt ontbrekende waarden, behoudt gehele getallen en geeft een ontbrekende waarde weer met <NA>. dtype_backend="numpy_nullable" vraagt voor het hele resultaat om types met ondersteuning voor ontbrekende waarden. Voor een kleine, herhaalde verzameling labels slaat dtype={"region": "category"} de labels op als categorieën en kan dit het geheugengebruik verminderen.

Geef op hoe datums zijn geschreven

Tekst die op een datum lijkt, blijft tekst totdat die als datum wordt ingelezen. Gebruik voor datums met de dag eerst, zoals "03/04/2026" en "13/04/2026":

df = pd.read_csv(
    "events.csv",
    parse_dates=["day"],
    date_format="%d/%m/%Y"
)

Deze waarden worden 3 april en 13 april. Zonder formaat kan een keuze voor de maand eerst geldige dagen en maanden verwisselen of kan de conversie van de kolom mislukken. dayfirst=True geeft een voorkeur aan; een expliciet formaat legt de verwachte structuur vast. ISO-datums zoals "2026-04-03" voorkomen dubbelzinnigheid over dag en maand.

Inspecteer na het inlezen dtypes, isna().sum() en het aantal rijen. Controleer een datum waarvan de interpretatie de conventies van elkaar onderscheidt. Als een kolom nog tekst toont, zijn bij het inlezen niet de bedoelde datum-tijdwaarden ontstaan; een onverwachte stijging van het aantal ontbrekende waarden kan aangeven dat een echt label voor een markering is aangezien.

Een rapport kan een tabel combineren met titels, lege regels, commentaar, totalen en bronvermeldingen. Zoek eerst de kopregel en de grenzen van de gegevens. Anders kan een leesfunctie een titel voor kolomnamen aanzien of een totaal als gewone waarneming opnemen.

Lees alleen de tabel in

Een rapport bevat deze negen fysieke regels:

Monthly sales report
Exported 2026-04-01

region,jan,feb
North,120,135
# test row below
South,98,101
Total,218,236
Source: internal system

De eerste drie regels staan vóór de kopregel. De laatste twee zijn geen waarnemingen. Lees het rapport zo in:

df = pd.read_csv(
    "report.csv",
    skiprows=3,
    comment="#",
    skipfooter=2,
    engine="python"
)

Het resultaat heeft twee rijen. Het totaal voor januari is 218 uit North en South. Als je de totaalrij behoudt, komt daar nog eens 218 bij en rapporteer je 436. Met de standaardinstellingen kan de titel met één veld daarentegen de kopregel worden en tot een inleesfout leiden wanneer records met drie velden volgen.

skiprows=3 telt de eerste drie fysieke regels, inclusief de lege regel. Een lijst zoals skiprows=[0, 2] verwijdert specifieke regelposities, geteld vanaf nul. Lege regels worden standaard overgeslagen en comment="#" verwijdert commentaartekst. skipfooter vereist de Python-parser. Stem deze instellingen af op de werkelijke indeling; een vast aantal over te slaan regels kan onjuist worden als een exportprogramma een titelregel toevoegt.

Onderzoek onjuist opgebouwde records

Een record met te veel velden kan on_bad_lines="error", de standaardinstelling, activeren. "warn" slaat het record over met een waarschuwing, terwijl "skip" het zonder melding verwijdert. Inspecteer het ruwe record voordat je een van beide kiest. Een komma binnen een naamveld zonder aanhalingstekens of een verkeerd scheidingsteken kan extra velden maken; als je het record dan overslaat, verlies je een geldige waarneming in plaats van de oorzaak op te lossen.

Te weinig velden gedragen zich anders. Onder id,name,score wordt het record 2,Ben ingelezen met een ontbrekende score. Dat hoeft geen fout te geven. Controleer zowel het aantal ontbrekende waarden als het aantal rijen en vergelijk de behouden records met de bron als je onjuist opgebouwde regels uitsluit.

Lees kopregels op meerdere rijen of tekenposities

Twee rijen met kolomlabels kunnen een MultiIndex vormen. Met de groepslabels region,sales,sales boven ,2025,2026 geeft header=[0, 1] labels zoals ("sales", "2025"). Als platte labels beter bij de analyse passen, sla dan beide kopregels over en geef names=["region", "sales_2025", "sales_2026"] op.

Tekst met vaste veldbreedtes heeft geen scheidingsteken. Kolomgrenzen zijn tekenposities:

df = pd.read_fwf(
    "readings.txt",
    colspecs=[(0, 4), (4, 11), (11, 16)]
)

Deze halfopen bereiken omvatten elk beginpunt en sluiten het eindpunt uit. Het eerste veld beslaat de posities 0 tot en met 3 en het volgende begint bij 4. widths=[4, 7, 5] beschrijft dezelfde indeling. Automatische afleiding is handig bij regelmatige voorbeelden; expliciete grenzen voorkomen dat een korte waarde aan het begin de verkeerde breedte bepaalt.

Een bestand slaat bytes op, elk met een waarde van 0 tot en met 255. Een tekencodering bepaalt hoe tekens door die bytes worden weergegeven. Coderen zet Python-tekst om in bytes; decoderen zet bytes terug om in tekst. Dezelfde bytes kunnen volgens verschillende decoderingsregels verschillende tekens betekenen.

Tel tekens en bytes afzonderlijk

text = "café"
raw = text.encode("utf-8")
print(len(text))  # 4 characters
print(len(raw))   # 5 bytes
print(raw.decode("utf-8"))  # café

Het accent maakt hier geen tweede zichtbaar teken. De letter "é" heeft in UTF-8 twee bytes nodig, dus nemen vier tekens vijf bytes in. Het aantal bytes en het aantal tekens beantwoorden verschillende vragen.

ASCII definieert 128 tekens, waaronder Engelse basisletters, cijfers, leestekens en besturingscodes. Hun bytewaarden komen overeen in ASCII, UTF-8, Latin-1 en Windows-1252. Dit gedeelde begin verklaart waarom een voorbeeld met alleen Engelse tekst correct kan lijken, ook als de tekencodering verkeerd is ingesteld.

Herken de belangrijkste coderingsfamilies

UTF-8 geeft elk Unicode-teken weer en is de gebruikelijke keuze voor uitgewisselde tekst. Latin-1 en Windows-1252 geven een kleinere verzameling tekens weer. Ze komen overeen voor veel letters met accenten, maar verschillen in een deel van het bytebereik: Windows-1252 gebruikt byte 0x80 voor "€", waar Latin-1 een besturingsteken heeft. Het zijn geen uitwisselbare namen voor één codering.

Lees bytevolgordemarkeringen correct

Een bytevolgordemarkering, of BOM, is een markering aan het begin van sommige bestanden. UTF-16 kan beginnen met FF FE voor de little-endianvolgorde of FE FF voor de big-endianvolgorde. encoding="utf-16" gebruikt de BOM om de volgorde te kiezen. Zonder BOM geef je "utf-16-le" of "utf-16-be" op, afhankelijk van de bron.

Een UTF-8-BOM is EF BB BF. open(..., encoding="utf-8-sig") van Python verwijdert die tijdens het decoderen. Gewoon "utf-8" in open() behoudt die als \ufeff, wat onverwacht deel kan worden van de eerste kolomnaam. De CSV-leesfunctie van pandas verwerkt een UTF-8-BOM aan het begin ook, maar met utf-8-sig maak je de bedoelde bestandsconventie duidelijk.

Geef de tekencodering expliciet op

with open("notes.txt", encoding="utf-8") as f:
    text = f.read()

De standaardwaarde van open() hangt af van de Python-versie en de UTF-8-modus. Python 3.11–3.14 kan de codering van de landinstellingen gebruiken; Python 3.15 schakelt standaard de UTF-8-modus in, die je kunt uitschakelen. Met een expliciete codering blijft het script op verschillende computers afgestemd op het werkelijke bestandsformaat. Ook voorkom je dat een platformstandaard ongemerkt verandert hoe dezelfde bytes worden gelezen.

Een verkeerde tekencodering kan duidelijk misgaan met een UnicodeDecodeError, of ongemerkt leesbaar ogende onzin opleveren: mojibake. Beide problemen beginnen bij het interpreteren van bytes volgens de verkeerde regel. Bewaar het oorspronkelijke bestand zodat je het opnieuw kunt decoderen.

Stel de oorzaak van een fout vast

Een als Windows-1252 opgeslagen CSV bevat plaatsnamen waaronder "Zürich" en "Málaga". Als je het als UTF-8 leest, kan het misgaan bij byte 0xfc, die in Windows-1252 voor "ü" wordt gebruikt. Zodra de exportinstellingen van de bron de codering bevestigen, lees je het bestand zo in:

df = pd.read_csv("cities.csv", encoding="cp1252")
print(df["city"].head())

Inspecteer namen met accenten of symbolen. Een voorbeeld dat volledig uit ASCII-tekens bestaat, kan deze coderingen niet onderscheiden. Een bepaalde ongeldige byte in UTF-8 wijst op een mogelijke oudere codering, maar bepaalt niet eenduidig welke oudere codering het bestand heeft voortgebracht.

Herken een fout zonder foutmelding

Bytes in UTF-8 die als Windows-1252 worden gedecodeerd, kunnen "café" veranderen in "café" en "São Paulo" in "São Paulo". De leesfunctie heeft met succes tekens geproduceerd, maar het zijn de verkeerde tekens. Lees de oorspronkelijke bytes opnieuw met UTF-8:

df = pd.read_csv("cities.csv", encoding="utf-8")

Met zoeken en vervangen herstel je telkens één zichtbaar symptoom en kun je andere beschadigde letters missen. Ook loop je het risico een werkelijk voorkomend teken te veranderen. Correct decoderen pakt de oorzaak voor het hele bestand aan.

Verzamel aanwijzingen voor de tekencodering

Begin bij de documentatie of exportinstellingen van de leverancier. Inspecteer zo nodig een klein voorbeeld van de bytes:

with open("cities.csv", "rb") as f:
    sample = f.read(200)
print(sample)

De binaire modus behoudt de bytes zonder ze te decoderen. Een BOM kan een directe aanwijzing geven. Een detectieprogramma zoals charset-normalizer schat een waarschijnlijke codering, maar een kort voorbeeld kan bij meerdere mogelijkheden passen. Controleer het resultaat aan de hand van bekende namen met accenten en symbolen.

Latin-1 kent aan elke byte een teken toe en kan daardoor elke bytereeks zonder fout decoderen. Dat dit lukt, zegt op zichzelf niets over de juistheid van de tekens. Windows-1252 gebruikt ook tekens van één byte, maar laat enkele bytewaarden ongedefinieerd en kan een decoderingsfout geven.

Gooi de aanwijzingen niet weg

encoding_errors="replace" vervangt bytes die de decoder niet kan lezen door "�". encoding_errors="ignore" verwijdert ze. Deze opties kunnen helpen om beschadigde invoer te inspecteren, maar ze leiden tot informatieverlies en vervangen het zoeken naar de juiste codering niet. Een naam die is veranderd in "Zrich" kan een overeenkomst net zo goed verhinderen als zichtbaar verminkte tekst.

Voor uitvoer verwerkt UTF-8 de grootste verscheidenheid aan tekens. Sommige spreadsheetprogramma's herkennen die codering betrouwbaarder als er een BOM aanwezig is:

df.to_csv("cities_export.csv", index=False, encoding="utf-8-sig")

Open de export opnieuw in het ontvangende programma en inspecteer dezelfde waarden met accenten. Het doel is correcte tekst aan beide kanten van de uitwisseling.

De grootte van een bestand op schijf is niet gelijk aan de hoeveelheid geheugen die het nodig heeft. pandas bouwt arrays, indexen en tekstwaarden op in het geheugen en hun types beïnvloeden de benodigde ruimte. Meet met df.memory_usage(deep=True) of df.info(memory_usage="deep") voordat je beslist hoe je meer gegevens inleest.

Verminder de gegevens die je in het geheugen inleest

Lees geselecteerde kolommen met usecols, inspecteer een eerste steekproef met nrows en kies geschikte types met dtype. Een categorie kan herhaalde regionamen compact opslaan. float32 gebruikt minder ruimte dan float64, maar biedt ongeveer zeven significante cijfers, dus kies dit type alleen als die precisie bij de metingen past. Een kleine voorvertoning helpt types te herkennen, maar bewijst niet dat elke latere rij hetzelfde patroon volgt.

Verwerk gegevensblokken en bewaar een klein resultaat

chunksize verandert de teruggegeven waarde van een DataFrame in een iterator van DataFrames. Voor een totaal en een gemiddelde:

total = 0.0
count = 0
with pd.read_csv(
    "measurements.csv",
    usecols=["amount"],
    chunksize=100_000
) as reader:
    for chunk in reader:
        total += chunk["amount"].sum()
        count += chunk["amount"].count()
mean = total / count if count else float("nan")

De lus houdt een cumulatieve som en het aantal aanwezige waarden bij. Elk gegevensblok kan na gebruik worden vrijgegeven. Als je alle blokken in een lijst verzamelt en later aaneenvoegt, heb je opnieuw evenveel geheugen nodig als voor het geheel; blokgewijze verwerking bespaart alleen geheugen als het werk een kleiner resultaat bewaart of verwerkte delen wegschrijft.

Een bestand van tien rijen dat je met chunksize=4 inleest, levert delen van 4, 4 en 2 rijen op. Bij bedragen van 1 tot en met 10 met afwisselend de regio's N, S en E tel je de regionale deeltotalen op tot N 22, S 15 en E 18. Samen is dat 55.

Combineer de juiste grootheden

Sommen en aantallen kun je optellen. Combineer minima door het kleinste deelminimum te nemen; combineer maxima door het grootste deelmaximum te nemen. Gemiddelden hebben gewichten nodig, omdat blokken verschillende aantallen geldige waarnemingen kunnen bevatten.

Voor de waarden 1, 2 en 3 in het ene blok en 10 in het andere zijn de blokgemiddelden 2 en 10. Het gemiddelde van die gemiddelden is 6, waarbij het blok met één waarde even zwaar meetelt als het blok met drie waarden. Tel in plaats daarvan de sommen en aantallen op: een totaal van 16 over vier waarnemingen geeft een gemiddelde van 4. Blokmedianen bevatten niet genoeg informatie om een totale mediaan te reconstrueren.

Lees gecomprimeerde bestanden rechtstreeks in

read_csv leidt compressie normaal af uit herkende extensies zoals .gz, .bz2, .zip, .xz en .zst. Tijdens het inlezen wordt gedecomprimeerd:

with pd.read_csv("measurements.csv.gz", chunksize=100_000) as reader:
    for chunk in reader:
        print(len(chunk))

Een ZIP-archief dat je zo gebruikt, moet precies één gegevensbestand bevatten. df.to_csv("out.csv.gz", index=False) schrijft met gzip gecomprimeerde CSV. Compressie vermindert de schijfruimte en de hoeveelheid over te dragen gegevens, maar neemt het geheugengebruik van de gedecodeerde tabel niet weg. Voor herhaalde analyse voorkomt het converteren van een gecontroleerde dataset naar Parquet ook dat tekst steeds opnieuw moet worden ingelezen en worden de opgeslagen kolomtypes hersteld.

Een Excel-werkmap kan meerdere werkbladen, titels en berekende totalen bevatten. Cellen hebben opgeslagen waarden en types, maar ook weergaveopmaak. Om een werkblad in te lezen, zoek je de gegevenstabel en begrijp je welke onderdelen van de werkmap DataFrame-waarden worden.

Kies het werkblad en de grenzen

df = pd.read_excel(
    "quarterly.xlsx",
    sheet_name="Q1",
    skiprows=2,
    usecols="A:C",
    nrows=2
)

Stel dat rij 1 een samengevoegde titel is, rij 2 leeg is, rij 3 region, date en sales bevat en rijen 4–5 de waarnemingen bevatten. skiprows=2 maakt van rij 3 de kopregel; nrows=2 stopt vóór het totaal in rij 6. Voor North 1200 en South 950 tellen de twee waarnemingen op tot 2150. Als je een opgeslagen totaal van 2150 als derde waarneming opneemt, verdubbelt dat bedrag.

Excel toont rijnummers vanaf 1; rijposities in pandas beginnen bij 0. Ook header=2 selecteert Excel-rij 3 als kopregel. usecols="A,C,E:F" selecteert afzonderlijke kolommen en een bereik. De standaardinstelling sheet_name=0 leest het eerste werkblad; een naam selecteert een specifiek werkblad en sheet_name=1 selecteert het tweede.

sheet_name=None geeft een dictionary terug die werkbladnamen aan DataFrames koppelt. Selecteer een sleutel of doorloop .items() in een lus; de dictionary zelf is niet één DataFrame. Voor meerdere leesbewerkingen uit één werkmap:

with pd.ExcelFile("quarterly.xlsx") as xf:
    print(xf.sheet_names)
    q1 = pd.read_excel(xf, sheet_name="Q1")

Weet wat de cel werkelijk opslaat

Een percentage dat wordt weergegeven als "15%" slaat 0,15 op. Een getal dat met vijf cijfers wordt weergegeven, kan 2139 opslaan, ook al toont het scherm "02139". Geen enkele inleesoptie kan een nul terughalen die alleen in de opmaak bestaat. Sla identificatiecodes als tekst op in de werkmap en geef bij het inlezen ook dtype={"zip": str} door; anders kan pandas zelfs uit tekstcellen met alleen cijfers gehele getallen afleiden.

De numerieke precisie van Excel is beperkt tot 15 significante cijfers. Een identificatiecode van 16 cijfers die als getal is ingevoerd, kan al beschadigd zijn voordat Python die inleest. Sla zulke waarden op als tekst. Een werkblad heeft maximaal 1.048.576 rijen en 16.384 kolommen, dus een zeer grote dataset heeft een ander formaat nodig.

Ga zorgvuldig om met formules en samengevoegde cellen

pandas berekent geen formules. Het leest opgeslagen resultaten uit de werkmap. Een spreadsheetprogramma kan actuele resultaten opslaan; een door een script gemaakt bestand kan ontbrekende, voorlopige of verouderde opgeslagen resultaten bevatten. openpyxl berekent geen resultaat en XlsxWriter schrijft normaal een nul als plaatsaanduiding, tenzij een waarde wordt opgegeven. Bereken belangrijke waarden opnieuw in pandas of open en sla de werkmap op in een spreadsheetprogramma voordat je op de opgeslagen totalen vertrouwt.

Alleen de cel linksboven in een samengevoegd celbereik slaat het label op. Een samengevoegd landlabel kan daardoor lege waarden in de rijen eronder achterlaten. Als de indeling bevestigt dat het label voor die rijen geldt, vult df["country"] = df["country"].ffill() het naar beneden aan. Inspecteer de tabelgrens voordat je aanvult.

Voor het inlezen is een Excel-bibliotheek nodig. openpyxl verwerkt .xlsx en .xlsm; xlrd verwerkt .xls, pyxlsb verwerkt .xlsb, odf verwerkt .ods en calamine ondersteunt meerdere spreadsheetformaten. Een ontbrekende bibliotheek geeft een ImportError met de naam van de benodigde afhankelijkheid. Kleuren, opmerkingen en andere vormgeving worden niet als DataFrame-gegevens ingelezen.

Excel is handig wanneer mensen een rapport in een spreadsheetprogramma moeten openen en inspecteren. Een DataFrame kan één werkblad worden, of meerdere DataFrames kunnen een werkmap delen. Kies vóór het schrijven het doelpad en de werkbladnamen, zodat elke tabel op de bedoelde plaats terechtkomt.

Schrijf één of meerdere tabellen

weather.to_excel(
    "weather.xlsx",
    sheet_name="Weather",
    index=False
)

index=False houdt de standaardrijnummers buiten het werkblad. Zonder die optie verschijnen ze als een extra eerste kolom en kunnen ze bij later inlezen terugkomen als "Unnamed: 0". Behoud een index alleen als die betekenisvolle labels bevat die in het rapport thuishoren.

Een to_excel-aanroep met een pad schrijft een werkmap op dat pad en vervangt een bestaand bestand. Als je de aanroep één keer voor Weather en daarna voor Counts op hetzelfde pad uitvoert, blijft mogelijk alleen de tweede tabel over. Gebruik één schrijver voor beide:

with pd.ExcelWriter("report.xlsx") as writer:
    weather.to_excel(writer, sheet_name="Weather", index=False)
    counts.to_excel(writer, sheet_name="Counts", index=False)

De contextmanager sluit en voltooit de werkmap wanneer het blok eindigt. Als je die met pd.read_excel("report.xlsx", sheet_name=None) inleest, krijg je een dictionary met beide werkbladnamen. Voor het schrijven van .xlsx is openpyxl of XlsxWriter nodig.

Werk een werkblad in een bestaande werkmap bij

Gebruik een schrijver in toevoegmodus om één werkblad te vervangen en de andere te behouden:

with pd.ExcelWriter(
    "report.xlsx",
    mode="a",
    engine="openpyxl",
    if_sheet_exists="replace"
) as writer:
    counts.to_excel(writer, sheet_name="Counts", index=False)

if_sheet_exists bepaalt wat er bij een naamconflict gebeurt. "error" stopt, "new" maakt een ander werkblad, "replace" vervangt dat werkblad en "overlay" schrijft in de bestaande cellen. Bij schrijven over een bestaand werkblad worden oude cellen buiten de nieuwe tabel niet gewist, zodat een kortere update oude rijen kan achterlaten. Bepaal of het rapport een volledige vervanging van het werkblad nodig heeft of zorgvuldig gepositioneerde nieuwe inhoud over bestaande cellen.

Maak de uitvoer gemakkelijk opnieuw te openen

Werkbladnamen mogen maximaal 31 tekens bevatten en mogen geen :, \, /, ?, *, [ of ] bevatten. Een korte naam zoals "Q1 Summary" werkt; "Q1/Q2" bevat een verboden schuine streep. Sommige bibliotheken waarschuwen bij een te lange naam in plaats van te stoppen, dus kies zelf geschikte namen.

startrow en startcol positioneren een tabel met verschuivingen die bij nul beginnen. na_rep geeft ontbrekende waarden een zichtbare markering. float_format="%.2f" rondt geschreven getallen af en autofilter=True voegt in pandas 3 filterknoppen aan de kopregel toe. Datum-tijdkolommen worden als Excel-datums geschreven.

Afronden bij de uitvoer verandert opgeslagen getallen, niet alleen hun weergave. Bewaar een analysebestand met volledige precisie apart wanneer een afgerond rapport nodig is. Open de werkmap opnieuw en controleer de lijst met werkbladen, tabelafmetingen en representatieve waarden. Excel inlezen is relatief langzaam en opslaan en opnieuw inlezen kan pandas-datatypes veranderen, dus gebruik Parquet voor tussentabellen in de analyse wanneer behoud van types belangrijk is.

JSON slaat geneste gegevens op als tekst. Objecten bevatten naam-waardeparen, arrays bevatten geordende waarden en tekenreeksen gebruiken dubbele aanhalingstekens. De overige waarden zijn getallen, true, false en null. De module json van Python zet deze syntaxis om in Python-objecten voordat je een tabel maakt.

Lees en schrijf geldige JSON

import json

text = '{"station":"Oslo","active":true,"temp_c":[3.5,null,4.0]}'
data = json.loads(text)
print(data["active"])   # True
print(data["temp_c"])   # [3.5, None, 4.0]

Objecten worden dictionaries, arrays worden lijsten en null wordt None. json.loads leest een tekenreeks in; json.load leest een open bestand. De schrijffuncties werken in de omgekeerde richting: json.dumps geeft tekst terug en json.dump schrijft naar een bestand.

with open("station.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

ensure_ascii=False laat tekens zoals "ü" leesbaar. De standaardinstelling kan hetzelfde teken schrijven als \u00fc; beide vormen stellen dezelfde tekenreeks voor. Een afgedrukte Python-dictionary is geen JSON: enkele aanhalingstekens, True, None en afsluitende komma's zijn ongeldige JSON-syntaxis. Standaard-JSON heeft ook geen NaN. De encoder van Python staat dit standaard toe, maar allow_nan=False wijst het af; pandas schrijft ontbrekende waarden als null.

Stem af op de tabelindeling

Een JSON-tabel heeft een oriëntatie nodig: de indeling van rijen, labels en waarden. orient="records" geeft één object per rij:

[{"city":"Lyon","temp_c":21.5},{"city":"Osaka","temp_c":null}]

De standaardoriëntatie voor DataFrames, "columns", groepeert waarden onder kolomnamen en daarna rijlabels. "split" slaat kolommen, index en gegevens afzonderlijk op. Geef een oriëntatie op die bij het ontvangende programma past in plaats van aan te nemen dat elke JSON-tabel dezelfde vorm heeft.

from io import StringIO
import pandas as pd

df = pd.read_json(
    StringIO('[{"code":"0042","amount":9.5}]'),
    orient="records",
    dtype={"code": str}
)

In pandas 3 is een gewone tekenreeks die aan read_json wordt doorgegeven een pad, dus plaats echte JSON-tekst in StringIO. Zelfs uit JSON-tekenreeksen met alleen cijfers kunnen getallen worden afgeleid; het expliciete datatype behoudt "0042".

Gebruik JSON Lines voor opeenvolgende records

JSON Lines heeft één volledig JSON-object per regel, zonder omringende array of komma's tussen records:

{"id":1,"amount":9.5}
{"id":2,"amount":12.0}

Lees het in met pd.read_json(path, lines=True) en schrijf het met df.to_json(path, orient="records", lines=True). De opties chunksize en nrows van de leesfunctie vereisen lines=True, waardoor afzonderlijke records na elkaar beschikbaar komen.

Stel bij het exporteren van datums date_format="iso" in voor leesbare ISO-tijdstempels. pandas 3.1 gebruikt voor gewone DataFrame-uitvoer naar JSON nog standaard milliseconden sinds het epochtijdstip, maar die standaardinstelling verandert. Expliciete datumuitvoer voorkomt dat een leesprogramma moet raden wat een groot geheel getal voorstelt.

Geneste JSON kan een bestelling, de klant en meerdere artikelen in één object beschrijven. Bepaal vóór het omzetten naar een platte tabel het detailniveau per rij: wat één rij voorstelt. Dat detailniveau bepaalt welke bedragen je kunt optellen.

Zet eerst geneste objecten om naar een platte tabel

Bekijk twee bestellingen. Bestelling 501 hoort bij Ana en heeft de artikelen A1 (aantal 2, prijs 3,5) en B7 (aantal 1, prijs 10,0). Bestelling 502 hoort bij Ben en heeft A1 (aantal 4, prijs 3,5). De klantgegevens zijn geneste objecten en de artikelen zijn lijsten.

orders = [
    {"order_id": 501,
     "customer": {"name": "Ana", "country": "PT"},
     "items": [{"sku": "A1", "qty": 2, "price": 3.5},
               {"sku": "B7", "qty": 1, "price": 10.0}]},
    {"order_id": 502,
     "customer": {"name": "Ben", "country": "CA"},
     "items": [{"sku": "A1", "qty": 4, "price": 3.5}]}
]
order_rows = pd.json_normalize(orders)

Dit levert twee rijen en vier kolommen op: order_id, items, customer.name en customer.country. De geneste klantvelden worden kolommen met namen waarin punten staan. De artikellijsten blijven in cellen; normalisatie zet niet automatisch elke lijst om in rijen.

Vouw een lijst uit met informatie van het bovenliggende object

items = pd.json_normalize(
    orders,
    record_path="items",
    meta=["order_id", ["customer", "name"]]
)

record_path kiest de lijst waarvan de elementen rijen worden. meta kopieert waarden van het bovenliggende object naar elke rij, met een lijst van sleutels voor een genest pad. Het resultaat heeft drie artikelrijen: twee voor Ana's bestelling en één voor die van Ben. De omzet is aantal maal prijs: 7,0; 10,0 en 14,0, samen 31,0.

Als de verzendkosten op bestelniveau 4,00 zijn, worden ze op beide artikelrijen van bestelling 501 herhaald. Als je die herhaalde kosten optelt, krijg je 8,00 voor één bestelling. Bewaar bedragen op bestelniveau in een aparte bestellingentabel als je ook een artikelentabel nodig hebt; behoud order_id om ze te koppelen.

Bepaal namen en verwerk ontbrekende velden

sep="_" maakt namen zoals customer_name. record_prefix="item_" onderscheidt artikelvelden van velden met dezelfde naam in het bovenliggende object. max_level=0 laat geneste dictionaries intact.

Een gewoon genest veld dat bij één record ontbreekt, wordt een ontbrekende waarde in de uitvoerkolom. Een ontbrekend veld dat via meta wordt opgevraagd, geeft standaard KeyError; errors="ignore" staat ontbrekende metadata toe en vult die met NaN. Een ontbrekende lijst die door record_path wordt aangeduid, moet nog steeds worden gecorrigeerd.

Haal API-antwoorden uit hun omhulsel vóór het omzetten

Een API kan een omsluitend object met count, next en results teruggeven. Geef data["results"] door aan pd.json_normalize om de records om te zetten naar een platte tabel. Als je het omsluitende object zelf doorgeeft, wordt één omhullend object genormaliseerd en blijft de resultatenlijst in een cel staan. Houd pagineringsmetadata beschikbaar om latere pagina's op te halen, maar maak de analysetabel uit de werkelijke recordlijst.

Een web-API ontvangt een HTTP-verzoek bij een eindpunt en geeft een statuscode, headers en een berichtinhoud terug. Veel API's gebruiken JSON als berichtinhoud, maar een succesvol ontvangen antwoord betekent niet dat het de gegevens of alle benodigde records bevat.

Verstuur parameters en controleer het antwoord

import requests

resp = requests.get(
    url,
    params={"city": "Lima", "units": "metric"},
    timeout=10
)
resp.raise_for_status()
data = resp.json()
df = pd.json_normalize(data["results"])

Hier is url het gedocumenteerde eindpunt van de API. params codeert de querytekenreeks, zodat spaties en speciale tekens in waarden correct worden verwerkt. Requests heeft standaard geen wachttijdlimiet. Eén waarde voor de wachttijdlimiet bepaalt de wachttijd voor verbinden en lezen; het is geen uiterste tijd voor het downloaden van het volledige antwoord.

Roep raise_for_status() aan voordat je de berichtinhoud gebruikt. Bij 4xx- en 5xx-antwoorden geeft de methode een HTTP-fout. Een JSON-foutmelding kan met succes worden ingelezen en toch een mislukt verzoek beschrijven; omgekeerd kan een 200-antwoord tekst bevatten die geen JSON is, waardoor resp.json() mislukt. Inspecteer resp.text als het formaat van het antwoord onverwacht is.

Houd toegangsgegevens apart

Gebruik de authenticatiemethode die de API documenteert. Lees voor een bearer-token een sleutel uit een omgevingsvariabele en stuur die in een header:

import os

key = os.environ["WEATHER_API_KEY"]
headers = {"Authorization": "Bearer " + key}

Houd sleutels buiten opgeslagen code en notebooks. Als een sleutel is gedeeld of aan versiebeheer is toegevoegd, trek die dan in en vervang die. Een sleutel geeft toegang; een getoonde waarde later verbergen maakt het bekend worden niet ongedaan.

Ga door totdat alle pagina's zijn ingelezen

Volg de gedocumenteerde methode van de API voor de volgende pagina, of die nu paginanummers, offsets of een URL voor de volgende pagina gebruikt. Verzamel de records van elke pagina en stop bij de opgegeven eindvoorwaarde. Een totaal van 230 records met 100 per pagina vereist pagina's van 100, 100 en 30. De eerste pagina kan volledig geldig zijn terwijl de dataset onvolledig is.

Vergelijk het verzamelde aantal met een gerapporteerd totaal als dat beschikbaar is. Houd je aan verzoeklimieten: 429 vraagt om wachten vóór een volgend verzoek en Retry-After kan de wachttijd opgeven. Die header kan seconden of een HTTP-datum bevatten. Sla ruwe antwoorden op voor reproduceerbare analyse en om te voorkomen dat je bij elke nieuwe uitvoering dezelfde gegevens downloadt.

Herken andere formaten voor webtabellen

pd.read_html(url) geeft een lijst met DataFrames terug, één voor elke passende HTML-tabel. match="Population" beperkt tabellen op basis van hun tekst. De functie heeft een afhankelijkheid voor het verwerken van HTML nodig, zoals lxml of BeautifulSoup met html5lib. pd.read_xml leest herhaalde XML-elementen als rijen met lxml of parser="etree". Controleer de voorwaarden van een site voordat je gegevens verzamelt en geef de voorkeur aan een officiële download of API als die beschikbaar is.

Een CSV-export moet de waarden behouden die de ontvanger nodig heeft en de gebruikte conventies duidelijk maken. Kies of de rij-index gegevens bevat, hoe ontbrekende waarden verschijnen en of de uitvoer bedoeld is voor precieze analyse of afgeronde weergave.

Kies wat een kolom wordt

df.to_csv("weather_processed.csv", index=False)

Standaard wordt de index geschreven. Voor een tabel met een gewone genummerde index voegt dit een naamloos eerste veld toe; een latere read_csv kan dat tonen als "Unnamed: 0". index=False laat die rijnummers weg. Als de index betekenisvolle labels bevat, behoud die dan en lees de index opnieuw in met index_col=0.

Ontbrekende waarden worden normaal lege velden. na_rep="NA" maakt ze zichtbaar, maar de ontvangende leesfunctie moet die markering correct interpreteren. In een stedentabel met Lyon op 21,5 °C en Osaka op 18,25 °C moet een ontbrekende neerslagwaarde voor Osaka onderscheiden blijven van nul neerslag.

Stem af op de tekstconventie van de ontvanger

df.to_csv(
    "weather_export.csv",
    index=False,
    sep=";",
    decimal=",",
    na_rep="NA",
    date_format="%Y-%m-%d",
    encoding="utf-8"
)

De opties voor het scheidingsteken en decimaalteken leveren waarden op zoals Lyon;21,5;0,0. ISO-datumuitvoer houdt dag en maand ondubbelzinnig. Gebruik encoding="utf-8-sig" als een ontvangend spreadsheetprogramma een BOM nodig heeft om UTF-8 te herkennen.

float_format="%.1f" schrijft één decimaal. De waarde 18,25 wordt bij deze opmaak "18.2" en de verloren precisie kan niet uit de CSV worden teruggehaald. Behoud volledige precisie voor analysegegevens; maak zo nodig een apart afgerond rapport.

Controleer wat behouden blijft bij opslaan en opnieuw inlezen

CSV slaat tekens op zonder metadata over pandas-datatypes. Bekijk vier kolommen: een identificatiecode "02139", een datum-tijdwaarde, een geordende categorische variabele A < B < C en gehele getallen met ondersteuning voor ontbrekende waarden en een ontbrekende waarde. Bij standaard inlezen van CSV kun je het gehele getal 2139, datumtekst, gewone categorielabels zonder hun volgorde en drijvendekommagetallen voor de tellingen terugkrijgen.

Als het inlezen slaagt, betekent dat dus niet noodzakelijk dat het oorspronkelijke DataFrame is hersteld. Bewaar de opties die nodig zijn om de gegevens te reconstrueren, waaronder tekstuele identificatiecodes, het inlezen van datums en markeringen voor ontbrekende waarden. Ook de categorievolgorde moet opnieuw worden gedefinieerd. Voor herhaalde analyse waarbij deze types belangrijk zijn, kan Parquet ze direct behouden.

Voeg records toe en bescherm ruwe invoer

df.to_csv(
    "daily_results.csv",
    mode="a",
    header=False,
    index=False
)

Dit voegt rijen toe aan een bestaand bestand. Houd de kolomvolgorde en conventies consistent met dat bestand. Met header=True schrijft een toevoeging nog een kopregel in het midden en kan de volgende leesfunctie die als record behandelen. Schrijf bij een nieuw bestand de kopregel één keer voordat je later rijen toevoegt.

Bewaar ontvangen of gedownloade bestanden ongewijzigd op een locatie voor ruwe gegevens. Schrijf afgeleide resultaten afzonderlijk onder beschrijvende namen. Controleer bij het opnieuw openen van een verwerkte export het aantal rijen, de kolommen, ontbrekende waarden en representatieve waarden, waaronder voorloopnullen en datums.

Het beste opslagformaat hangt af van wie de gegevens hierna leest en wat bij de uitwisseling behouden moet blijven. Een tabel voor een collega, een genest API-antwoord en een analysedataset met vastgelegde types hebben verschillende behoeften.

Vergelijk tekstuele en binaire opslag

Tekstformaten coderen zichtbare tekens. CSV is gemakkelijk te inspecteren en wordt breed ondersteund; JSON geeft geneste objecten en arrays op natuurlijke wijze weer. CSV heeft geen schema met kolomtypes en gewone JSON-waardetypes behouden niet elk pandas-datatype. Opnieuw inlezen vereist verwerking van de tekst en kan expliciete typekeuzes nodig maken.

Binaire formaten coderen gegevens zodat software die rechtstreeks kan lezen. Formaten zoals Parquet en Feather slaan een schema op dat kolommen en types beschrijft, waardoor het minder nodig is types opnieuw af te leiden. Ondersteuning voor types hangt nog steeds af van het formaat en de leesfunctie: willekeurige Python-objecten worden niet zomaar uitwisselbaar omdat het bestand binair is.

Een rijgeoriënteerde indeling houdt de velden van een record bij elkaar. Een kolomgeoriënteerde indeling houdt waarden uit dezelfde kolom bij elkaar. Bij analyse zijn vaak enkele kolommen van veel rijen nodig, zodat kolomgeoriënteerde leesfuncties onnodige kolommen kunnen overslaan. Vergelijkbare aangrenzende waarden laten zich ook goed comprimeren. Bestandsgrootte en snelheid hangen af van de gegevens; een compressieresultaat voor één tabel is geen vaste verhouding voor alle tabellen.

Kies voor elke taak een passend formaat

Parquet is een open formaat dat wordt gebruikt door pandas, R, Spark en DuckDB. Feather gebruikt Arrow IPC en is handig voor snelle uitwisseling tussen Python en R of tussen lokale stappen. to_feather en read_feather bieden die mogelijkheid. HDF5 groepeert meerdere datasets in één bestand; to_hdf van pandas vereist PyTables.

Begrijp de vertrouwensgrens van pickle

pickle kan Python-objecten buiten gewone tabellen opslaan, maar bij het inlezen kan code worden uitgevoerd. Lees nooit een pickle van een onbetrouwbare bron in. Gebruik het voor je eigen tijdelijke objecten en verwacht compatibiliteitsbeperkingen als Python en bibliotheken veranderen. Zo ondersteunt pandas 3 het lezen van pickles die met pandas-versies van vóór 1.0 zijn gemaakt niet meer.

Beslis op basis van het gewenste resultaat

Als een ontvanger een kleine tabel zonder speciale hulpmiddelen moet inspecteren, is CSV praktisch. Gebruik Excel als de ontvanger benoemde werkbladen nodig heeft. Kies Parquet als je identificatiecodes, categorieën en types met ondersteuning voor ontbrekende waarden tussen analysesessies moet behouden. Als meerdere programma's gedeelde records moeten bevragen en bijwerken, past een database beter dan kopieën van een bestand rondsturen. De formaatkeuze volgt uit het volgende gebruik, niet uit de extensie van de oorspronkelijke invoer.

Parquet slaat een tabel met de kolomtypes op in een open, kolomgeoriënteerd formaat. Dit is handig wanneer een gecontroleerd DataFrame herhaaldelijk wordt ingelezen of aan andere analysehulpmiddelen wordt doorgegeven. pandas gebruikt PyArrow voor de onderstaande voorbeelden.

Schrijf en controleer een tabel met vastgelegde types

df.to_parquet("sales.parquet", engine="pyarrow")
restored = pd.read_parquet("sales.parquet", engine="pyarrow")
print(restored.dtypes)

Een tekstuele identificatiecode "02139", een datum-tijdkolom, een geordende categorische variabele en gehele getallen met ondersteuning voor ontbrekende waarden kunnen bij deze opslag van pandas via PyArrow en terug naar pandas allemaal met hun types behouden blijven. Anders dan bij het inlezen van CSV hoeft pandas de functie van de identificatiecode niet te raden of de categorievolgorde opnieuw te maken. Inspecteer types en representatieve waarden wanneer je een nieuwe schrijf- of leesfunctie gaat gebruiken.

De standaardinstelling index=None slaat een RangeIndex compact op als metadata. Een andere index wordt als kolommen geschreven en bij het inlezen hersteld. Gebruik index=False als de index niet nodig is. Die keuze gaat over rijlabels, los van de gewone kolommen van de tabel.

Lees minder in en kies compressie

small = pd.read_parquet(
    "sales.parquet",
    columns=["zip", "amount"]
)

De leesfunctie kan alleen die kolommen uit de opslag ophalen. Dat verschilt van de volledige tabel inlezen en daarna selecteren: dan heb je de volledige leestijd al besteed. Kolomselectie is vooral handig voor brede tabellen.

Snappy is de standaardcompressiecodec. compression="zstd" of "gzip" kost vaak meer schrijfwerk maar levert kleinere bestanden op, terwijl compression=None ongecomprimeerde gegevens schrijft. Meet de afweging met representatieve gegevens; herhaalde labels en willekeurige metingen worden niet op dezelfde manier gecomprimeerd. Installeer PyArrow; de alternatieve fastparquet-engine is in pandas 3.1 verouderd.

Deel een dataset in partities in

df.to_parquet(
    "sales_dataset",
    engine="pyarrow",
    partition_cols=["year"],
    index=False
)
recent = pd.read_parquet(
    "sales_dataset",
    filters=[("year", "==", 2026)]
)

De bestemming is een map met submappen zoals year=2025 en year=2026. Als je de map inleest, wordt de dataset geladen; een filter kan niet-relevante partities overslaan. Bij deze indeling leidt PyArrow de waarden voor year af uit mapnamen en ontvangt pandas de partitiekolom doorgaans als categorische kolom.

Kies een partitiekolom met een kleine verzameling bruikbare waarden waarop je vaak filtert. Een unieke record-ID maakt duizenden kleine partities, wat meer werk voor bestanden en mappen oplevert. Een jaar of een kleine verzameling regio's biedt vaak een praktischere indeling.

Voeg gegevens toe zonder de dataset te beschadigen

Eén Parquet-bestand ondersteunt via pandas geen toevoeging van rijen zoals CSV. Schrijf nieuwe bestanden of partities naar de datasetmap, of lees, combineer en herschrijf één bestand. Bestanden in dezelfde dataset hebben compatibele gegevensschema's nodig. Als het ene bestand een code als tekst opslaat en het andere als geheel getal, kan het inlezen mislukken of kunnen waarden worden geconverteerd. Stel consistente datatypes in voordat je elk deel schrijft en controleer of een toegevoegde partitie geen overlappende kopieën van dezelfde records maakt.

Een relationele database slaat records op in tabellen met benoemde kolommen. Een programma verstuurt een SQL-query via een verbinding en ontvangt een resultaat dat pandas kan omzetten in een DataFrame. De database kan alleen de benodigde gegevens selecteren voordat ze naar Python worden verstuurd.

Begin met een SQLite-bestand

import sqlite3
import pandas as pd

con = sqlite3.connect("shop.db")
try:
    df = pd.read_sql_query(
        "SELECT region, amount FROM sales", con
    )
finally:
    con.close()

SQLite werkt zonder afzonderlijke server en slaat een database op in een bestand. Bij het verbinden wordt het bestand aangemaakt als het niet bestaat, dus een verkeerd getypt pad kan een nieuwe, lege database openen in plaats van de bedoelde. ":memory:" maakt een tijdelijke database in het geheugen. De bovenstaande query geeft de kolommen region en amount uit een bestaande tabel sales terug; de kolomnamen van het resultaat worden DataFrame-labels.

Een with-blok van een SQLite-verbinding beheert een transactie, maar sluit de verbinding niet. Roep expliciet close() aan als je klaar bent. Een try/finally-blok sluit de verbinding ook als het inlezen een fout geeft.

Gebruik een engine voor een serverdatabase

SQLAlchemy biedt engines voor systemen zoals PostgreSQL, MySQL en SQL Server, met een bijbehorend geïnstalleerd stuurprogramma. Een verbindings-URL geeft het dialect, stuurprogramma, de server en database aan. Bewaar die URL in een omgevingsvariabele:

import os
from sqlalchemy import create_engine

engine = create_engine(os.environ["ANALYSIS_DB_URL"])
try:
    with engine.connect() as conn:
        df = pd.read_sql_query(
            "SELECT region, amount FROM sales", conn
        )
finally:
    engine.dispose()

De verbindingscontext geeft de verbinding terug aan de verbindingenpool van de engine. dispose() geeft de middelen in de pool vrij wanneer de engine niet meer nodig is. Gebruik voor analyse een account met alleen leesrechten en houd toegangsgegevens buiten notebooks en versiebeheer. Een engine-URL voor een lokaal SQLite-bestand kan "sqlite:///shop.db" zijn.

Kies de leesfunctie die bij de invoer past

Geef bij een gewone sqlite3-verbinding een volledige query door. pd.read_sql("sales", con) verstuurt sales als SQL en mislukt; gebruik in plaats daarvan pd.read_sql_query("SELECT * FROM sales", con). pandas ondersteunt SQLAlchemy-, ADBC- en SQLite-verbindingen; een willekeurige rechtstreekse verbinding via een stuurprogramma is geen ondersteund alternatief enkel omdat het stuurprogramma SQL kan uitvoeren.

Verplaats het resultaat dat je nodig hebt

Een query die geselecteerde rijen en kolommen teruggeeft, draagt minder gegevens over dan een hele tabel inlezen en het grootste deel in pandas weggooien. De gegeven query SELECT SUM(amount) AS total FROM sales geeft één aggregatiewaarde terug, met het label total. Het inlezen van een queryresultaat verandert de opgeslagen tabel niet. Controleer na het inlezen het aantal rijen en de types, net als bij een bestand; de gedeclareerde databasetypes en de teruggegeven pandas-types hangen samen maar zijn niet identiek.

Veranderende waarden horen in queryparameters. De SQL-instructie bepaalt de bewerking; gebonden parameters leveren de regio, grenswaarde of andere waarde die voor deze uitvoering wordt gebruikt. Zo blijft de querystructuur behouden, ook als een waarde een aanhalingsteken bevat.

Bind waarden met de syntaxis van de verbinding

Voor SQLite:

query = "SELECT region, amount, sold_on FROM sales WHERE amount > ? ORDER BY amount DESC"
df = pd.read_sql_query(query, con, params=(70,))

Voor de verkoopbedragen 120,0, 75,5, 60,0 en 210,0 geeft dit 210,0, 120,0 en 75,5 terug in aflopende volgorde. De tuple (70,) heeft één element; (70) is alleen het getal 70. SQLite accepteert ook benoemde plaatsaanduidingen, bijvoorbeeld WHERE region = :r met params={"r": "North"}.

De regels voor plaatsaanduidingen hangen af van de interface. psycopg gebruikt %s of %(name)s. Met SQLAlchemy plaats je een instructie in text en gebruik je benoemde parameters:

from sqlalchemy import text

query = text("SELECT region, amount FROM sales WHERE amount >= :m")
with engine.connect() as conn:
    df = pd.read_sql_query(query, conn, params={"m": 100})

Geef waarden door via params; gebruik geen Python-opmaak om ze in de instructie in te voegen.

Begrijp waartegen parametrisering beschermt

Stel dat code een voorwaarde bouwt met een f-string en de invoer "x' OR '1'='1". Als je die tussen aanhalingstekens plakt, verandert de voorwaarde in region = 'x' OR '1'='1', die op elke rij van toepassing is. Dit is SQL-injectie: een waarde is uitvoerbare querystructuur geworden.

Een gebonden parameter wordt als één waarde vergeleken, zodat dezelfde tekenreeks alleen overeenkomt met een regio die letterlijk die tekst heeft. Binden verwerkt ook gewone namen met apostroffen zonder dat je zelf escapes voor aanhalingstekens hoeft te maken. De regel geldt voor invoer uit bestanden én uit gebruikersformulieren.

Parameters vertegenwoordigen waarden, geen tabel- of kolomnamen. Een parameter op de plaats van een tabelnaam selecteert die tabel niet. Als een programma een variabele identificatie nodig heeft, kies die dan uit een vaste lijst die door de code wordt beheerd.

Bepaal de types in het resultaat

SQLite slaat datums vaak op als tekst. Vraag pandas om ze als datums in te lezen:

df = pd.read_sql_query(
    "SELECT sold_on, visits FROM observations", con,
    parse_dates=["sold_on"],
    dtype={"visits": "Int64"}
)

De datumkolom krijgt datum-tijdwaarden en een telling met SQL NULL gebruikt gehele getallen met ondersteuning voor ontbrekende waarden, in plaats van alleen daarvoor drijvendekommagetallen te worden. Inspecteer het resultaat om de conversie te controleren.

Onderscheid gegevensblokken van buffering door het stuurprogramma

chunksize=1000 geeft een iterator van DataFrames terug die elk maximaal 1.000 rijen bevatten. Een resultaat van vier rijen geeft met chunksize=3 delen van drie en één rij. Houd de verbinding open terwijl je ze verwerkt. Sommige databasestuurprogramma's bufferen nog steeds het hele resultaat voordat pandas blokken oplevert; een cursor aan de serverzijde of een streaminginstelling kan ook nodig zijn om het geheugenverbruik over het volledige verbindingstraject te beperken.

to_sql maakt een databasetabel uit een DataFrame of schrijft rijen naar een bestaande tabel. De opties bepalen of bestaande gegevens behouden blijven, of de index een kolom wordt en hoe een groep schrijfbewerkingen wordt bevestigd.

Kies het gedrag bij een bestaande tabel

df.to_sql("sales", con, index=False)

De standaardinstelling if_exists="fail" stopt als sales al bestaat. Kies alleen een andere modus als het effect past bij de bedoelde invoer:

delete_rows is beschikbaar in pandas 3. Een tabel vervangen verwijdert de oude definitie, inclusief sleutels, indexen en beperkingen; ook databasespecifieke rechten kunnen worden beïnvloed. Rijen verwijderen behoudt de definitie, maar wist nog steeds elk bestaand record. Gebruik dit als je de tabel volledig opnieuw wilt vullen, niet als het DataFrame alleen een nieuwe groep records bevat.

Stel kolommen in en schrijf binnen een transactie

Standaard wordt de DataFrame-index als kolom geschreven. Een naamloze index wordt index; een benoemde index behoudt zijn naam. index_label geeft de index een expliciete naam en index=False sluit die uit. Als een ID al een gewone kolom is, voegt het schrijven van standaardrijnummers meestal geen bruikbare informatie toe.

Met SQLAlchemy kan dtype databasetypes kiezen:

from sqlalchemy import types

with engine.begin() as conn:
    df.to_sql(
        "sales", conn,
        if_exists="append",
        index=False,
        dtype={"sold_on": types.Date()},
        chunksize=1000
    )

engine.begin() bevestigt de transactie bij succesvolle afsluiting en draait die terug bij een uitzondering. Voor een bestaande tabel bepaalt het opgeslagen gegevensschema nog steeds welke waarden kunnen worden ingevoegd; dtype is geen opdracht om de kolommen opnieuw te ontwerpen. Transactiegaranties hangen ook af van de ondersteuning van de database voor de gebruikte bewerkingen. Toevoegen binnen een SQLAlchemy-transactie houdt de invoegbewerking van het voorbeeld bij elkaar.

chunksize groepeert rijen in partijen. method="multi" plaatst meerdere rijen in één INSERT-instructie waar dat wordt ondersteund. Dit kan de prestaties verbeteren of verslechteren, afhankelijk van de database en partijgrootte, dus meet dit met representatieve gegevens.

Controleer de groei, niet alleen de voltooiing

check = pd.read_sql_query("SELECT COUNT(*) AS n FROM sales", con)
print(check["n"].iloc[0])

Vergelijk voor een nieuwe of volledig opnieuw gevulde tabel het aantal met len(df). Vergelijk bij toevoegen de toename: een tabel met vier rijen die twee rijen erbij krijgt, moet er zes bevatten. Het aantal rijen dat to_sql teruggeeft, komt uit de rapportage van het stuurprogramma; controleer de opgeslagen gegevens rechtstreeks.

Als je toevoegen twee keer uitvoert, worden de records herhaald, tenzij de database duplicaten afwijst of het programma alleen nieuwe records selecteert. Bepaal voordat je de bewerking opnieuw uitvoert of het gaat om een tabel volledig opnieuw vullen of het toevoegen van nieuwe records. Een transactie voorkomt een gedeeltelijke invoer bij een fout; die maakt herhaald succesvol toevoegen niet uniek.