Opérations d’E/S de DataStore

Lecture et écriture de données avec DataStore - tous les formats et toutes les destinations pris en charge

DataStore prend en charge la lecture à partir de diverses sources de données et de divers formats de fichier, ainsi que l’écriture vers ceux-ci.

​

Lecture de données

​

Fichiers CSV

read_csv(filepath_or_buffer, sep=',', header='infer', names=None, 
         usecols=None, dtype=None, nrows=None, skiprows=None,
         compression=None, encoding=None, **kwargs)

Exemples :

from chdb import datastore as pd

# Basic CSV read
ds = pd.read_csv("data.csv")

# With options
ds = pd.read_csv(
    "data.csv",
    sep=";",                    # Custom delimiter
    header=0,                   # Header row index
    names=['a', 'b', 'c'],      # Custom column names
    usecols=['a', 'b'],         # Only read specific columns
    dtype={'a': 'Int64'},       # Specify dtypes
    nrows=1000,                 # Read only first 1000 rows
    skiprows=1,                 # Skip first row
    compression='gzip',         # Compressed file
    encoding='utf-8'            # Encoding
)

# From URL
ds = pd.read_csv("https://example.com/data.csv")

​

Fichiers Parquet

Recommandé pour les grands jeux de données - format en colonnes avec une meilleure compression.

read_parquet(path, columns=None, **kwargs)

Exemples :

# Basic Parquet read
ds = pd.read_parquet("data.parquet")

# Read specific columns only (efficient - only reads needed data)
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2', 'col3'])

# From S3
ds = pd.read_parquet("s3://bucket/data.parquet")

​

Fichiers JSON

read_json(path_or_buf, orient=None, lines=False, **kwargs)

Exemples :

# Standard JSON
ds = pd.read_json("data.json")

# JSON Lines (newline-delimited)
ds = pd.read_json("data.jsonl", lines=True)

# JSON with specific orientation
ds = pd.read_json("data.json", orient='records')

​

Fichiers Excel

read_excel(io, sheet_name=0, header=0, names=None, **kwargs)

Exemples :

# Read first sheet
ds = pd.read_excel("data.xlsx")

# Read specific sheet
ds = pd.read_excel("data.xlsx", sheet_name="Sheet1")
ds = pd.read_excel("data.xlsx", sheet_name=2)  # Third sheet

# Read multiple sheets (returns dict)
sheets = pd.read_excel("data.xlsx", sheet_name=['Sheet1', 'Sheet2'])

​

Bases de données SQL

read_sql(sql, con, **kwargs)

Exemples :

# Read from SQL query
ds = pd.read_sql("SELECT * FROM users", connection)
ds = pd.read_sql("SELECT * FROM orders WHERE date > '2024-01-01'", connection)

​

Autres formats

# Feather (Arrow)
ds = pd.read_feather("data.feather")

# ORC
ds = pd.read_orc("data.orc")

# Pickle
ds = pd.read_pickle("data.pkl")

# Fixed-width formatted
ds = pd.read_fwf("data.txt", widths=[10, 20, 15])

# HTML tables
ds = pd.read_html("https://example.com/table.html")[0]

---

​

Écriture de données

​

to_csv

Exporte au format CSV.

to_csv(path_or_buf=None, sep=',', na_rep='', header=True, 
       index=True, mode='w', compression=None, **kwargs)

Exemples :

ds = pd.read_parquet("data.parquet")

# Basic export
ds.to_csv("output.csv")

# With options
ds.to_csv(
    "output.csv",
    sep=";",                    # Custom delimiter
    index=False,                # Don't include index
    header=True,                # Include header
    na_rep='NULL',              # Represent NaN as 'NULL'
    compression='gzip'          # Compress output
)

# To string
csv_string = ds.to_csv()

​

to_parquet

Exporter au format Parquet (recommandé pour les volumes de données importants).

to_parquet(path, engine='pyarrow', compression='snappy', **kwargs)

Exemples :

# Basic export
ds.to_parquet("output.parquet")

# With compression options
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')

# Partitioned output
ds.to_parquet(
    "output/",
    partition_cols=['year', 'month']
)

​

to_json

Exporter au format JSON.

to_json(path_or_buf=None, orient='records', lines=False, **kwargs)

Exemples :

# Standard JSON (array of records)
ds.to_json("output.json", orient='records')

# JSON Lines (one JSON object per line)
ds.to_json("output.jsonl", lines=True)

# Different orientations
ds.to_json("output.json", orient='split')    # {columns, data, index}
ds.to_json("output.json", orient='records')  # [{col: val}, ...]
ds.to_json("output.json", orient='columns')  # {col: {idx: val}}

# To string
json_string = ds.to_json()

​

to_excel

Exporte au format Excel.

to_excel(excel_writer, sheet_name='Sheet1', index=True, **kwargs)

Exemples :

# Single sheet
ds.to_excel("output.xlsx")
ds.to_excel("output.xlsx", sheet_name="Data", index=False)

# Multiple sheets
with pd.ExcelWriter("output.xlsx") as writer:
    ds1.to_excel(writer, sheet_name="Sales")
    ds2.to_excel(writer, sheet_name="Inventory")

​

to_sql

Exporter vers une base de données SQL ou générer une chaîne de caractères SQL.

to_sql(name=None, con=None, schema=None, if_exists='fail', **kwargs)

Exemples :

# Generate SQL query (no execution)
sql = ds.to_sql()
print(sql)
# SELECT ...
# FROM ...
# WHERE ...

# Write to database
ds.to_sql("table_name", connection, if_exists='replace')

​

Autres méthodes d’exportation

# To pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# To Arrow Table
table = ds.to_arrow()

# To NumPy array
arr = ds.to_numpy()

# To dictionary
d = ds.to_dict()
d = ds.to_dict(orient='records')  # List of dicts
d = ds.to_dict(orient='list')     # Dict of lists

# To records (list of tuples)
records = ds.to_records()

# To string
s = ds.to_string()
s = ds.to_string(max_rows=100)

# To Markdown
md = ds.to_markdown()

# To HTML
html = ds.to_html()

# To LaTeX
latex = ds.to_latex()

# To clipboard
ds.to_clipboard()

# To pickle
ds.to_pickle("output.pkl")

# To feather
ds.to_feather("output.feather")

---

​

Comparaison des formats de fichier

Format	Vitesse de lecture	Vitesse d’écriture	Taille du fichier	Schéma	Idéal pour
Parquet	Rapide	Rapide	Petite	Oui	Grands jeux de données, analyses
CSV	Moyenne	Rapide	Grande	Non	Compatibilité, données simples
JSON	Lente	Moyenne	Grande	Partiel	API, données imbriquées
Excel	Lente	Lente	Moyenne	Partiel	Partage avec des utilisateurs non techniques
Feather	Très rapide	Très rapide	Moyenne	Oui	Inter-processus, pandas

​

Recommandations

1. Pour les charges de travail d’analyse : utilisez Parquet

   • Le format colonnaire permet de ne lire que les colonnes nécessaires
   • Excellente compression
   • Préserve les types de données

2. Pour l’échange de données : utilisez CSV ou JSON

   • Compatibilité universelle
   • Facilement lisible

3. Pour l’interopérabilité avec pandas : utilisez Feather ou Arrow

   • Sérialisation la plus rapide
   • Préserve les types

---

​

Prise en charge de la compression

​

Lecture de fichiers compressés

# Auto-detect from extension
ds = pd.read_csv("data.csv.gz")
ds = pd.read_csv("data.csv.bz2")
ds = pd.read_csv("data.csv.xz")
ds = pd.read_csv("data.csv.zst")

# Explicit compression
ds = pd.read_csv("data.csv", compression='gzip')

​

Écriture de fichiers compressés

# CSV with compression
ds.to_csv("output.csv.gz", compression='gzip')
ds.to_csv("output.csv.bz2", compression='bz2')

# Parquet (always compressed)
ds.to_parquet("output.parquet", compression='snappy')  # Default
ds.to_parquet("output.parquet", compression='gzip')
ds.to_parquet("output.parquet", compression='zstd')    # Best ratio
ds.to_parquet("output.parquet", compression='lz4')     # Fastest

​

Options de compression

Compression	Vitesse	Ratio	Cas d’utilisation
snappy	Très rapide	Faible	Par défaut pour Parquet
lz4	Très rapide	Faible	Priorité à la vitesse
gzip	Moyenne	Élevé	Compatibilité
zstd	Rapide	Très élevé	Meilleur compromis
bz2	Lente	Très élevé	Compression maximale

---

​

E/S en streaming

Pour les fichiers très volumineux qui ne tiennent pas en mémoire :

​

Lecture fragmentée

# Read in chunks
for chunk in pd.read_csv("large.csv", chunksize=100000):
    # Process each chunk
    process(chunk)

# Using iterator
reader = pd.read_csv("large.csv", iterator=True)
chunk = reader.get_chunk(10000)

​

Utiliser ClickHouse Streaming

from chdb.datastore import DataStore

# Stream from file without loading all into memory
ds = DataStore.from_file("huge.parquet")

# Operations are lazy - only computes what's needed
result = ds.filter(ds['amount'] > 1000).head(100)

---

​

Sources de données distantes

​

HTTP/HTTPS

# Read from URL
ds = pd.read_csv("https://example.com/data.csv")
ds = pd.read_parquet("https://example.com/data.parquet")

​

S3

from chdb.datastore import DataStore

# Anonymous access
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# With credentials
ds = DataStore.from_s3(
    "s3://bucket/data.parquet",
    access_key_id="KEY",
    secret_access_key="SECRET"
)

​

GCS, Azure, HDFS

Consultez les méthodes de fabrique pour connaître les options de stockage dans le cloud.

---

​

Bonnes pratiques

​

1. Utilisez Parquet pour les fichiers volumineux

# Convert CSV to Parquet for better performance
ds = pd.read_csv("large.csv")
ds.to_parquet("large.parquet")

# Future reads are much faster
ds = pd.read_parquet("large.parquet")

​

2. Sélectionnez uniquement les colonnes nécessaires

# Efficient - only reads col1 and col2
ds = pd.read_parquet("data.parquet", columns=['col1', 'col2'])

# Inefficient - reads all columns then filters
ds = pd.read_parquet("data.parquet")[['col1', 'col2']]

​

3. Utiliser la compression

# Smaller file size, usually faster due to less I/O
ds.to_parquet("output.parquet", compression='zstd')

​

4. Écritures par lots

# Write once, not in a loop
result = process_all_data(ds)
result.to_parquet("output.parquet")

# NOT this (inefficient)
for chunk in chunks:
    chunk.to_parquet(f"output_{i}.parquet")