Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Configuration du moteur d’exécution

View as MarkdownEdit this pageReport an issueSet up docs MCP

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()
Navigation