Configuration du moteur d’exécution

Configurer le moteur d’exécution de DataStore : auto, chdb ou pandas

DataStore peut exécuter des opérations via différents backends. Ce guide explique comment configurer et optimiser le choix du moteur.

​

Moteurs disponibles

Moteur	Description	Idéal pour
auto	Sélectionne automatiquement le meilleur moteur pour chaque opération	Utilisation générale (par défaut)
chdb	Exécute toutes les opérations via ClickHouse SQL	Grands ensembles de données, agrégations
pandas	Exécute toutes les opérations via pandas	Tests de compatibilité, fonctionnalités propres à pandas

​

Définir le moteur

​

Configuration globale

from chdb.datastore.config import config

# Option 1: Using set method
config.set_execution_engine('auto')    # Default
config.set_execution_engine('chdb')    # Force ClickHouse
config.set_execution_engine('pandas')  # Force pandas

# Option 2: Using shortcuts
config.use_auto()     # Auto-select
config.use_chdb()     # Force ClickHouse
config.use_pandas()   # Force pandas

​

Vérifier le moteur actuel

print(config.execution_engine)  # 'auto', 'chdb', or 'pandas'

---

​

mode auto

En mode auto (par défaut), DataStore choisit le moteur le plus adapté à chaque opération :

​

Opérations exécutées dans chDB

• Filtrage de type SQL (filter(), where())
• Sélection de colonnes (select())
• Tri (sort(), orderby())
• Regroupement et agrégation (groupby().agg())
• Jointures (join(), merge())
• Déduplication (distinct(), drop_duplicates())
• Limitation (limit(), head(), tail())

​

Opérations effectuées dans pandas

• Fonctions apply personnalisées (apply(custom_func))
• Tableaux croisés dynamiques complexes avec des agrégations personnalisées
• Opérations impossibles à exprimer en SQL
• Lorsque l’entrée est déjà un DataFrame pandas

​

Exemple

from chdb import datastore as pd
from chdb.datastore.config import config

config.use_auto()  # Default

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

# This uses chDB (SQL)
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# This uses pandas (custom function)
result = ds.apply(lambda row: complex_calculation(row), axis=1)

---

​

Mode chDB

Forcez toutes les opérations via ClickHouse SQL :

config.use_chdb()

​

Quand l’utiliser

• Traitement de grands volumes de données (des millions de lignes)
• Charges de travail d’agrégation intensives
• Lorsque vous recherchez une optimisation SQL maximale
• Comportement cohérent pour toutes les opérations

​

Caractéristiques en matière de performances

Type d’opération	Performances
GroupBy/Agrégation	Excellentes (jusqu’à 20x plus rapide)
Filtrage complexe	Excellentes
Tri	Très bonnes
Filtres simples individuels	Bonnes (léger surcoût)

​

Limites

• Les fonctions Python personnalisées peuvent ne pas être prises en charge
• Certaines fonctionnalités propres à pandas nécessitent une conversion

---

​

Mode pandas

Forcer toutes les opérations via pandas :

config.use_pandas()

​

Quand utiliser

• Tests de compatibilité avec pandas
• Utilisation de fonctionnalités propres à pandas
• Débogage des problèmes liés à pandas
• Lorsque les données sont déjà au format pandas

​

Caractéristiques de performances

Type d’opération	Performance
Opérations simples	Bonne
Fonctions personnalisées	Excellente
Agrégations complexes	Plus lentes que chDB
Jeux de données volumineux	Gourmands en mémoire

---

​

Moteur Cross-DataStore

Configurez le moteur pour les opérations combinant des colonnes de différents DataStores :

# Set cross-DataStore engine
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')

​

Exemple

ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# This operation involves two DataStores
result = ds1.join(ds2, on='product_id')
# Uses cross_datastore_engine setting

---

​

Logique de sélection du moteur

​

Arbre de décision du mode Auto

Operation requested
    │
    ├─ Can be expressed in SQL?
    │      │
    │      ├─ Yes → Use chDB
    │      │
    │      └─ No → Use pandas
    │
    └─ Cross-DataStore operation?
           │
           └─ Use cross_datastore_engine setting

​

Surcharge au niveau de la fonction

Certaines fonctions peuvent avoir leur moteur configuré explicitement :

from chdb.datastore.config import function_config

# Force specific functions to use specific engine
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')

Voir Configuration des fonctions pour plus de détails.

---

​

Comparaison des performances

Résultats du benchmark sur 10 M lignes :

Opération	pandas (ms)	chdb (ms)	Accélération
GroupBy count	347	17	19.93x
Opérations combinées	1,535	234	6.56x
Pipeline complexe	2,047	380	5.39x
Filter+Sort+Head	1,537	350	4.40x
GroupBy agg	406	141	2.88x
Filtre simple	276	526	0.52x

Points clés :

• chDB excelle pour les agrégations et les pipelines complexes
• pandas est légèrement plus rapide pour les opérations simples prises isolément
• Utilisez le mode auto pour profiter du meilleur des deux

---

​

Bonnes pratiques

​

1. Commencez par mode auto

config.use_auto()  # Let DataStore decide

​

2. Définissez un profil avant de forcer

config.enable_profiling()
# Run your workload
# Check profiler report to see where time is spent

​

3. Forcer un moteur pour des charges de travail spécifiques

# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
config.use_pandas()

​

4. Utilisez explain() pour comprendre l’exécution

ds = pd.read_csv("data.csv")
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'sum'})

# See what SQL will be generated
query.explain()

---

​

Dépannage

​

Problème : opération plus lente que prévue

# Check current engine
print(config.execution_engine)

# Enable debug to see what's happening
config.enable_debug()

# Try forcing specific engine
config.use_chdb()  # or config.use_pandas()

​

Problème : opération non prise en charge en mode chdb

# Some pandas operations aren't supported in SQL
# Solution: use auto mode
config.use_auto()

# Or explicitly convert to pandas first
df = ds.to_df()
result = df.some_pandas_specific_operation()

​

Problème : problèmes de mémoire avec de gros volumes de données

# Use chdb engine to avoid loading all data into memory
config.use_chdb()

# Filter early to reduce data size
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# For maximum throughput on large datasets, use performance mode
# which enables parallel Parquet reading and single-SQL aggregation
config.use_performance_mode()

Performance Mode

Si vous exécutez des charges d’agrégation importantes et que vous n’avez pas besoin d’une compatibilité exacte avec la sortie de pandas (ordre des lignes, MultiIndex, corrections de type), envisagez d’utiliser le Performance Mode. Il définit automatiquement le moteur sur chdb et supprime toute la surcharge liée à la compatibilité avec pandas.