Migración desde pandas

Guía paso a paso para migrar de pandas a DataStore

Esta guía le ayuda a migrar su código actual de pandas a DataStore para obtener un mejor rendimiento sin perder compatibilidad.

​

La migración en una sola línea

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

# Antes (pandas)
import pandas as pd

# Después (DataStore)
from chdb import datastore as pd

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

​

Migración paso a paso

1. ​

   Instala chDB

   pip install "chdb>=4.0"
   
2. ​

   Cambia la importación

   # Cambia esto:
   import pandas as pd
   
   # Por esto:
   from chdb import datastore as pd
   
3. ​

   Prueba tu 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")
   
4. ​

   Ten en cuenta las diferencias

   Algunas operaciones se comportan de manera diferente. Consulta Diferencias clave a continuación.

---

​

Lo que funciona sin cambios

​

Carga de datos

# Todos estos funcionan igual
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

# Indexación booleana
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

# método query()
df.query('age > 25 and salary > 50000')

​

Selección

# Selección de columnas
df['name']
df[['name', 'age']]

# Selección de filas
df.head(10)
df.tail(10)
df.iloc[0:100]

​

GroupBy y agregación

# Agrupar por
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 de texto

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

​

Operaciones de 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 principales

​

1. Evaluación diferida

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

pandas:

# Se ejecuta inmediatamente
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame

DataStore:

# Construye la consulta, aún no la ejecuta
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (diferida)

# Se ejecuta cuando necesitas los datos
print(result)        # Activa la ejecución
df = result.to_df()  # Activa la ejecución

​

2. Tipos de retorno

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

​

3. No existe el 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'])  # Asignar el resultado

​

4. Comparación de DataStores

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

# Esto puede no funcionar como se espera
df == ds  # pandas no reconoce DataStore

# Haz esto en su lugar
df.equals(ds.to_pandas())

​

5. Orden de las filas

DataStore puede no conservar el orden de las filas en fuentes de datos como archivos o bases de datos SQL. Use una ordenación explícita:

# pandas preserva el orden
df = pd.read_csv("data.csv")

# DataStore - usar sort para orden garantizado
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # Orden explícito

---

​

Patrones de migración

​

Patrón 1: Lectura-análisis-escritura

# 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: ¡el mismo código funciona!
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 funciones específicas de pandas, haz la conversión al final:

from chdb import datastore as pd

# Operaciones rápidas de DataStore
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# Convertir a pandas para funciones específicas
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # específico de pandas

​

Patrón 3: Flujo de trabajo mixto

from chdb import datastore as pd
import pandas

# Comenzar con DataStore para filtrado rápido
ds = pd.read_csv("huge_file.csv")  # 10M filas
ds = ds.filter(ds['year'] == 2024)  # Filtro SQL rápido
ds = ds.select('col1', 'col2', 'col3')  # Poda de columnas

# Convertir para operaciones específicas de pandas
df = ds.to_df()  # Ahora solo ~100K filas
result = df.apply(complex_custom_function)  # pandas

---

​

Comparación de rendimiento

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

Operación	pandas	DataStore	Mejora
Recuento con GroupBy	347ms	17ms	19.93x
pipeline compleja	2,047ms	380ms	5.39x
Filter+Sort+Head	1,537ms	350ms	4.40x
Agregación con GroupBy	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 aparece en la lista de compatibilidad?
2. Prueba a convertirlo primero a pandas: ds.to_df().operation()

​

Problema: Resultados diferentes

Activa el registro de depuración para entender qué ocurre:

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

# Ver el SQL que se está generando
ds.filter(ds['x'] > 10).explain()

​

Problema: rendimiento lento

Revise su patrón de ejecución:

# Mal: varias ejecuciones pequeñas
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# Bien: una sola ejecución
result = ds.filter(ds['id'].isin(ids)).to_df()

​

Problema: Desajustes de tipos

DataStore puede inferir los tipos de manera distinta:

# Comprobar tipos
print(ds.dtypes)

# Forzar conversión
ds['col'] = ds['col'].astype('int64')

---

​

Estrategia de migración gradual

​

Semana 1: Comprobar la compatibilidad

# Mantener ambas importaciones
import pandas as pd
from chdb import datastore as ds

# Comparar resultados
pdf = pd.read_csv("data.csv")
dsf = ds.read_csv("data.csv")

# Verificar que coincidan
assert pdf.equals(dsf.to_pandas())

​

Semana 2: Cambiar scripts sencillos

Empieza con scripts que:

• Lean archivos grandes
• Hagan filtrado y agregación
• No usen funciones apply personalizadas

​

Semana 3: Aborda casos complejos

Para scripts con funciones personalizadas:

from chdb import datastore as pd

# Dejar que DataStore haga el trabajo pesado
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# Convertir para trabajo personalizado
df = ds.to_df()
result = df.apply(my_custom_function)

​

Semana 4: Migración completa

Cambie todos los scripts para que importen 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

# De DataStore a pandas
df = ds_result.to_pandas()

# De pandas a DataStore  
ds = ds.DataFrame(pd_result)

​

¿Seguirán pasando mis pruebas?

La mayoría de las pruebas deberían seguir pasando. Para las pruebas de comparación, convierta 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 notebooks de Jupyter:

from chdb import datastore as pd

ds = pd.read_csv("data.csv")
ds.head()  # Se visualiza correctamente en Jupyter

​

¿Cómo puedo reportar problemas?

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