Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Migration à partir de pandas

View as MarkdownEdit this pageReport an issueSet up docs MCP

Ce guide vous aide à migrer votre code pandas existant vers DataStore pour de meilleures performances tout en conservant la compatibilité.

La migration en une seule ligne

La migration la plus simple consiste à modifier votre instruction d’import :

# Before (pandas)
import pandas as pd

# After (DataStore)
from chdb import datastore as pd

C'est tout ! La plupart du code pandas fonctionne tel quel.

Migration étape par étape

Installer chDB

pip install "chdb>=4.0"

Modifier l’import

# Remplacez ceci :
import pandas as pd

# Par ceci :
from chdb import datastore as pd

Tester votre code

Exécutez votre code existant. La plupart des opérations fonctionnent sans modification :

from chdb import datastore as pd

# Tout cela fonctionne de la même façon
df = pd.read_csv("data.csv")
result = df[df['age'] > 25]
grouped = df.groupby('city')['salary'].mean()
df.to_csv("output.csv")

Gérer les différences éventuelles

Certaines opérations se comportent différemment. Voir Principales différences ci-dessous.

Ce qui fonctionne tel quel

Chargement des données

# All these work the same
df = pd.read_csv("data.csv")
df = pd.read_parquet("data.parquet")
df = pd.read_json("data.json")
df = pd.read_excel("data.xlsx")

Filtrage

# Boolean indexing
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

# query() method
df.query('age > 25 and salary > 50000')

Sélection

# Column selection
df['name']
df[['name', 'age']]

# Row selection
df.head(10)
df.tail(10)
df.iloc[0:100]

GroupBy et agrégation

# GroupBy
df.groupby('city')['salary'].mean()
df.groupby(['city', 'dept']).agg({'salary': ['sum', 'mean']})

Tri

df.sort_values('salary', ascending=False)
df.sort_values(['city', 'age'])

Opérations sur les chaînes de caractères

df['name'].str.upper()
df['name'].str.contains('John')
df['name'].str.len()

Opérations sur DateTime

df['date'].dt.year
df['date'].dt.month
df['date'].dt.dayofweek

Opérations d’E/S

df.to_csv("output.csv")
df.to_parquet("output.parquet")
df.to_json("output.json")

Principales différences

1. Évaluation différée

Les opérations de DataStore sont différées : elles ne s’exécutent que lorsque les résultats sont nécessaires.

pandas:

# Executes immediately
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame

DataStore :

# Builds query, doesn't execute yet
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (lazy)

# Executes when you need the data
print(result)        # Triggers execution
df = result.to_df()  # Triggers execution

2. Types de retour

Opération Renvoyé par pandas Renvoyé par DataStore
df['col'] Series ColumnExpr (différé)
df[['a', 'b']] DataFrame DataStore (différé)
df[condition] DataFrame DataStore (différé)
df.groupby('x') GroupBy LazyGroupBy

3. Aucun paramètre inplace

DataStore ne prend pas en charge inplace=True. Utilisez toujours la valeur de retour :

pandas:

df.drop(columns=['col'], inplace=True)

DataStore:

ds = ds.drop(columns=['col'])  # Assign the result

4. Comparer les DataStores

pandas ne reconnaît pas les objets DataStore ; utilisez donc to_pandas() pour les comparer :

# This may not work as expected
df == ds  # pandas doesn't know DataStore

# Do this instead
df.equals(ds.to_pandas())

5. Ordre des lignes

DataStore peut ne pas préserver l’ordre des lignes pour les sources de type fichier (comme les bases de données SQL). Utilisez un tri explicite :

# pandas preserves order
df = pd.read_csv("data.csv")

# DataStore - use sort for guaranteed order
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # Explicit ordering

Schémas de migration

Schéma 1 : lecture-analyse-écriture

# pandas
import pandas as pd

df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")

# DataStore - same code works!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")

Schéma 2 : DataFrame avec pandas

Si vous avez besoin de fonctionnalités propres à pandas, effectuez la conversion à la fin :

from chdb import datastore as pd

# Fast DataStore operations
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# Convert to pandas for specific features
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # pandas-specific

Schéma 3 : workflow mixte

from chdb import datastore as pd
import pandas

# Start with DataStore for fast filtering
ds = pd.read_csv("huge_file.csv")  # 10M rows
ds = ds.filter(ds['year'] == 2024)  # Fast SQL filter
ds = ds.select('col1', 'col2', 'col3')  # Column pruning

# Convert for pandas-specific operations
df = ds.to_df()  # Now only ~100K rows
result = df.apply(complex_custom_function)  # pandas

Comparaison des performances

DataStore est nettement plus rapide sur de grands jeux de données :

Opération pandas DataStore Gain de vitesse
GroupBy count 347ms 17ms 19.93x
Pipeline complexe 2,047ms 380ms 5.39x
Filter+Sort+Head 1,537ms 350ms 4.40x
GroupBy agg 406ms 141ms 2.88x

Benchmark sur 10 M de lignes

Dépannage de la migration

Problème : l’opération ne fonctionne pas

Certaines opérations pandas peuvent ne pas être prises en charge. Vérifiez les points suivants :

  1. L’opération figure-t-elle dans la liste de compatibilité ?
  2. Essayez d’abord de convertir en pandas : ds.to_df().operation()

Problème : résultats différents

Activez la journalisation de débogage pour comprendre ce qui se passe :

from chdb.datastore.config import config
config.enable_debug()

# View the SQL being generated
ds.filter(ds['x'] > 10).explain()

Problème : lenteurs

Vérifiez votre schéma d’exécution :

# Bad: Multiple small executions
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# Good: Single execution
result = ds.filter(ds['id'].isin(ids)).to_df()

Problème : incompatibilités de types

DataStore peut inférer les types différemment :

# Check types
print(ds.dtypes)

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

Stratégie de migration progressive

Semaine 1 : tester la compatibilité

# Keep both imports
import pandas as pd

from chdb import datastore as ds

# Compare results
pdf = pd.read_csv("data.csv")
dsf = ds.read_csv("data.csv")

# Verify they match
assert pdf.equals(dsf.to_pandas())

Semaine 2 : passez aux scripts simples

Commencez par des scripts qui :

  • lisent de gros fichiers
  • effectuent du filtrage et de l’agrégation
  • n’utilisent pas de fonctions apply personnalisées

Semaine 3 : Gérer les cas complexes

Pour les scripts avec des fonctions personnalisées :

from chdb import datastore as pd

# Let DataStore handle the heavy lifting
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# Convert for custom work
df = ds.to_df()
result = df.apply(my_custom_function)

Semaine 4 : Migration complète

Modifiez tous les scripts pour utiliser l’import DataStore.

FAQ

Puis-je utiliser à la fois pandas et DataStore ?

Oui ! Vous pouvez passer librement de l’un à l’autre :

from chdb import datastore as ds
import pandas as pd

# DataStore to pandas
df = ds_result.to_pandas()

# pandas to DataStore  
ds = ds.DataFrame(pd_result)

Mes tests réussiront-ils toujours ?

La plupart des tests devraient réussir. Pour les tests de comparaison, convertissez au format pandas :

def test_my_function():
    result = my_function()
    expected = pd.DataFrame(...)
    pd.testing.assert_frame_equal(result.to_pandas(), expected)

Puis-je utiliser DataStore dans Jupyter ?

Oui ! DataStore fonctionne dans les notebooks Jupyter :

from chdb import datastore as pd

ds = pd.read_csv("data.csv")
ds.head()  # Displays nicely in Jupyter

Comment signaler des problèmes ?

Si vous constatez des problèmes de compatibilité, signalez-les ici : https://github.com/chdb-io/chdb/issues

Navigation