> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración del motor de ejecución

> Configura 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 selecció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`   | 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 |

<div id="setting">
  ## Configurar el motor
</div>

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

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

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

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

***

<div id="auto-mode">
  ## Auto Mode
</div>

En el modo `auto` (por defecto), 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()`)
* Eliminación de duplicados (`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 pandas DataFrame

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

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

***

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

Obliga a que todas las operaciones pasen por ClickHouse SQL:

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

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

* 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

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

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

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

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

***

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

Forzar 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="chdb-performance">
  ### Características de rendimiento
</div>

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

***

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

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

```python theme={null}
# Set cross-DataStore engine
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")

# This operation involves two DataStores
result = ds1.join(ds2, on='product_id')
# Uses cross_datastore_engine setting
```

***

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

<div id="decision-tree">
  ### Árbol de decisión de Auto Mode
</div>

```text theme={null}
Operation requested
    │
    ├─ Can be expressed in SQL?
    │      │
    │      ├─ Yes → Use chDB
    │      │
    │      └─ No → Use pandas
    │
    └─ Cross-DataStore operation?
           │
           └─ Use cross_datastore_engine setting
```

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

Algunas funciones pueden tener el motor configurado explícitamente:

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

***

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

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

***

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

<div id="start-with-auto-mode">
  ### 1. Comienza con Auto Mode
</div>

```python theme={null}
config.use_auto()  # Let DataStore decide
```

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

```python theme={null}
config.enable_profiling()
# Run your workload
# Check profiler report to see where time is spent
```

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

```python theme={null}
# For heavy aggregation workloads
config.use_chdb()

# For pandas compatibility testing
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'})

# See what SQL will be generated
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}
# 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()
```

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

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

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

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

<Tip>
  **Modo de rendimiento**

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