Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Migración desde pandas

View as MarkdownEdit this pageReport an issueSet up docs MCP

Esta guía le ayudará a migrar su código existente de pandas a DataStore para mejorar el rendimiento sin perder compatibilidad.

La migración en una sola línea

La migración más sencilla consiste en cambiar la sentencia import:

# Before (pandas)
import pandas as pd

# After (DataStore)
from chdb import datastore as pd

¡Eso es todo! La mayoría del código de pandas funciona sin cambios.

Migración paso a paso

Instalar chDB

pip install "chdb>=4.0"

Cambiar la importación

# Cambia esto:
import pandas as pd

# Por esto:
from chdb import datastore as pd

Probar el código

Ejecuta tu código actual. La mayoría de las operaciones funcionan sin cambios:

from chdb import datastore as pd

# Todo esto funciona igual
df = pd.read_csv("data.csv")
result = df[df['age'] > 25]
grouped = df.groupby('city')['salary'].mean()
df.to_csv("output.csv")

Abordar las diferencias

Algunas operaciones se comportan de forma distinta. Consulta Diferencias clave a continuación.

Qué funciona sin cambios

Carga interna de datos

# All these work the same
df = pd.read_csv("data.csv")
df = pd.read_parquet("data.parquet")
df = pd.read_json("data.json")
df = pd.read_excel("data.xlsx")

Filtrado

# Boolean indexing
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

# query() method
df.query('age > 25 and salary > 50000')

Selección

# Column selection
df['name']
df[['name', 'age']]

# Row selection
df.head(10)
df.tail(10)
df.iloc[0:100]

GroupBy y agregación

# GroupBy
df.groupby('city')['salary'].mean()
df.groupby(['city', 'dept']).agg({'salary': ['sum', 'mean']})

Ordenación

df.sort_values('salary', ascending=False)
df.sort_values(['city', 'age'])

Operaciones con cadenas

df['name'].str.upper()
df['name'].str.contains('John')
df['name'].str.len()

Operaciones con DateTime

df['date'].dt.year
df['date'].dt.month
df['date'].dt.dayofweek

Operaciones de E/S

df.to_csv("output.csv")
df.to_parquet("output.parquet")
df.to_json("output.json")

Diferencias clave

1. Evaluación diferida

Las operaciones de DataStore se evalúan de forma diferida: no se ejecutan hasta que se necesitan los resultados.

pandas:

# Executes immediately
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame

DataStore:

# Builds query, doesn't execute yet
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (lazy)

# Executes when you need the data
print(result)        # Triggers execution
df = result.to_df()  # Triggers execution

2. Tipos de retorno

Operación Resultado en pandas Resultado en DataStore
df['col'] Series ColumnExpr (diferido)
df[['a', 'b']] DataFrame DataStore (diferido)
df[condition] DataFrame DataStore (diferido)
df.groupby('x') GroupBy LazyGroupBy

3. Sin parámetro inplace

DataStore no admite inplace=True. Usa siempre el valor devuelto:

pandas:

df.drop(columns=['col'], inplace=True)

DataStore:

ds = ds.drop(columns=['col'])  # Assign the result

4. Comparación de DataStores

pandas no reconoce los objetos DataStore, así que utiliza to_pandas() para compararlos:

# This may not work as expected
df == ds  # pandas doesn't know DataStore

# Do this instead
df.equals(ds.to_pandas())

5. Orden de las filas

Es posible que DataStore no conserve el orden de las filas en orígenes de archivo (como las bases de datos SQL). Use una ordenación explícita:

# pandas preserves order
df = pd.read_csv("data.csv")

# DataStore - use sort for guaranteed order
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # Explicit ordering

Patrones de migración

Patrón 1: Leer-analizar-escribir

# pandas
import pandas as pd

df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")

# DataStore - same code works!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['amount'] > 100].groupby('category')['amount'].sum()
result.to_csv("output.csv")

Patrón 2: DataFrame con operaciones de pandas

Si necesitas características específicas de pandas, conviértelo al final:

from chdb import datastore as pd

# Fast DataStore operations
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# Convert to pandas for specific features
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # pandas-specific

Patrón 3: Flujo de trabajo mixto

from chdb import datastore as pd
import pandas

# Start with DataStore for fast filtering
ds = pd.read_csv("huge_file.csv")  # 10M rows
ds = ds.filter(ds['year'] == 2024)  # Fast SQL filter
ds = ds.select('col1', 'col2', 'col3')  # Column pruning

# Convert for pandas-specific operations
df = ds.to_df()  # Now only ~100K rows
result = df.apply(complex_custom_function)  # pandas

Comparación de rendimiento

DataStore es significativamente más rápido con grandes conjuntos de datos:

Operación pandas DataStore Mejora
GroupBy count 347ms 17ms 19.93x
Pipeline complejo 2,047ms 380ms 5.39x
Filter+Sort+Head 1,537ms 350ms 4.40x
GroupBy agg 406ms 141ms 2.88x

Benchmark con 10M de filas

Solución de problemas de la migración

Problema: La operación no funciona

Es posible que algunas operaciones de pandas no sean compatibles. Comprueba lo siguiente:

  1. ¿La operación está en la lista de compatibilidad?
  2. Prueba primero a convertirlo a pandas: ds.to_df().operation()

Problema: resultados diferentes

Active el registro de depuración para entender qué está ocurriendo:

from chdb.datastore.config import config
config.enable_debug()

# View the SQL being generated
ds.filter(ds['x'] > 10).explain()

Problema: rendimiento lento

Revisa tu patrón de ejecución:

# Bad: Multiple small executions
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# Good: Single execution
result = ds.filter(ds['id'].isin(ids)).to_df()

Problema: desajustes de tipos

DataStore puede inferir los tipos de forma distinta:

# Check types
print(ds.dtypes)

# Force conversion
ds['col'] = ds['col'].astype('int64')

Estrategia de migración gradual

Semana 1: Probar la compatibilidad

# Keep both imports
import pandas as pd

from chdb import datastore as ds

# Compare results
pdf = pd.read_csv("data.csv")
dsf = ds.read_csv("data.csv")

# Verify they match
assert pdf.equals(dsf.to_pandas())

Semana 2: Migra los scripts simples

Comienza con scripts que:

  • leen archivos grandes
  • hacen filtrado y agregación
  • no usan funciones apply personalizadas

Semana 3: Aborda casos complejos

Para scripts con funciones personalizadas:

from chdb import datastore as pd

# Let DataStore handle the heavy lifting
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# Convert for custom work
df = ds.to_df()
result = df.apply(my_custom_function)

Semana 4: Migración completa

Actualice todos los scripts para que usen la importación de DataStore.

Preguntas frecuentes

¿Puedo usar tanto pandas como DataStore?

¡Sí! Puedes convertir entre ambos libremente:

from chdb import datastore as ds
import pandas as pd

# DataStore to pandas
df = ds_result.to_pandas()

# pandas to DataStore  
ds = ds.DataFrame(pd_result)

¿Seguirán pasando mis pruebas?

La mayoría de las pruebas deberían pasar. En el caso de las pruebas de comparación, conviértalas a pandas:

def test_my_function():
    result = my_function()
    expected = pd.DataFrame(...)
    pd.testing.assert_frame_equal(result.to_pandas(), expected)

¿Puedo usar DataStore en Jupyter?

¡Sí! DataStore funciona en los cuadernos de Jupyter:

from chdb import datastore as pd

ds = pd.read_csv("data.csv")
ds.head()  # Displays nicely in Jupyter

¿Cómo reporto issues?

Si encuentras problemas de compatibilidad, repórtalos en: https://github.com/chdb-io/chdb/issues

Navigation