Configuración del motor de ejecución - ClickHouse Documentation

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

Modo de rendimientoSi ejecuta cargas de trabajo intensivas de agregación y no necesita compatibilidad exacta con la salida de pandas (orden de las filas, MultiIndex, correcciones de dtype), considere usar Modo de rendimiento. Configura automáticamente el motor como chdb y elimina toda la sobrecarga de compatibilidad con pandas.

​Motores disponibles

​Configurar el motor

​Configuración global

​Comprobar el motor actual

​Auto Mode

​Operaciones ejecutadas en chDB

​Operaciones ejecutadas en pandas

​Ejemplo

​Modo chDB

​Cuándo usar

​Características de rendimiento

​Limitaciones

​Modo pandas

​Cuándo usar

​Características de rendimiento

​Motor entre DataStores

​Ejemplo

​Lógica de selección del motor

​Árbol de decisión de Auto Mode

​Sobrescritura a nivel de función

​Comparación de rendimiento

​Buenas prácticas

​1. Comienza con Auto Mode

​2. Analiza el rendimiento antes de forzar

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

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

​Solución de problemas

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

​Problema: Operación no admitida en modo chdb

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

Motores disponibles

Configurar el motor

Configuración global

Comprobar el motor actual

Auto Mode

Operaciones ejecutadas en chDB

Operaciones ejecutadas en pandas

Ejemplo

Modo chDB

Cuándo usar

Características de rendimiento

Limitaciones

Modo pandas

Cuándo usar

Características de rendimiento

Motor entre DataStores

Ejemplo

Lógica de selección del motor

Árbol de decisión de Auto Mode

Sobrescritura a nivel de función

Comparación de rendimiento

Buenas prácticas

1. Comienza con Auto Mode

2. Analiza el rendimiento antes de forzar

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

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

Solución de problemas

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

Problema: Operación no admitida en modo chdb

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