> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Principais diferenças em relação ao pandas

> Diferenças importantes entre DataStore e pandas

Embora o DataStore seja altamente compatível com o pandas, é importante entender algumas diferenças.

<div id="summary">
  ## Tabela resumida
</div>

| Aspecto              | pandas                    | DataStore                                                                                                           |
| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Execução**         | imediata (imediata)       | lazy (adiada)                                                                                                       |
| **Tipos de retorno** | DataFrame/Series          | DataStore/ColumnExpr                                                                                                |
| **Ordem das linhas** | Preservada                | Preservada (automática); não garantida no [modo de desempenho](/pt-BR/products/chdb/configuration/performance-mode) |
| **inplace**          | Compatível                | Não compatível                                                                                                      |
| **Índice**           | Suporte completo          | Simplificado                                                                                                        |
| **Memória**          | Todos os dados em memória | Dados na origem                                                                                                     |

***

<div id="lazy-execution">
  ## 1. Execução lazy vs imediata
</div>

<div id="pandas-eager">
  ### pandas (Execução imediata)
</div>

As operações são executadas imediatamente:

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

df = pd.read_csv("data.csv")  # Carrega o arquivo inteiro AGORA
result = df[df['age'] > 25]   # Filtra AGORA
grouped = result.groupby('city')['salary'].mean()  # Agrega AGORA
```

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

As operações só são executadas quando os resultados são necessários:

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

ds = pd.read_csv("data.csv")  # Apenas registra a fonte
result = ds[ds['age'] > 25]   # Apenas registra o filtro
grouped = result.groupby('city')['salary'].mean()  # Apenas registra

# A execução ocorre aqui:
print(grouped)        # Executa ao exibir
df = grouped.to_df()  # Ou ao converter para pandas
```

<div id="why-lazy">
  ### Por que isso importa
</div>

A execução lazy permite:

* **Otimização de consulta**: várias operações são compiladas em uma única consulta SQL
* **Poda de colunas**: apenas as colunas necessárias são lidas
* **Pushdown de filtros**: os filtros são aplicados na fonte
* **Eficiência no uso de memória**: não carrega dados desnecessários

***

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

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

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

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

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

<div id="converting-to-pandas-types">
  ### Convertendo para os tipos do pandas
</div>

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

# Obter Series do pandas a partir de uma coluna
series = ds['col'].to_pandas()

# Ou acionar a execução
print(ds)  # Converte automaticamente para exibição
```

***

<div id="triggers">
  ## 3. Gatilhos de execução
</div>

O DataStore é executado quando você precisa dos valores reais:

| Gatilho              | Exemplo            | Observações                 |
| -------------------- | ------------------ | --------------------------- |
| `print()` / `repr()` | `print(ds)`        | A exibição requer dados     |
| `len()`              | `len(ds)`          | Requer a contagem de linhas |
| `.columns`           | `ds.columns`       | Requer os nomes das colunas |
| `.dtypes`            | `ds.dtypes`        | Requer informações de tipo  |
| `.shape`             | `ds.shape`         | Requer as dimensões         |
| `.values`            | `ds.values`        | Requer os dados reais       |
| `.index`             | `ds.index`         | Requer o índice             |
| `to_df()`            | `ds.to_df()`       | Conversão explícita         |
| Iteração             | `for row in ds`    | Requer iteração             |
| `equals()`           | `ds.equals(other)` | Requer comparação           |

<div id="stay-lazy">
  ### Operações que permanecem lazy
</div>

| Operação         | Retorno     |
| ---------------- | ----------- |
| `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. Ordem das linhas
</div>

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

A ordem das linhas é sempre preservada:

```python theme={null}
df = pd.read_csv("data.csv")
print(df.head())  # Sempre na mesma ordem do arquivo
```

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

A ordem das linhas é **mantida automaticamente** na maioria das operações:

```python theme={null}
ds = pd.read_csv("data.csv")
print(ds.head())  # Corresponde à ordem do arquivo

# O filtro preserva a ordem
ds_filtered = ds[ds['age'] > 25]  # Mesma ordem que o pandas
```

O DataStore rastreia automaticamente, de forma interna, as posições originais das linhas (usando `rowNumberInAllBlocks()`) para garantir a consistência da ordem em relação ao pandas.

<div id="order-preserved">
  ### Quando a ordem é preservada
</div>

* Fontes de arquivo (CSV, Parquet, JSON etc.)
* Fontes de DataFrame do pandas
* Operações de filtro
* Seleção de colunas
* Após `sort()` ou `sort_values()` executados explicitamente
* Operações que definem a ordem (`nlargest()`, `nsmallest()`, `head()`, `tail()`)

<div id="order-may-differ">
  ### Quando a ordem pode variar
</div>

* Após agregações com `groupby()` (use `sort_values()` para garantir uma ordem consistente)
* Após `merge()` / `join()` com determinados tipos de join
* No **modo de desempenho** (`config.use_performance_mode()`): a ordem das linhas não é garantida em nenhuma operação. Veja [Modo de desempenho](/pt-BR/products/chdb/configuration/performance-mode).

***

<div id="no-inplace">
  ## 5. Sem 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` não é suportado. Sempre atribua o resultado:

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

<div id="why-no-inplace">
  ### Por que não existe inplace?
</div>

O DataStore usa operações imutáveis para permitir:

* Construção de consultas (avaliação lazy)
* Segurança entre threads
* Depuração mais fácil
* Código mais limpo

***

<div id="index">
  ## 6. Suporte a índices
</div>

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

Suporte completo a índices:

```python theme={null}
df = df.set_index('id')
df.loc['user123']           # Acesso baseado em rótulo
df.loc['a':'z']             # Fatiamento baseado em rótulo
df.reset_index()
df.index.name = 'user_id'
```

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

Suporte simplificado para índices:

```python theme={null}
# Operações básicas funcionam
ds.loc[0:10]               # Posição inteira
ds.iloc[0:10]              # Igual a loc para DataStore

# Para operações de índice no estilo pandas, converta primeiro
df = ds.to_df()
df = df.set_index('id')
df.loc['user123']
```

<div id="datastore-source-matters">
  ### A fonte do DataStore faz diferença
</div>

* **Fonte DataFrame**: Preserva o índice do pandas
* **Fonte File**: Usa um índice inteiro simples

***

<div id="comparison">
  ## 7. Comportamento das comparações
</div>

<div id="comparing-with-pandas">
  ### Comparando com o pandas
</div>

O pandas não reconhece 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]})

# Isso não funciona como esperado
pdf == dsf  # pandas não reconhece DataStore

# Solução: converter DataStore para pandas
pdf.equals(dsf.to_pandas())  # True
```

<div id="using-equals">
  ### Como usar equals()
</div>

```python theme={null}
# DataStore.equals() também funciona
dsf.equals(pdf)  # Compara com pandas DataFrame
```

***

<div id="types">
  ## 8. Inferência de tipos
</div>

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

Usa os tipos do numpy/pandas:

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

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

Pode usar os tipos do ClickHouse:

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

# Os tipos são convertidos ao exportar para pandas
df = ds.to_df()
df['col'].dtype  # Agora é tipo pandas
```

<div id="explicit-casting">
  ### Conversão explícita de tipo
</div>

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

***

<div id="memory">
  ## 9. Modelo de memória
</div>

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

Todos os dados ficam na memória:

```python theme={null}
df = pd.read_csv("huge.csv")  # 10GB na memória!
```

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

Os dados permanecem na origem até que sejam necessários:

```python theme={null}
ds = pd.read_csv("huge.csv")  # Apenas metadados
ds = ds.filter(ds['year'] == 2024)  # Ainda apenas metadados

# Apenas o resultado filtrado é carregado
df = ds.to_df()  # Talvez apenas 1GB agora
```

***

<div id="errors">
  ## 10. Mensagens de erro
</div>

<div id="different-error-sources">
  ### Diferentes Fontes de Erro
</div>

* **erros do pandas**: Da biblioteca pandas
* **erros do DataStore**: Do chDB ou do ClickHouse

```python theme={null}
# Pode exibir erros no estilo ClickHouse
# "Code: 62. DB::Exception: Syntax error..."
```

<div id="debugging-tips">
  ### Dicas de depuração
</div>

```python theme={null}
# Visualize o SQL para depuração
print(ds.to_sql())

# Veja o plano de execução
ds.explain()

# Ative o logging de depuração
from chdb.datastore.config import config
config.enable_debug()
```

***

<div id="checklist">
  ## Checklist de migração
</div>

Ao migrar do pandas:

* [ ] Altere a instrução de importação
* [ ] Remova os parâmetros `inplace=True`
* [ ] Adicione `to_df()` explicitamente onde um DataFrame do pandas for necessário
* [ ] Adicione ordenação se a ordem das linhas for importante
* [ ] Use `to_pandas()` em testes de comparação
* [ ] Teste com volumes de dados representativos

***

<div id="quick-ref">
  ## Referência rápida
</div>

| pandas                  | DataStore                      |
| ----------------------- | ------------------------------ |
| `df[condition]`         | Mesmo (retorna DataStore)      |
| `df.groupby()`          | Mesmo (retorna 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)`             | Mesmo (dispara a execução)     |
| `len(df)`               | Mesmo (dispara a execução)     |