> ## 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. # Modo de rendimiento (compat_mode) > Modo de rendimiento centrado en SQL que desactiva la sobrecarga de la compatibilidad con pandas para maximizar el rendimiento DataStore tiene dos modos de compatibilidad que determinan si la salida se formatea para ser compatible con pandas o se optimiza para el rendimiento de Raw SQL.
## Descripción general
| Modo | Valor de `compat_mode` | Descripción | | ------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pandas** (por defecto) | `"pandas"` | Compatibilidad total con el comportamiento de pandas. Se conserva el orden de las filas, así como MultiIndex, set\_index, correcciones de dtype, criterios de desempate en ordenaciones estables y envolturas `-If`/`isNaN`. | | **Performance** | `"performance"` | Ejecución centrada en SQL. Se elimina toda la sobrecarga de compatibilidad con pandas. Máximo rendimiento, pero los resultados pueden diferir estructuralmente de los de pandas. |
### Qué desactiva el modo de rendimiento
| Sobrecarga | Comportamiento del modo Pandas | Comportamiento del modo de rendimiento | | ------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | **Preservación del orden de las filas** | Inyección de `_row_id`, `rowNumberInAllBlocks()`, subconsultas `__orig_row_num__` | Desactivado — el orden de las filas no está garantizado | | **Criterio de desempate para ordenación estable** | `rowNumberInAllBlocks() ASC` añadido a ORDER BY | Desactivado — los empates pueden quedar en un orden arbitrario | | **`preserve_order` de Parquet** | `input_format_parquet_preserve_order=1` | Desactivado — se permite la lectura paralela de Parquet | | **ORDER BY automático en GroupBy** | Se añade `ORDER BY group_key` (valor predeterminado de pandas: `sort=True`) | Desactivado — los grupos se devuelven en orden arbitrario | | **WHERE para `dropna` en GroupBy** | Se añade `WHERE key IS NOT NULL` (valor predeterminado de pandas: `dropna=True`) | Desactivado — se incluyen grupos NULL | | **`set_index` en GroupBy** | Las claves de grupo se establecen como índice | Desactivado — las claves de grupo permanecen como columnas | | **Columnas MultiIndex** | `agg({'col': ['sum','mean']})` devuelve columnas MultiIndex | Desactivado — nombres de columna planos (`col_sum`, `col_mean`) | | **Envolturas `-If`/`isNaN`** | `sumIf(col, NOT isNaN(col))` para skipna | Desactivado — `sum(col)` simple (ClickHouse omite NULL de forma nativa) | | **`toInt64` en count** | `toInt64(count())` para ajustarse a pandas int64 | Desactivado — se devuelve el tipo nativo de SQL | | **`fillna(0)` para sumas con todo NaN** | La suma de valores todos NaN devuelve 0 (comportamiento de pandas) | Desactivado — devuelve NULL | | **Correcciones de tipo** | `abs()` de sin signo→con signo, etc. | Desactivado — tipos nativos de SQL | | **Preservación del índice** | Restaura el índice original después de ejecutar SQL | Desactivado | | **`first()`/`last()`** | `argMin/argMax(col, rowNumberInAllBlocks())` | `any(col)` / `anyLast(col)` — más rápido, pero no determinista | | **Agregación en una sola consulta SQL** | El groupby de ColumnExpr materializa un DataFrame intermedio | Inyecta `LazyGroupByAgg` en la cadena de operaciones lazy — una sola consulta SQL | ***
## Habilitar el modo de rendimiento
### Uso del objeto de configuración
```python theme={null} from chdb.datastore.config import config # Activar el modo de rendimiento config.use_performance_mode() # Volver a la compatibilidad con pandas config.use_pandas_compat() # Comprobar el modo actual print(config.compat_mode) # 'pandas' or 'performance' ```
### Uso de funciones del módulo
```python theme={null} from chdb.datastore.config import set_compat_mode, CompatMode, is_performance_mode # Habilitar el modo de rendimiento set_compat_mode(CompatMode.PERFORMANCE) # Comprobar print(is_performance_mode()) # True # Volver al valor predeterminado set_compat_mode(CompatMode.PANDAS) ```
### Uso de importaciones simplificadas
```python theme={null} from chdb import use_performance_mode, use_pandas_compat use_performance_mode() # ... operaciones de alto rendimiento ... use_pandas_compat() ``` Al activar el modo de rendimiento, el motor de ejecución se configura automáticamente en `chdb`. No es necesario llamar a `config.use_chdb()` por separado. ***
## Cuándo usar el modo de rendimiento
**Usa el modo de rendimiento cuando:** * Procesas grandes conjuntos de datos (de cientos de miles a millones de filas) * Ejecutas cargas de trabajo con mucha agregación (`groupby`, `sum`, `mean`, `count`) * El orden de las filas no importa (p. ej., resultados agregados, informes, dashboards) * Quieres el máximo rendimiento de SQL con una sobrecarga mínima * Te preocupa el uso de memoria (lectura paralela de Parquet, sin DataFrames intermedios) **Mantente en el modo pandas cuando:** * Necesitas el comportamiento exacto de pandas (orden de las filas, MultiIndex, `dtypes`) * Dependes de que `first()`/`last()` devuelvan realmente la primera/última fila * Usas `shift()`, `diff()`, `cumsum()` que dependen del orden de las filas * Estás escribiendo pruebas que comparan la salida de DataStore con pandas ***
## Diferencias de comportamiento
### Orden de las filas
En el modo de rendimiento, el orden de las filas **no está garantizado** en ninguna operación. Esto incluye: * Resultados de filtros * Resultados de agregaciones de GroupBy * `head()` / `tail()` sin `sort_values()` explícito * Agregaciones `first()` / `last()` Si necesitas resultados ordenados, añade un `sort_values()` explícito: ```python theme={null} config.use_performance_mode() ds = pd.read_csv("data.csv") # Sin orden (rápido) result = ds.groupby("region")["revenue"].sum() # Ordenado (sigue siendo rápido, solo añade ORDER BY) result = ds.groupby("region")["revenue"].sum().sort_values() ```
### Resultados de GroupBy
| Aspecto | Modo de Pandas | Modo de rendimiento | | ----------------------------------- | -------------------------------------------------- | ------------------------------------- | | Ubicación de la clave de agrupación | Índice (mediante `set_index`) | Columna normal | | Orden de agrupación | Ordenado por clave (de forma predeterminada) | Orden arbitrario | | Grupos `NULL` | Excluidos (de forma predeterminada, `dropna=True`) | Incluidos | | Formato de las columnas | MultiIndex para varias agregaciones | Nombres planos (`col_func`) | | `first()`/`last()` | Determinista (orden de las filas) | No determinista (`any()`/`anyLast()`) |
### Agregación
```python theme={null} config.use_performance_mode() # La suma de un grupo con todos NaN devuelve NULL (no 0) # Count devuelve uint64 nativo (no int64 forzado) # Sin envolturas -If: sum() en lugar de sumIf() result = ds.groupby("cat")["val"].sum() ```
### Ejecución con una sola consulta SQL
En el modo de rendimiento, la agregación `groupby` de `ColumnExpr` (p. ej., `ds[condition].groupby('col')['val'].sum()`) se ejecuta como una **única consulta SQL** en lugar del proceso de dos pasos que se utiliza en el modo pandas: ```python theme={null} config.use_performance_mode() # Modo Pandas: dos consultas SQL (filter → materialize → groupby) # Modo rendimiento: una consulta SQL (WHERE + GROUP BY en la misma consulta) result = ds[ds["rating"] > 3.5].groupby("category")["revenue"].sum() # SQL generado (consulta única): # SELECT category, sum(revenue) FROM data WHERE rating > 3.5 GROUP BY category ``` Esto evita la materialización intermedia del DataFrame y puede reducir significativamente el uso de memoria y el tiempo de ejecución. ***
## Comparación con el motor de ejecución
El modo de rendimiento (`compat_mode`) y el motor de ejecución (`execution_engine`) son **parámetros de configuración independientes**: | Config | Controla | Valores | | ------------------ | ------------------------------------------------------------- | ------------------------ | | `execution_engine` | **Qué motor** ejecuta el procesamiento | `auto`, `chdb`, `pandas` | | `compat_mode` | **Si** se adapta la salida para que sea compatible con pandas | `pandas`, `performance` | Establecer `compat_mode='performance'` configura automáticamente `execution_engine='chdb'`, ya que el modo de rendimiento está diseñado para ejecutar SQL. ```python theme={null} from chdb.datastore.config import config # Estos son independientes config.use_chdb() # Forzar motor chDB, mantener compatibilidad con pandas config.use_performance_mode() # Forzar chDB + eliminar la sobrecarga de pandas ``` ***
## Pruebas del modo de rendimiento
Al escribir pruebas para el modo de rendimiento, los resultados pueden diferir de los de pandas en el orden de las filas y en el formato estructural. Utiliza estas estrategias:
### Ordenar y luego comparar (agregaciones, filtros)
```python theme={null} # Ordenar ambos lados por las mismas columnas antes de comparar ds_result = ds.groupby("cat")["val"].sum() pd_result = pd_df.groupby("cat")["val"].sum() ds_sorted = ds_result.sort_index() pd_sorted = pd_result.sort_index() np.testing.assert_array_equal(ds_sorted.values, pd_sorted.values) ```
### Comprobación del rango de valores (primero/último)
```python theme={null} # first() con any() devuelve un elemento arbitrario del grupo result = ds.groupby("cat")["val"].first() for group_key in groups: assert result.loc[group_key] in group_values[group_key] ```
### Esquema y conteo (LIMIT sin ORDER BY)
```python theme={null} # head() sin sort_values: el conjunto de filas es no determinista result = ds.head(5) assert len(result) == 5 assert set(result.columns) == expected_columns ``` ***
## Buenas prácticas
### 1. Actívalo al principio del script
```python theme={null} from chdb.datastore.config import config config.use_performance_mode() # Todas las operaciones posteriores se benefician ds = pd.read_parquet("data.parquet") result = ds[ds["amount"] > 100].groupby("region")["amount"].sum() ```
### 2. Añada una ordenación explícita cuando el orden sea importante
```python theme={null} # Para visualización o procesamiento posterior que requiera orden result = (ds .groupby("region")["revenue"].sum() .sort_values(ascending=False) ) ```
### 3. Úselo para cargas de trabajo batch/ETL
```python theme={null} config.use_performance_mode() # Pipeline ETL — el orden no importa, el rendimiento sí summary = (ds .filter(ds["date"] >= "2024-01-01") .groupby(["region", "product"]) .agg({"revenue": "sum", "quantity": "sum", "rating": "mean"}) ) summary.to_df().to_parquet("summary.parquet") ```
### 4. Alternar entre modos dentro de una sesión
```python theme={null} # Modo de rendimiento para cálculos intensivos config.use_performance_mode() aggregated = ds.groupby("cat")["val"].sum() # De vuelta al modo pandas para comparación de coincidencia exacta config.use_pandas_compat() detailed = ds[ds["val"] > 100].head(10) ``` *** * [Motor de ejecución](/es/products/chdb/configuration/execution-engine) — Selección del motor (auto/chdb/pandas) * [Guía de rendimiento](/es/products/chdb/guides/pandas-performance) — Consejos generales de optimización * [Diferencias clave con pandas](/es/products/chdb/guides/pandas-differences) — Diferencias de comportamiento