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 elecció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`	Hace que todas las operaciones se ejecuten con ClickHouse SQL	Conjuntos de datos grandes, agregaciones
`pandas`	Hace que todas las operaciones se ejecuten con pandas	Pruebas de compatibilidad, funciones específicas de pandas

Configuración del motor

Configuración global

from chdb.datastore.config import config

# Opción 1: Usando el método set
config.set_execution_engine('auto')    # Por defecto
config.set_execution_engine('chdb')    # Forzar ClickHouse
config.set_execution_engine('pandas')  # Forzar pandas

# Opción 2: Usando atajos
config.use_auto()     # Selección automática
config.use_chdb()     # Forzar ClickHouse
config.use_pandas()   # Forzar pandas

Comprobar el motor actual

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

Modo automático

En el modo auto (predeterminado), 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())
Valores distintos (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 DataFrame de pandas

Ejemplo

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

config.use_auto()  # Por defecto

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

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

# Esto usa pandas (función personalizada)
result = ds.apply(lambda row: complex_calculation(row), axis=1)

Modo chDB

Fuerza todas las operaciones mediante ClickHouse SQL:

config.use_chdb()

Cuándo usar

Procesamiento de grandes volúmenes de datos (millones de filas)
Cargas de trabajo con agregaciones intensivas
Cuando necesites la máxima optimización de SQL
Comportamiento uniforme en todas las operaciones

Características del rendimiento

Tipo de operación	Rendimiento
GroupBy/Agregación	Excelente (hasta 20x más rápido)
Filtrado complejo	Excelente
Ordenación	Muy bueno
Filtros simples de una sola condición	Bueno (ligera sobrecarga)

Limitaciones

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

Modo pandas

Fuerza 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 individuales	Bueno
Funciones personalizadas	Excelente
Agregaciones complejas	Más lentas que chDB
Grandes conjuntos de datos	Uso intensivo de memoria

Motor entre DataStores

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

# Configurar el motor cross-DataStore
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")

# Esta operación involucra dos DataStores
result = ds1.join(ds2, on='product_id')
# Usa la configuración cross_datastore_engine

Lógica de selección del motor

Árbol de decisiones del modo automático

Operación solicitada
    │
    ├─ ¿Se puede expresar en SQL?
    │      │
    │      ├─ Sí → Usa chDB
    │      │
    │      └─ No → Usa pandas
    │
    └─ ¿Operación entre DataStores?
           │
           └─ Usa cross_datastore_engine setting

Sobrescritura a nivel de función

En algunas funciones, se puede configurar explícitamente el motor:

from chdb.datastore.config import function_config

# Forzar funciones específicas a usar un motor específico
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')

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

Comparación de rendimiento

Resultados de benchmark con 10 M de filas:

Operación	pandas (ms)	chdb (ms)	Aceleración
Conteo con GroupBy	347	17	19.93x
Operaciones combinadas	1,535	234	6.56x
Canalización compleja	2,047	380	5.39x
Filtrar+Ordenar+Head	1,537	350	4.40x
Agregación con GroupBy	406	141	2.88x
Filtro simple	276	526	0.52x

Conclusiones clave:

chDB destaca en las agregaciones y las canalizaciones complejas
pandas es ligeramente más rápido en operaciones simples
Usa el modo auto para obtener lo mejor de ambos

Buenas prácticas

1. Comienza con el modo automático

config.use_auto()  # Dejar que DataStore decida

2. Perfila antes de forzar

config.enable_profiling()
# Ejecuta tu carga de trabajo
# Consulta el informe del Profiler para ver dónde se invierte el tiempo

3. Forzar un motor para cargas de trabajo específicas

# Para cargas de trabajo de agregación intensiva
config.use_chdb()

# Para pruebas de compatibilidad con pandas
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'})

# Ver qué SQL se generará
query.explain()

Solución de problemas

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

# Comprobar el motor actual
print(config.execution_engine)

# Habilitar debug para ver qué está ocurriendo
config.enable_debug()

# Intentar forzar un motor específico
config.use_chdb()  # or config.use_pandas()

Problema: Operación no admitida en modo chdb

# Algunas operaciones de pandas no son compatibles con SQL
# Solución: usar el modo automático
config.use_auto()

# O convertir explícitamente a pandas primero
df = ds.to_df()
result = df.some_pandas_specific_operation()

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

# Usar el motor chdb para evitar cargar todos los datos en memoria
config.use_chdb()

# Filtrar con anticipación para reducir el tamaño de los datos
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# Para máximo rendimiento con grandes conjuntos de datos, usar el modo de rendimiento,
# que habilita la lectura paralela de Parquet y la agregación en una sola consulta SQL
config.use_performance_mode()

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

​Motores disponibles