> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<div id="engines">
  ## Motores disponibles
</div>

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

<div id="setting">
  ## Configuración del motor
</div>

<div id="global">
  ### Configuración global
</div>

```python theme={null}
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
```

<div id="checking">
  ### Comprobar el motor actual
</div>

```python theme={null}
print(config.execution_engine)  # 'auto', 'chdb' o 'pandas'
```

***

<div id="auto-mode">
  ## Modo automático
</div>

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

<div id="auto-chdb">
  ### Operaciones ejecutadas en chDB
</div>

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

<div id="auto-pandas">
  ### Operaciones ejecutadas en pandas
</div>

* 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

<div id="auto-example">
  ### Ejemplo
</div>

```python theme={null}
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)
```

***

<div id="chdb-mode">
  ## Modo chDB
</div>

Fuerza todas las operaciones mediante ClickHouse SQL:

```python theme={null}
config.use_chdb()
```

<div id="chdb-when">
  ### Cuándo usar
</div>

* 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

<div id="chdb-performance">
  ### Características del rendimiento
</div>

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

<div id="chdb-limitations">
  ### Limitaciones
</div>

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

***

<div id="pandas-mode">
  ## Modo pandas
</div>

Fuerza todas las operaciones mediante pandas:

```python theme={null}
config.use_pandas()
```

<div id="chdb-when">
  ### Cuándo usar
</div>

* 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

<div id="pandas-performance">
  ### Características de rendimiento
</div>

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

***

<div id="cross-datastore">
  ## Motor entre DataStores
</div>

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

```python theme={null}
# Configurar el motor cross-DataStore
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')
```

<div id="auto-example">
  ### Ejemplo
</div>

```python theme={null}
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
```

***

<div id="selection-logic">
  ## Lógica de selección del motor
</div>

<div id="decision-tree">
  ### Árbol de decisiones del modo automático
</div>

```text theme={null}
Operación solicitada
    │
    ├─ ¿Se puede expresar en SQL?
    │      │
    │      ├─ Sí → Usa chDB
    │      │
    │      └─ No → Usa pandas
    │
    └─ ¿Operación entre DataStores?
           │
           └─ Usa cross_datastore_engine setting
```

<div id="function-override">
  ### Sobrescritura a nivel de función
</div>

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

```python theme={null}
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](/es/products/chdb/configuration/function-config) para más detalles.

***

<div id="performance-comparison">
  ## Comparación de rendimiento
</div>

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

***

<div id="best-practices">
  ## Buenas prácticas
</div>

<div id="start-with-auto-mode">
  ### 1. Comienza con el modo automático
</div>

```python theme={null}
config.use_auto()  # Dejar que DataStore decida
```

<div id="profile-before-forcing">
  ### 2. Perfila antes de forzar
</div>

```python theme={null}
config.enable_profiling()
# Ejecuta tu carga de trabajo
# Consulta el informe del Profiler para ver dónde se invierte el tiempo
```

<div id="force-engine-for-specific-workloads">
  ### 3. Forzar un motor para cargas de trabajo específicas
</div>

```python theme={null}
# Para cargas de trabajo de agregación intensiva
config.use_chdb()

# Para pruebas de compatibilidad con pandas
config.use_pandas()
```

<div id="use-explain-to-understand-execution">
  ### 4. Usa explain() para comprender la ejecución
</div>

```python theme={null}
ds = pd.read_csv("data.csv")
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'sum'})

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

***

<div id="troubleshooting">
  ## Solución de problemas
</div>

<div id="issue-operation-slower">
  ### Problema: La operación es más lenta de lo esperado
</div>

```python theme={null}
# 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()
```

<div id="issue-unsupported-operation">
  ### Problema: Operación no admitida en modo chdb
</div>

```python theme={null}
# 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()
```

<div id="issue-memory-issues">
  ### Problema: problemas de memoria al trabajar con grandes volúmenes de datos
</div>

```python theme={null}
# 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()
```

<Tip>
  **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](/es/products/chdb/configuration/performance-mode). Configura automáticamente el motor como `chdb` y elimina toda la sobrecarga de compatibilidad con pandas.
</Tip>