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

# Migração a partir do pandas

> Guia passo a passo para migrar do pandas para o DataStore

Este guia ajuda você a migrar seu código existente em pandas para o DataStore, para obter melhor desempenho sem perder a compatibilidade.

<div id="one-line">
  ## A migração em uma linha
</div>

A migração mais simples é alterar a instrução de importação:

```python theme={null}
# Antes (pandas)
import pandas as pd

# Depois (DataStore)
from chdb import datastore as pd
```

É isso! A maior parte do código em pandas funciona sem alterações.

<div id="step-by-step">
  ## Migração passo a passo
</div>

<Steps>
  <Step>
    ### Instale o chDB

    ```bash theme={null}
    pip install "chdb>=4.0"
    ```
  </Step>

  <Step>
    ### Altere a importação

    ```python theme={null}
    # Altere isto:
    import pandas as pd

    # Para isto:
    from chdb import datastore as pd
    ```
  </Step>

  <Step>
    ### Teste seu código

    Execute seu código atual. A maioria das operações funciona sem alterações:

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

    # Todos estes funcionam da mesma forma
    df = pd.read_csv("data.csv")
    result = df[df['age'] > 25]
    grouped = df.groupby('city')['salary'].mean()
    df.to_csv("output.csv")
    ```
  </Step>

  <Step>
    ### Lide com as diferenças

    Algumas operações se comportam de forma diferente. Veja [Principais diferenças](#differences) abaixo.
  </Step>
</Steps>

***

<div id="works-unchanged">
  ## O que funciona sem alterações
</div>

<div id="loading-unchanged">
  ### Carregamento de dados
</div>

```python theme={null}
# Todos esses funcionam da mesma forma
df = pd.read_csv("data.csv")
df = pd.read_parquet("data.parquet")
df = pd.read_json("data.json")
df = pd.read_excel("data.xlsx")
```

<div id="filtering-unchanged">
  ### Filtragem
</div>

```python theme={null}
# Indexação booleana
df[df['age'] > 25]
df[(df['age'] > 25) & (df['city'] == 'NYC')]

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

<div id="selection-unchanged">
  ### Seleção
</div>

```python theme={null}
# Seleção de colunas
df['name']
df[['name', 'age']]

# Seleção de linhas
df.head(10)
df.tail(10)
df.iloc[0:100]
```

<div id="groupby-unchanged">
  ### GroupBy e agregação
</div>

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

<div id="sorting-unchanged">
  ### Ordenação
</div>

```python theme={null}
df.sort_values('salary', ascending=False)
df.sort_values(['city', 'age'])
```

<div id="string-unchanged">
  ### Operações com String
</div>

```python theme={null}
df['name'].str.upper()
df['name'].str.contains('John')
df['name'].str.len()
```

<div id="datetime-unchanged">
  ### Operações com DateTime
</div>

```python theme={null}
df['date'].dt.year
df['date'].dt.month
df['date'].dt.dayofweek
```

<div id="io-unchanged">
  ### Operações de E/S
</div>

```python theme={null}
df.to_csv("output.csv")
df.to_parquet("output.parquet")
df.to_json("output.json")
```

***

<div id="differences">
  ## Principais diferenças
</div>

<div id="lazy">
  ### 1. Avaliação preguiçosa
</div>

As operações do DataStore são avaliadas de forma preguiçosa - só são executadas quando os resultados são necessários.

**pandas:**

```python theme={null}
# Executa imediatamente
result = df[df['age'] > 25]
print(type(result))  # pandas.DataFrame
```

**DataStore:**

```python theme={null}
# Constrói a consulta, mas ainda não executa
result = ds[ds['age'] > 25]
print(type(result))  # DataStore (preguiçoso)

# Executa quando os dados são necessários
print(result)        # Dispara a execução
df = result.to_df()  # Dispara a execução
```

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

| Operação          | Retornos do pandas | Retornos do DataStore   |
| ----------------- | ------------------ | ----------------------- |
| `df['col']`       | Series             | ColumnExpr (preguiçoso) |
| `df[['a', 'b']]`  | DataFrame          | DataStore (preguiçoso)  |
| `df[condition]`   | DataFrame          | DataStore (preguiçoso)  |
| `df.groupby('x')` | GroupBy            | LazyGroupBy             |

<div id="no-inplace">
  ### 3. Sem o parâmetro inplace
</div>

O DataStore não oferece suporte a `inplace=True`. Sempre use o valor retornado:

**pandas:**

```python theme={null}
df.drop(columns=['col'], inplace=True)
```

**DataStore:**

```python theme={null}
ds = ds.drop(columns=['col'])  # Atribua o resultado
```

<div id="comparing">
  ### 4. Comparando DataStores
</div>

O pandas não reconhece objetos DataStore, então use `to_pandas()` para fazer a comparação:

```python theme={null}
# Isso pode não funcionar como esperado
df == ds  # pandas não reconhece DataStore

# Faça isso em vez disso
df.equals(ds.to_pandas())
```

<div id="row-order">
  ### 5. Ordem das linhas
</div>

DataStore pode não preservar a ordem das linhas em fontes baseadas em arquivo (como bancos de dados SQL). Use ordenação explícita:

```python theme={null}
# pandas preserva a ordem
df = pd.read_csv("data.csv")

# DataStore - use sort para ordem garantida
ds = pd.read_csv("data.csv")
ds = ds.sort('id')  # Ordenação explícita
```

***

<div id="patterns">
  ## Padrões de migração
</div>

<div id="pattern-1">
  ### Padrão 1: Leitura-Análise-Escrita
</div>

```python theme={null}
# 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 - o mesmo 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")
```

<div id="pattern-2">
  ### Padrão 2: DataFrame com operações do pandas
</div>

Se você precisar de recursos específicos do pandas, faça a conversão ao final:

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

# Operações rápidas com DataStore
ds = pd.read_csv("large_data.csv")
ds = ds.filter(ds['date'] >= '2024-01-01')
ds = ds.filter(ds['amount'] > 100)

# Converter para pandas para recursos específicos
df = ds.to_df()
df_pivoted = df.pivot_table(...)  # específico do pandas
```

<div id="pattern-3">
  ### Padrão 3: Fluxo de trabalho híbrido
</div>

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

# Comece com DataStore para filtragem rápida
ds = pd.read_csv("huge_file.csv")  # 10M linhas
ds = ds.filter(ds['year'] == 2024)  # Filtro SQL rápido
ds = ds.select('col1', 'col2', 'col3')  # Pruning de colunas

# Converta para operações específicas do pandas
df = ds.to_df()  # Agora apenas ~100K linhas
result = df.apply(complex_custom_function)  # pandas
```

***

<div id="performance">
  ## Comparação de desempenho
</div>

DataStore é significativamente mais rápido para grandes conjuntos de dados:

| Operação              | pandas  | DataStore | Ganho de desempenho |
| --------------------- | ------- | --------- | ------------------- |
| Contagem com GroupBy  | 347ms   | 17ms      | **19.93x**          |
| Pipeline complexo     | 2,047ms | 380ms     | **5.39x**           |
| Filter+Sort+Head      | 1,537ms | 350ms     | **4.40x**           |
| Agregação com GroupBy | 406ms   | 141ms     | **2.88x**           |

*Benchmark em 10M de linhas*

***

<div id="troubleshooting">
  ## Solução de problemas de migração
</div>

<div id="issue-op">
  ### Problema: a operação não funciona
</div>

Algumas operações do pandas podem não ser compatíveis. Verifique:

1. A operação está na [lista de compatibilidade](/pt-BR/products/chdb/datastore/pandas-compat)?
2. Tente converter primeiro para pandas: `ds.to_df().operation()`

<div id="issue-results">
  ### Problema: Resultados diferentes
</div>

Ative o logging de depuração para entender o que está acontecendo:

```python theme={null}
from chdb.datastore.config import config
config.enable_debug()

# Visualizar o SQL gerado
ds.filter(ds['x'] > 10).explain()
```

<div id="issue-slow">
  ### Problema: Desempenho lento
</div>

Verifique o padrão de execução:

```python theme={null}
# Ruim: Múltiplas execuções pequenas
for i in range(1000):
    result = ds.filter(ds['id'] == i).to_df()

# Bom: Execução única
result = ds.filter(ds['id'].isin(ids)).to_df()
```

<div id="issue-types">
  ### Problema: incompatibilidade de tipos
</div>

DataStore pode inferir os tipos de forma diferente:

```python theme={null}
# Verificar tipos
print(ds.dtypes)

# Forçar conversão
ds['col'] = ds['col'].astype('int64')
```

***

<div id="gradual">
  ## Estratégia de migração gradual
</div>

<div id="week-1">
  ### Semana 1: Teste a compatibilidade
</div>

```python theme={null}
# Mantenha ambas as importações
import pandas as pd
from chdb import datastore as ds

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

# Verifique se são iguais
assert pdf.equals(dsf.to_pandas())
```

<div id="week-2">
  ### Semana 2: Migre scripts simples
</div>

Comece com scripts que:

* Leem arquivos grandes
* Fazem filtragem e agregação
* Não usam funções `apply` personalizadas

<div id="week-3">
  ### Semana 3: Lide com casos complexos
</div>

Para scripts com funções personalizadas:

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

# Deixe o DataStore fazer o trabalho pesado
ds = pd.read_csv("data.csv")
ds = ds.filter(ds['year'] == 2024)  # SQL

# Converter para trabalho personalizado
df = ds.to_df()
result = df.apply(my_custom_function)
```

<div id="week-4">
  ### Semana 4: Migração completa
</div>

Atualize todos os scripts para usar a importação de DataStore.

***

<div id="faq">
  ## FAQ
</div>

<div id="faq-both">
  ### Posso usar tanto pandas quanto DataStore?
</div>

Sim! Você pode converter livremente entre eles:

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

# DataStore para pandas
df = ds_result.to_pandas()

# pandas para DataStore  
ds = ds.DataFrame(pd_result)
```

<div id="faq-tests">
  ### Meus testes continuarão passando?
</div>

A maioria dos testes deve passar. Para testes de comparação, converta para pandas:

```python theme={null}
def test_my_function():
    result = my_function()
    expected = pd.DataFrame(...)
    pd.testing.assert_frame_equal(result.to_pandas(), expected)
```

<div id="faq-jupyter">
  ### Posso usar o DataStore no Jupyter?
</div>

Sim! O DataStore funciona nos notebooks do Jupyter:

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

ds = pd.read_csv("data.csv")
ds.head()  # Exibe bem no Jupyter
```

<div id="faq-issues">
  ### Como faço para relatar problemas?
</div>

Se você encontrar problemas de compatibilidade, informe-os em:
[https://github.com/chdb-io/chdb/issues](https://github.com/chdb-io/chdb/issues)