Principales différences avec pandas

Différences importantes entre DataStore et pandas

Bien que DataStore soit largement compatible avec pandas, il existe d’importantes différences à connaître.

​

Tableau récapitulatif

Aspect	pandas	DataStore
Exécution	Eager (immédiat)	Lazy (différé)
Types de retour	DataFrame/Series	DataStore/ColumnExpr
Ordre des lignes	Préservé	Préservé (automatique) ; non garanti en mode performance
inplace	Pris en charge	Non pris en charge
Index	Prise en charge complète	Simplifié
Mémoire	Toutes les données en mémoire	Données conservées à la source

---

​

1. Exécution différée vs immédiate

​

pandas (Exécution immédiate)

Les opérations s’exécutent immédiatement :

import pandas as pd

df = pd.read_csv("data.csv")  # Loads entire file NOW
result = df[df['age'] > 25]   # Filters NOW
grouped = result.groupby('city')['salary'].mean()  # Aggregates NOW

​

DataStore (différé)

Les opérations sont reportées jusqu’au moment où les résultats sont nécessaires :

from chdb import datastore as pd

ds = pd.read_csv("data.csv")  # Just records the source
result = ds[ds['age'] > 25]   # Just records the filter
grouped = result.groupby('city')['salary'].mean()  # Just records

# Execution happens here:
print(grouped)        # Executes when displaying
df = grouped.to_df()  # Or when converting to pandas

​

Pourquoi c’est important

L’exécution différée permet :

• Optimisation des requêtes : plusieurs opérations sont compilées en une seule requête SQL
• Élagage des colonnes : seules les colonnes nécessaires sont lues
• Pushdown des filtres : les filtres sont appliqués à la source
• Utilisation efficace de la mémoire : ne chargez pas les données dont vous n’avez pas besoin

---

​

2. Types de retour

​

pandas

df['col']           # Returns pd.Series
df[['a', 'b']]      # Returns pd.DataFrame
df[df['x'] > 10]    # Returns pd.DataFrame
df.groupby('x')     # Returns DataFrameGroupBy

​

DataStore

ds['col']           # Returns ColumnExpr (lazy)
ds[['a', 'b']]      # Returns DataStore (lazy)
ds[ds['x'] > 10]    # Returns DataStore (lazy)
ds.groupby('x')     # Returns LazyGroupBy

​

Conversion en types pandas

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

# Get pandas Series from column
series = ds['col'].to_pandas()

# Or trigger execution
print(ds)  # Automatically converts for display

---

​

3. Déclencheurs d’exécution

DataStore s’exécute lorsque vous avez besoin de valeurs effectives :

Déclencheur	Exemple	Remarques
print() / repr()	print(ds)	L’affichage nécessite les données
len()	len(ds)	Nécessite de connaître le nombre de lignes
.columns	ds.columns	Nécessite les noms de colonnes
.dtypes	ds.dtypes	Nécessite les informations de type
.shape	ds.shape	Nécessite les dimensions
.values	ds.values	Nécessite les données réelles
.index	ds.index	Nécessite l’index
to_df()	ds.to_df()	Conversion explicite
Itération	for row in ds	Nécessite une itération
equals()	ds.equals(other)	Nécessite une comparaison

​

Opérations qui restent en exécution différée

Opération	Renvoie
filter()	DataStore
select()	DataStore
sort()	DataStore
groupby()	LazyGroupBy
join()	DataStore
ds['col']	ColumnExpr
ds[['a', 'b']]	DataStore
ds[condition]	DataStore

---

​

4. Ordre des lignes

​

pandas

L’ordre des lignes est toujours conservé :

df = pd.read_csv("data.csv")
print(df.head())  # Always same order as file

​

DataStore

L’ordre des lignes est automatiquement conservé pour la plupart des opérations :

ds = pd.read_csv("data.csv")
print(ds.head())  # Matches file order

# Filter preserves order
ds_filtered = ds[ds['age'] > 25]  # Same order as pandas

DataStore suit automatiquement en interne la position d’origine des lignes (à l’aide de rowNumberInAllBlocks()) afin de garantir la cohérence de l’ordre avec pandas.

​

Lorsque l’ordre est préservé

• Sources de fichiers (CSV, Parquet, JSON, etc.)
• Sources de type pandas DataFrame
• Opérations de filtrage
• Sélection de colonnes
• Après un sort() ou un sort_values() explicite
• Opérations qui définissent l’ordre (nlargest(), nsmallest(), head(), tail())

​

Cas où l’ordre peut varier

• Après des agrégations groupby() (utilisez sort_values() pour garantir un ordre cohérent)
• Après merge() / join() avec certains types de jointure
• En mode performance (config.use_performance_mode()) : l’ordre des lignes n’est pas garanti, quelle que soit l’opération. Voir Mode Performance.

---

​

5. Pas de paramètre inplace

​

pandas

df.drop(columns=['col'], inplace=True)  # Modifies df
df.fillna(0, inplace=True)              # Modifies df
df.rename(columns={'old': 'new'}, inplace=True)

​

DataStore

inplace=True n’est pas pris en charge. Assignez toujours le résultat :

ds = ds.drop(columns=['col'])           # Returns new DataStore
ds = ds.fillna(0)                       # Returns new DataStore
ds = ds.rename(columns={'old': 'new'})  # Returns new DataStore

​

Pourquoi pas de inplace ?

DataStore s’appuie sur des opérations immuables pour offrir :

• La construction de requêtes (évaluation paresseuse)
• La sûreté en environnement multithread
• Un débogage plus facile
• Un code plus clair

---

​

6. Prise en charge des index

​

pandas

Prise en charge complète des index :

df = df.set_index('id')
df.loc['user123']           # Label-based access
df.loc['a':'z']             # Label-based slicing
df.reset_index()
df.index.name = 'user_id'

​

DataStore

Prise en charge simplifiée des index :

# Basic operations work
ds.loc[0:10]               # Integer position
ds.iloc[0:10]              # Same as loc for DataStore

# For pandas-style index operations, convert first
df = ds.to_df()
df = df.set_index('id')
df.loc['user123']

​

Le type de source DataStore est important

• Source DataFrame : conserve l’index pandas
• Source File : utilise un index entier simple

---

​

7. Comportement des comparaisons

​

Comparaison avec pandas

pandas ne reconnaît pas les objets DataStore :

import pandas as pd
from chdb import datastore as ds

pdf = pd.DataFrame({'a': [1, 2, 3]})
dsf = ds.DataFrame({'a': [1, 2, 3]})

# This doesn't work as expected
pdf == dsf  # pandas doesn't know DataStore

# Solution: convert DataStore to pandas
pdf.equals(dsf.to_pandas())  # True

​

Utilisation d’equals()

# DataStore.equals() also works
dsf.equals(pdf)  # Compares with pandas DataFrame

---

​

8. Inférence de type

​

pandas

Utilise des types numpy/pandas :

df['col'].dtype  # int64, float64, object, datetime64, etc.

​

DataStore

Peut utiliser des types ClickHouse :

ds['col'].dtype  # Int64, Float64, String, DateTime, etc.

# Types are converted when going to pandas
df = ds.to_df()
df['col'].dtype  # Now pandas type

​

Conversion de type explicite

# Force specific type
ds['col'] = ds['col'].astype('int64')

---

​

9. Modèle mémoire

​

pandas

Toutes les données sont en mémoire :

df = pd.read_csv("huge.csv")  # 10GB in memory!

​

DataStore

Les données restent dans la source jusqu’à ce qu’on en ait besoin :

ds = pd.read_csv("huge.csv")  # Just metadata
ds = ds.filter(ds['year'] == 2024)  # Still just metadata

# Only filtered result is loaded
df = ds.to_df()  # Maybe only 1GB now

---

​

10. Messages d’erreur

​

Différentes sources d’erreurs

• erreurs pandas : issues de la bibliothèque pandas
• erreurs DataStore : issues de chDB ou de ClickHouse

# May see ClickHouse-style errors
# "Code: 62. DB::Exception: Syntax error..."

​

Conseils de débogage

# View the SQL to debug
print(ds.to_sql())

# See execution plan
ds.explain()

# Enable debug logging
from chdb.datastore.config import config
config.enable_debug()

---

​

Checklist de migration

Lors d’une migration depuis pandas :

• Modifier l’instruction d’import
• Supprimer les paramètres inplace=True
• Ajouter un to_df() explicite lorsqu’un DataFrame pandas est nécessaire
• Ajouter un tri si l’ordre des lignes a de l’importance
• Utiliser to_pandas() pour les tests de comparaison
• Tester avec des volumes de données représentatifs

---

​

Référence rapide

pandas	DataStore
df[condition]	Identique (renvoie un DataStore)
df.groupby()	Identique (renvoie un LazyGroupBy)
df.drop(inplace=True)	ds = ds.drop()
df.equals(other)	ds.to_pandas().equals(other)
df.loc['label']	ds.to_df().loc['label']
print(df)	Identique (déclenche l’exécution)
len(df)	Identique (déclenche l’exécution)