Configuración del motor de ejecución

Configure el motor de ejecución de DataStore: auto, chdb o pandas

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 rendimiento

Si 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.