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

# Diferencias clave con pandas

> Diferencias importantes entre DataStore y pandas

Aunque DataStore es muy compatible con pandas, hay diferencias importantes que conviene entender.

<div id="summary">
  ## Tabla resumen
</div>

| Aspecto                | pandas                     | DataStore                                                                                                                        |
| ---------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Ejecución**          | Inmediata                  | Diferida                                                                                                                         |
| **Tipos de retorno**   | DataFrame/Series           | DataStore/ColumnExpr                                                                                                             |
| **Orden de las filas** | Se conserva                | Se conserva (automáticamente); no está garantizado en el [modo de rendimiento](/es/products/chdb/configuration/performance-mode) |
| **inplace**            | Admitido                   | No admitido                                                                                                                      |
| **Índice**             | Compatibilidad completa    | Simplificado                                                                                                                     |
| **Memoria**            | Todos los datos en memoria | Los datos permanecen en el origen                                                                                                |

***

<div id="lazy-execution">
  ## 1. Ejecución diferida frente a ejecución inmediata
</div>

<div id="pandas-eager">
  ### pandas (inmediato)
</div>

Las operaciones se ejecutan de inmediato:

```python theme={null}
import pandas as pd

df = pd.read_csv("data.csv")  # Carga el archivo completo AHORA
result = df[df['age'] > 25]   # Filtra AHORA
grouped = result.groupby('city')['salary'].mean()  # Agrega AHORA
```

<div id="datastore-lazy">
  ### DataStore (diferido)
</div>

Las operaciones se aplazan hasta que se necesitan los resultados:

```python theme={null}
from chdb import datastore as pd

ds = pd.read_csv("data.csv")  # Solo registra la fuente
result = ds[ds['age'] > 25]   # Solo registra el filtro
grouped = result.groupby('city')['salary'].mean()  # Solo registra

# La ejecución ocurre aquí:
print(grouped)        # Se ejecuta al mostrar
df = grouped.to_df()  # O al convertir a pandas
```

<div id="why-lazy">
  ### Por qué es importante
</div>

La ejecución diferida permite:

* **Optimización de consultas**: Varias operaciones se compilan en una sola consulta SQL
* **Poda de columnas**: Solo se leen las columnas necesarias
* **Ejecución de filtros en el origen**: Los filtros se aplican en el origen
* **Uso eficiente de la memoria**: No se cargan datos innecesarios

***

<div id="return-types">
  ## 2. Tipos de retorno
</div>

<div id="pandas-return-types">
  ### pandas
</div>

```python theme={null}
df['col']           # Devuelve pd.Series
df[['a', 'b']]      # Devuelve pd.DataFrame
df[df['x'] > 10]    # Devuelve pd.DataFrame
df.groupby('x')     # Devuelve DataFrameGroupBy
```

<div id="datastore-return-types">
  ### DataStore
</div>

```python theme={null}
ds['col']           # Devuelve ColumnExpr (lazy)
ds[['a', 'b']]      # Devuelve DataStore (lazy)
ds[ds['x'] > 10]    # Devuelve DataStore (lazy)
ds.groupby('x')     # Devuelve LazyGroupBy
```

<div id="converting-to-pandas-types">
  ### Conversión a tipos de pandas
</div>

```python theme={null}
# Obtener DataFrame de pandas
df = ds.to_df()
df = ds.to_pandas()

# Obtener Series de pandas desde una columna
series = ds['col'].to_pandas()

# O disparar la ejecución
print(ds)  # Convierte automáticamente para mostrar
```

***

<div id="triggers">
  ## 3. Desencadenantes de ejecución
</div>

DataStore se ejecuta cuando se necesitan valores reales:

| Desencadenante       | Ejemplo            | Notas                                    |
| -------------------- | ------------------ | ---------------------------------------- |
| `print()` / `repr()` | `print(ds)`        | La visualización requiere datos          |
| `len()`              | `len(ds)`          | Se necesita el recuento de filas         |
| `.columns`           | `ds.columns`       | Se necesitan los nombres de las columnas |
| `.dtypes`            | `ds.dtypes`        | Se necesita información sobre los tipos  |
| `.shape`             | `ds.shape`         | Se necesitan las dimensiones             |
| `.values`            | `ds.values`        | Se necesitan los datos reales            |
| `.index`             | `ds.index`         | Se necesita el índice                    |
| `to_df()`            | `ds.to_df()`       | Conversión explícita                     |
| Iteración            | `for row in ds`    | Se necesita iterar                       |
| `equals()`           | `ds.equals(other)` | Se necesita la comparación               |

<div id="stay-lazy">
  ### Operaciones que permanecen diferidas
</div>

| Operación        | Devuelve    |
| ---------------- | ----------- |
| `filter()`       | DataStore   |
| `select()`       | DataStore   |
| `sort()`         | DataStore   |
| `groupby()`      | LazyGroupBy |
| `join()`         | DataStore   |
| `ds['col']`      | ColumnExpr  |
| `ds[['a', 'b']]` | DataStore   |
| `ds[condition]`  | DataStore   |

***

<div id="row-order">
  ## 4. Orden de filas
</div>

<div id="pandas-return-types">
  ### pandas
</div>

El orden de las filas siempre se mantiene:

```python theme={null}
df = pd.read_csv("data.csv")
print(df.head())  # Siempre en el mismo orden que el archivo
```

<div id="datastore-return-types">
  ### DataStore
</div>

El orden de las filas **se conserva automáticamente** en la mayoría de las operaciones:

```python theme={null}
ds = pd.read_csv("data.csv")
print(ds.head())  # Coincide con el orden del archivo

# El filtro conserva el orden
ds_filtered = ds[ds['age'] > 25]  # Mismo orden que pandas
```

DataStore rastrea automáticamente las posiciones originales de las filas de forma interna (mediante `rowNumberInAllBlocks()`) para garantizar la coherencia del orden con pandas.

<div id="order-preserved">
  ### Cuando se conserva el orden
</div>

* Fuentes de archivos (CSV, Parquet, JSON, etc.)
* Fuentes de DataFrame de pandas
* Operaciones de filtro
* Selección de columnas
* Después de una llamada explícita a `sort()` o `sort_values()`
* Operaciones que definen el orden (`nlargest()`, `nsmallest()`, `head()`, `tail()`)

<div id="order-may-differ">
  ### Cuándo el orden puede variar
</div>

* Después de las agregaciones de `groupby()` (utilice `sort_values()` para garantizar un orden coherente)
* Después de `merge()` / `join()` con ciertos tipos de join
* En **modo de rendimiento** (`config.use_performance_mode()`): el orden de las filas no está garantizado en ninguna operación. Consulte [Modo de rendimiento](/es/products/chdb/configuration/performance-mode).

***

<div id="no-inplace">
  ## 5. Sin parámetro inplace
</div>

<div id="pandas-return-types">
  ### pandas
</div>

```python theme={null}
df.drop(columns=['col'], inplace=True)  # Modifica df
df.fillna(0, inplace=True)              # Modifica df
df.rename(columns={'old': 'new'}, inplace=True)
```

<div id="datastore-return-types">
  ### DataStore
</div>

`inplace=True` no se admite. Asigna siempre el resultado:

```python theme={null}
ds = ds.drop(columns=['col'])           # Devuelve un nuevo DataStore
ds = ds.fillna(0)                       # Devuelve un nuevo DataStore
ds = ds.rename(columns={'old': 'new'})  # Devuelve un nuevo DataStore
```

<div id="why-no-inplace">
  ### ¿Por qué no usar inplace?
</div>

DataStore usa operaciones inmutables para favorecer:

* La construcción de consultas (evaluación diferida)
* La seguridad en entornos multihilo
* Una depuración más sencilla
* Un código más limpio

***

<div id="index">
  ## 6. Soporte de índices
</div>

<div id="pandas-return-types">
  ### pandas
</div>

Compatibilidad completa con índices:

```python theme={null}
df = df.set_index('id')
df.loc['user123']           # Acceso basado en etiquetas
df.loc['a':'z']             # Segmentación basada en etiquetas
df.reset_index()
df.index.name = 'user_id'
```

<div id="datastore-return-types">
  ### DataStore
</div>

Soporte simplificado para índices:

```python theme={null}
# Las operaciones básicas funcionan
ds.loc[0:10]               # Posición entera
ds.iloc[0:10]              # Igual que loc para DataStore

# Para operaciones de índice estilo pandas, convertir primero
df = ds.to_df()
df = df.set_index('id')
df.loc['user123']
```

<div id="datastore-source-matters">
  ### La fuente de DataStore importa
</div>

* **Fuente DataFrame**: Conserva el índice de pandas
* **Fuente File**: Usa un índice entero simple

***

<div id="comparison">
  ## 7. Comportamiento de las comparaciones
</div>

<div id="comparing-with-pandas">
  ### Comparación con pandas
</div>

pandas no reconoce los objetos DataStore:

```python theme={null}
import pandas as pd
from chdb import datastore as ds

pdf = pd.DataFrame({'a': [1, 2, 3]})
dsf = ds.DataFrame({'a': [1, 2, 3]})

# Esto no funciona como se espera
pdf == dsf  # pandas no reconoce DataStore

# Solución: convertir DataStore a pandas
pdf.equals(dsf.to_pandas())  # True
```

<div id="using-equals">
  ### Uso de equals()
</div>

```python theme={null}
# DataStore.equals() también funciona
dsf.equals(pdf)  # Compara con un DataFrame de pandas
```

***

<div id="types">
  ## 8. Inferencia de tipos
</div>

<div id="pandas-return-types">
  ### pandas
</div>

Utiliza tipos de numpy/pandas:

```python theme={null}
df['col'].dtype  # int64, float64, object, datetime64, etc.
```

<div id="datastore-return-types">
  ### DataStore
</div>

Puede utilizar tipos de ClickHouse:

```python theme={null}
ds['col'].dtype  # Int64, Float64, String, DateTime, etc.

# Los tipos se convierten al pasar a pandas
df = ds.to_df()
df['col'].dtype  # Ahora es tipo pandas
```

<div id="explicit-casting">
  ### Conversión explícita
</div>

```python theme={null}
# Forzar tipo específico
ds['col'] = ds['col'].astype('int64')
```

***

<div id="memory">
  ## 9. Modelo de memoria
</div>

<div id="pandas-return-types">
  ### pandas
</div>

Todos los datos se almacenan en memoria:

```python theme={null}
df = pd.read_csv("huge.csv")  # ¡10 GB en memoria!
```

<div id="datastore-return-types">
  ### DataStore
</div>

Los datos permanecen en su origen hasta que se necesitan:

```python theme={null}
ds = pd.read_csv("huge.csv")  # Solo metadatos
ds = ds.filter(ds['year'] == 2024)  # Todavía solo metadatos

# Solo se carga el resultado filtrado
df = ds.to_df()  # Quizás solo 1 GB ahora
```

***

<div id="errors">
  ## 10. Mensajes de error
</div>

<div id="different-error-sources">
  ### Diferentes fuentes de errores
</div>

* **errores de pandas**: De la biblioteca pandas
* **errores de DataStore**: De chDB o ClickHouse

```python theme={null}
# Es posible ver errores de estilo ClickHouse
# "Code: 62. DB::Exception: Syntax error..."
```

<div id="debugging-tips">
  ### Consejos de depuración
</div>

```python theme={null}
# Ver el SQL para depurar
print(ds.to_sql())

# Ver el plan de ejecución
ds.explain()

# Habilitar el registro de depuración
from chdb.datastore.config import config
config.enable_debug()
```

***

<div id="checklist">
  ## Lista de comprobación para la migración
</div>

Al migrar desde pandas:

* [ ] Cambie la instrucción de importación
* [ ] Elimine los parámetros `inplace=True`
* [ ] Añada `to_df()` de forma explícita cuando se requiera un DataFrame de pandas
* [ ] Añada ordenación si el orden de las filas es importante
* [ ] Use `to_pandas()` para las pruebas de comparación
* [ ] Haga pruebas con tamaños de datos representativos

***

<div id="quick-ref">
  ## Referencia rápida
</div>

| pandas                  | DataStore                      |
| ----------------------- | ------------------------------ |
| `df[condition]`         | Igual (devuelve DataStore)     |
| `df.groupby()`          | Igual (devuelve LazyGroupBy)   |
| `df.drop(inplace=True)` | `ds = ds.drop()`               |
| `df.equals(other)`      | `ds.to_pandas().equals(other)` |
| `df.loc['label']`       | `ds.to_df().loc['label']`      |
| `print(df)`             | Igual (ejecuta la operación)   |
| `len(df)`               | Igual (ejecuta la operación)   |