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

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

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

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:

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

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:

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.

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)

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

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

# 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

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

# 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

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

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

---

​

Documentación relacionada

• Motor de ejecución — Selección del motor (auto/chdb/pandas)
• Guía de rendimiento — Consejos generales de optimización
• Diferencias clave con pandas — Diferencias de comportamiento