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.
| 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
- 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
- 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()
| 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()) |
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
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
Comparación con el motor de ejecución
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 |
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
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
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)
