Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Configuración del motor de ejecución

View as MarkdownEdit this pageReport an issueSet up docs MCP

DataStore puede ejecutar operaciones con distintos backends. Esta guía explica cómo configurar y optimizar la selección del motor.

Motores disponibles

Motor Descripción Ideal para
auto Selecciona automáticamente el mejor motor para cada operación Uso general (predeterminado)
chdb Fuerza todas las operaciones a ejecutarse mediante ClickHouse SQL Grandes conjuntos de datos, agregaciones
pandas Fuerza todas las operaciones a ejecutarse mediante pandas Pruebas de compatibilidad, funcionalidades específicas de pandas

Configurar el motor

Configuración global

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

Comprobar el motor actual

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

Auto Mode

En el modo auto (por defecto), DataStore selecciona el motor óptimo para cada operación:

Operaciones ejecutadas en chDB

  • Filtrado compatible con SQL (filter(), where())
  • Selección de columnas (select())
  • Ordenación (sort(), orderby())
  • Agrupación y agregación (groupby().agg())
  • Uniones (join(), merge())
  • Eliminación de duplicados (distinct(), drop_duplicates())
  • Limitación de resultados (limit(), head(), tail())

Operaciones ejecutadas en pandas

  • Funciones apply personalizadas (apply(custom_func))
  • Tablas dinámicas complejas con agregaciones personalizadas
  • Operaciones que no se pueden expresar en SQL
  • Cuando la entrada ya es un pandas DataFrame

Ejemplo

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)

Modo chDB

Obliga a que todas las operaciones pasen por ClickHouse SQL:

config.use_chdb()

Cuándo usar

  • Procesamiento de grandes conjuntos de datos (millones de filas)
  • Cargas de trabajo con agregaciones intensivas
  • Cuando se busca la máxima optimización de SQL
  • Comportamiento coherente en todas las operaciones

Características de rendimiento

Tipo de operación Rendimiento
GroupBy/Agregación Excelente (hasta 20 veces más rápido)
Filtrado complejo Excelente
Ordenación Muy bueno
Filtros simples de un solo criterio Bueno (ligera sobrecarga)

Limitaciones

  • Es posible que no se admitan funciones personalizadas en Python
  • Algunas funciones específicas de pandas requieren conversión

Modo pandas

Forzar todas las operaciones mediante pandas:

config.use_pandas()

Cuándo usar

  • Pruebas de compatibilidad con pandas
  • Uso de funciones específicas de pandas
  • Depuración de problemas relacionados con pandas
  • Cuando los datos ya están en formato pandas

Características de rendimiento

Tipo de operación Rendimiento
Operaciones simples Bueno
Funciones personalizadas Excelente
Agregaciones complejas Más lentas que chDB
Conjuntos de datos grandes Uso intensivo de memoria

Motor entre DataStores

Configure el motor para las operaciones que combinan columnas de distintos DataStores:

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

Ejemplo

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

Lógica de selección del motor

Árbol de decisión de Auto Mode

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

Sobrescritura a nivel de función

Algunas funciones pueden tener el motor configurado explícitamente:

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')

Consulta Configuración de funciones para más información.

Comparación de rendimiento

Resultados del benchmark con 10M de filas:

Operación pandas (ms) chdb (ms) Mejora
Recuento de GroupBy 347 17 19.93x
Operaciones combinadas 1,535 234 6.56x
Pipeline complejo 2,047 380 5.39x
Filtro+Ordenación+Head 1,537 350 4.40x
Agregación de GroupBy 406 141 2.88x
Filtro único 276 526 0.52x

Conclusiones clave:

  • chDB destaca en las agregaciones y los pipelines complejos
  • pandas es ligeramente más rápido en operaciones simples aisladas
  • Usa el modo auto para aprovechar lo mejor de ambos

Buenas prácticas

1. Comienza con Auto Mode

config.use_auto()  # Let DataStore decide

2. Analiza el rendimiento antes de forzar

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

3. Forzar el uso del motor para cargas de trabajo específicas

# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
config.use_pandas()

4. Usa explain() para comprender la ejecución

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

Solución de problemas

Problema: La operación es más lenta de lo esperado

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

Problema: Operación no admitida en modo 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()

Problema: problemas de memoria con grandes volúmenes de datos

# 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