Configuration du moteur d’exécution - ClickHouse Documentation

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 moteur le plus adapté à chaque opération	Usage général (par défaut)
`chdb`	Force toutes les opérations à passer par ClickHouse SQL	Jeux de données volumineux, agrégations
`pandas`	Force toutes les opérations à passer par pandas	Tests de compatibilité, fonctionnalités propres à pandas

Configuration du 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 automatique

En mode auto (par défaut), DataStore choisit le moteur optimal pour chaque opération :

Opérations exécutées dans chDB

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

Opérations exécutées dans pandas

Fonctions personnalisées avec 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 pandas DataFrame

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

Faites passer toutes les opérations par ClickHouse SQL :

config.use_chdb()

Quand utiliser

Traitement de grands volumes de données (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 de performance

Type d’opération	Performances
GroupBy/Agrégation	Excellentes (jusqu’à 20 fois plus rapides)
Filtrage complexe	Excellentes
Tri	Très bonnes
Filtres simples à critère unique	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

Forcez toutes les opérations à passer par pandas :

config.use_pandas()

Quand utiliser

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

Caractéristiques des 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 qui combinent des colonnes provenant 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 des fonctions

Pour certaines fonctions, il est possible de configurer explicitement leur moteur :

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 de fonction pour plus de détails.

Comparaison des performances

Résultats du benchmark sur 10 millions de lignes :

Opération	pandas (ms)	chdb (ms)	Gain de vitesse
GroupBy count	347	17	19.93x
Opérations combinées	1,535	234	6.56x
Pipeline complexe	2,047	380	5.39x
Filtre+Tri+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
Utilisez le mode auto pour tirer le meilleur parti des deux

Bonnes pratiques

1. Commencez par mode automatique

config.use_auto()  # Let DataStore decide

2. Mesurez avant de forcer

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

3. Imposer un moteur pour certaines charges de travail

# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
config.use_pandas()

4. Utiliser 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évu

# 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 grands 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()

Mode PerformanceSi 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 Dtype), envisagez d’utiliser le Mode Performance. Il définit automatiquement le moteur sur chdb et supprime toute la surcharge liée à la compatibilité avec pandas.

​Moteurs disponibles