Compatibilité de DataStore avec Pandas - ClickHouse Documentation

DataStore implémente 209 méthodes de DataFrame pandas pour assurer une compatibilité complète avec l’API. Votre code pandas existant fonctionne avec un minimum de modifications.

Approche de compatibilité

# Typical migration - just change the import
- import pandas as pd
+ from chdb import datastore as pd

# Your code works unchanged
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

Principes clés :

Prise en charge des 209 méthodes de DataFrame pandas
Évaluation différée pour l’optimisation SQL
Encapsulation automatique des types (DataFrame → DataStore, Series → ColumnExpr)
Opérations immuables (sans inplace=True)

Attributs et propriétés

Propriété	Description	Déclenche l’exécution
`shape`	tuple (lignes, colonnes)	Oui
`columns`	Noms des colonnes (Index)	Oui
`dtypes`	Types de données des colonnes	Oui
`values`	tableau NumPy	Oui
`index`	Index des lignes	Oui
`size`	Nombre d’éléments	Oui
`ndim`	Nombre de dimensions	Non
`empty`	DataFrame vide	Oui
`T`	Transposition	Oui
`axes`	Liste des axes	Oui

Exemples :

from chdb import datastore as pd

ds = pd.read_csv("data.csv")

print(ds.shape)      # (1000, 5)
print(ds.columns)    # Index(['name', 'age', 'city', 'salary', 'dept'])
print(ds.dtypes)     # name: object, age: int64, ...
print(ds.empty)      # False

Indexation et sélection

Méthode	Description	Exemple
`df['col']`	Sélection d’une colonne	`ds['age']`
`df[['col1', 'col2']]`	Sélection de colonnes	`ds[['name', 'age']]`
`df[condition]`	Indexation booléenne	`ds[ds['age'] > 25]`
`df.loc[...]`	Accès par étiquette	`ds.loc[0:10, 'name']`
`df.iloc[...]`	Accès par indice entier	`ds.iloc[0:10, 0:3]`
`df.at[...]`	Valeur unique par étiquette	`ds.at[0, 'name']`
`df.iat[...]`	Valeur unique par position	`ds.iat[0, 0]`
`df.head(n)`	n premières lignes	`ds.head(10)`
`df.tail(n)`	n dernières lignes	`ds.tail(10)`
`df.sample(n)`	Échantillon aléatoire	`ds.sample(100)`
`df.select_dtypes()`	Sélection par type de données	`ds.select_dtypes(include='number')`
`df.query()`	Expression de requête	`ds.query('age > 25')`
`df.where()`	Remplacement conditionnel	`ds.where(ds['age'] > 0, 0)`
`df.mask()`	Inverse de `where`	`ds.mask(ds['age'] < 0, 0)`
`df.isin()`	Appartenance à un ensemble de valeurs	`ds['city'].isin(['NYC', 'LA'])`
`df.get()`	Accès sécurisé à une colonne	`ds.get('col', default=None)`
`df.xs()`	Coupe transversale	`ds.xs('key')`
`df.pop()`	Suppression d’une colonne	`ds.pop('col')`

Méthodes statistiques

Méthode	Description	Équivalent SQL
`mean()`	Valeur moyenne	`AVG()`
`median()`	Valeur médiane	`MEDIAN()`
`mode()`	Valeur modale	-
`std()`	Écart-type	`STDDEV()`
`var()`	Variance	`VAR()`
`min()`	Minimum	`MIN()`
`max()`	Maximum	`MAX()`
`sum()`	Somme	`SUM()`
`prod()`	Produit	-
`count()`	Nombre de valeurs non NULL	`COUNT()`
`nunique()`	Nombre de valeurs uniques	`UNIQ()`
`value_counts()`	Fréquence des valeurs	`GROUP BY`
`quantile()`	Quantile	`QUANTILE()`
`describe()`	Statistiques descriptives	-
`corr()`	Matrice de corrélation	`CORR()`
`cov()`	Matrice de covariance	`COV()`
`corrwith()`	Corrélation par paires	-
`rank()`	Rang des valeurs	`RANK()`
`abs()`	Valeurs absolues	`ABS()`
`round()`	Arrondi des valeurs	`ROUND()`
`clip()`	Bornage des valeurs	-
`cumsum()`	Somme cumulative	Fonction de fenêtre
`cumprod()`	Produit cumulatif	Fonction de fenêtre
`cummin()`	Minimum cumulatif	Fonction de fenêtre
`cummax()`	Maximum cumulatif	Fonction de fenêtre
`diff()`	Différence	Fonction de fenêtre
`pct_change()`	Variation en pourcentage	Fonction de fenêtre
`skew()`	Asymétrie	`SKEW()`
`kurt()`	Kurtosis	`KURT()`
`sem()`	Erreur type	-
`all()`	Toutes vraies	-
`any()`	Au moins une vraie	-
`idxmin()`	Indice du minimum	-
`idxmax()`	Indice du maximum	-

Exemples :

ds = pd.read_csv("data.csv")

# Basic statistics
print(ds['salary'].mean())
print(ds['age'].std())
print(ds.describe())

# Group statistics
print(ds.groupby('department')['salary'].mean())
print(ds.groupby('city').agg({'salary': ['mean', 'std'], 'age': 'count'}))

Manipulation des données

Méthode	Description
`drop()`	Supprimer des lignes/colonnes
`drop_duplicates()`	Supprimer les doublons
`duplicated()`	Marquer les doublons
`dropna()`	Supprimer les valeurs manquantes
`fillna()`	Remplir les valeurs manquantes
`ffill()`	Remplissage en avant
`bfill()`	Remplissage en arrière
`interpolate()`	Interpoler les valeurs
`replace()`	Remplacer les valeurs
`rename()`	Renommer les colonnes/l’index
`rename_axis()`	Renommer l’axe
`assign()`	Ajouter de nouvelles colonnes
`astype()`	Convertir les types
`convert_dtypes()`	Inférer les types
`copy()`	Copier le DataFrame

Exemples :

ds = pd.read_csv("data.csv")

# Drop operations
result = ds.drop(columns=['unused_col'])
result = ds.drop_duplicates(subset=['user_id'])
result = ds.dropna(subset=['email'])

# Fill operations
result = ds.fillna(0)
result = ds.fillna({'age': 0, 'name': 'Unknown'})

# Transform operations
result = ds.rename(columns={'old_name': 'new_name'})
result = ds.assign(
    full_name=lambda x: x['first_name'] + ' ' + x['last_name'],
    age_group=lambda x: pd.cut(x['age'], bins=[0, 25, 50, 100])
)

Tri et classement

Méthode	Description
`sort_values()`	Tri par valeurs
`sort_index()`	Tri par index
`nlargest()`	N plus grandes valeurs
`nsmallest()`	N plus petites valeurs

Exemples :

# Sort by single column
result = ds.sort_values('salary', ascending=False)

# Sort by multiple columns
result = ds.sort_values(['department', 'salary'], ascending=[True, False])

# Get top/bottom N
result = ds.nlargest(10, 'salary')
result = ds.nsmallest(5, 'age')

Réorganisation

Méthode	Description
`pivot()`	Tableau croisé dynamique
`pivot_table()`	Pivot avec agrégation
`melt()`	Dépivotage
`stack()`	Empiler les colonnes dans l’index
`unstack()`	Désempiler l’index en colonnes
`transpose()` / `T`	Transposition
`explode()`	Éclater les listes en lignes
`squeeze()`	Réduction des dimensions
`droplevel()`	Supprimer un niveau d’index
`swaplevel()`	Permuter les niveaux d’index
`reorder_levels()`	Réordonner les niveaux

Exemples :

# Pivot table
result = ds.pivot_table(
    values='amount',
    index='region',
    columns='product',
    aggfunc='sum'
)

# Melt (unpivot)
result = ds.melt(
    id_vars=['name'],
    value_vars=['score1', 'score2', 'score3'],
    var_name='test',
    value_name='score'
)

# Explode arrays
result = ds.explode('tags')

Combinaison / jointure

Méthode	Description
`merge()`	Fusion de type SQL
`join()`	Jointure sur index
`concat()`	Concaténation
`append()`	Ajout de lignes
`combine()`	Combinaison avec fonction
`combine_first()`	Combinaison avec priorité
`update()`	Mise à jour des valeurs
`compare()`	Afficher les différences

Exemples :

# Merge (join)
result = pd.merge(df1, df2, on='id', how='left')
result = df1.join(df2, on='id')

# Concatenate
result = pd.concat([df1, df2, df3])
result = pd.concat([df1, df2], axis=1)

Opérations binaires

Méthode	Description
`add()` / `radd()`	Addition
`sub()` / `rsub()`	Soustraction
`mul()` / `rmul()`	Multiplication
`div()` / `rdiv()`	Division
`truediv()` / `rtruediv()`	Division réelle
`floordiv()` / `rfloordiv()`	Division entière
`mod()` / `rmod()`	Modulo
`pow()` / `rpow()`	Puissance
`dot()`	Multiplication matricielle

Exemples :

# Arithmetic operations
result = ds['col1'].add(ds['col2'])
result = ds['price'].mul(ds['quantity'])

# With fill_value for missing data
result = ds['col1'].add(ds['col2'], fill_value=0)

Opérations de comparaison

Méthode	Description
`eq()`	Égal à
`ne()`	Différent de
`lt()`	Inférieur à
`le()`	Inférieur ou égal à
`gt()`	Supérieur à
`ge()`	Supérieur ou égal à
`equals()`	Tester l’égalité
`compare()`	Afficher les différences

Application des fonctions

Méthode	Description
`apply()`	Appliquer la fonction
`applymap()`	Appliquer à chaque élément
`map()`	Faire correspondre les valeurs
`agg()` / `aggregate()`	Agréger
`transform()`	Transformer
`pipe()`	Enchaîner les fonctions
`groupby()`	Regrouper par

Exemples :

# Apply function
result = ds['name'].apply(lambda x: x.upper())
result = ds.apply(lambda row: row['a'] + row['b'], axis=1)

# Aggregate
result = ds.agg({'col1': 'sum', 'col2': 'mean'})
result = ds.agg(['sum', 'mean', 'std'])

# Pipe
result = (ds
    .pipe(filter_active)
    .pipe(calculate_metrics)
    .pipe(format_output)
)

Séries temporelles

Method	Description
`rolling()`	Fenêtre glissante
`expanding()`	Fenêtre cumulative
`ewm()`	Pondération exponentielle
`resample()`	Rééchantillonner une série temporelle
`shift()`	Décaler les valeurs
`asfreq()`	Convertir la fréquence
`asof()`	Dernière valeur à un instant donné
`at_time()`	Sélectionner à une heure donnée
`between_time()`	Sélectionner l’intervalle de temps
`first()` / `last()`	Premières/dernières périodes
`to_period()`	Convertir en période
`to_timestamp()`	Convertir en horodatage
`tz_convert()`	Convertir le fuseau horaire
`tz_localize()`	Définir le fuseau horaire

Exemples :

# Rolling window
result = ds['value'].rolling(window=7).mean()

# Expanding window
result = ds['value'].expanding().sum()

# Shift
result = ds['value'].shift(1)  # Lag
result = ds['value'].shift(-1)  # Lead

Valeurs manquantes

Méthode	Description
`isna()` / `isnull()`	Détecter les valeurs manquantes
`notna()` / `notnull()`	Détecter les valeurs non manquantes
`dropna()`	Supprimer les valeurs manquantes
`fillna()`	Combler les valeurs manquantes
`ffill()`	Remplissage en avant
`bfill()`	Remplissage en arrière
`interpolate()`	Interpoler
`replace()`	Remplacer des valeurs

Méthodes d’E/S

Méthode	Description
`to_csv()`	Export vers CSV
`to_json()`	Export vers JSON
`to_excel()`	Export vers Excel
`to_parquet()`	Export vers Parquet
`to_feather()`	Export vers Feather
`to_sql()`	Export vers une base de données SQL
`to_pickle()`	Format Pickle
`to_html()`	Tableau HTML
`to_latex()`	Tableau LaTeX
`to_markdown()`	Tableau Markdown
`to_string()`	Représentation sous forme de chaîne
`to_dict()`	Dictionnaire
`to_records()`	Enregistrements
`to_numpy()`	Tableau NumPy
`to_clipboard()`	Presse-papiers

Voir Opérations d’E/S pour la documentation détaillée.

Itération

Méthode	Description
`items()`	Parcourir (colonne, Series)
`iterrows()`	Parcourir (index, Series)
`itertuples()`	Parcourir sous forme de tuples nommés

Différences clés avec Pandas

1. Types de retour

# Pandas returns Series
pdf['col']  # → pd.Series

# DataStore returns ColumnExpr (lazy)
ds['col']   # → ColumnExpr

2. Exécution différée

# DataStore operations are lazy
result = ds.filter(ds['age'] > 25)  # Not executed yet
df = result.to_df()  # Executed here

3. Pas de paramètre inplace

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

# DataStore (always returns new object)
ds = ds.drop(columns=['col'])

4. Comparaison des résultats

# Use to_pandas() for comparison
pd.testing.assert_frame_equal(
    ds.to_pandas(),
    expected_df
)

Voir Différences clés pour plus de détails.

​Approche de compatibilité

​Attributs et propriétés

​Indexation et sélection

​Méthodes statistiques

​Manipulation des données

​Tri et classement

​Réorganisation

​Combinaison / jointure

​Opérations binaires

​Opérations de comparaison

​Application des fonctions

​Séries temporelles

​Valeurs manquantes

​Méthodes d’E/S

​Itération

​Différences clés avec Pandas

​1. Types de retour

​2. Exécution différée

​3. Pas de paramètre inplace

​4. Comparaison des résultats

Approche de compatibilité

Attributs et propriétés

Indexation et sélection

Méthodes statistiques

Manipulation des données

Tri et classement

Réorganisation

Combinaison / jointure

Opérations binaires

Opérations de comparaison

Application des fonctions

Séries temporelles

Valeurs manquantes

Méthodes d’E/S

Itération

Différences clés avec Pandas

1. Types de retour

2. Exécution différée

3. Pas de paramètre inplace

4. Comparaison des résultats