> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Compatibilidade do DataStore com pandas

> Lista completa de métodos compatíveis com pandas no DataStore (209 métodos de DataFrame do pandas)

O DataStore implementa **209 métodos de DataFrame do pandas** para total compatibilidade com a API. Seu código pandas existente funciona com alterações mínimas.

<div id="approach">
  ## Estratégia de compatibilidade
</div>

```python theme={null}
# Typical migration - just change the import
- import pandas as pd
+ from chdb import datastore as pd

# Your code works unchanged
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()
```

**Princípios-chave:**

* Todos os 209 métodos do DataFrame do pandas implementados
* Avaliação preguiçosa para otimização de SQL
* Encapsulamento automático de tipos (DataFrame → DataStore, Series → ColumnExpr)
* Operações imutáveis (sem `inplace=True`)

***

<div id="attributes">
  ## Atributos e Propriedades
</div>

| Propriedade | Descrição                  | Aciona a execução |
| ----------- | -------------------------- | ----------------- |
| `shape`     | tupla (linhas, colunas)    | Sim               |
| `columns`   | Nomes das colunas (Index)  | Sim               |
| `dtypes`    | Tipos de dados das colunas | Sim               |
| `values`    | array do NumPy             | Sim               |
| `index`     | Índice das linhas          | Sim               |
| `size`      | Número de elementos        | Sim               |
| `ndim`      | Número de dimensões        | Não               |
| `empty`     | Se o DataFrame está vazio  | Sim               |
| `T`         | Transposição               | Sim               |
| `axes`      | Lista de eixos             | Sim               |

**Exemplos:**

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

ds = pd.read_csv("data.csv")

print(ds.shape)      # (1000, 5)
print(ds.columns)    # Index(['name', 'age', 'city', 'salary', 'dept'])
print(ds.dtypes)     # name: object, age: int64, ...
print(ds.empty)      # False
```

***

<div id="indexing">
  ## Indexação e seleção
</div>

| Método                 | Descrição                    | Exemplo                              |
| ---------------------- | ---------------------------- | ------------------------------------ |
| `df['col']`            | Selecionar coluna            | `ds['age']`                          |
| `df[['col1', 'col2']]` | Selecionar colunas           | `ds[['name', 'age']]`                |
| `df[condition]`        | Indexação booleana           | `ds[ds['age'] > 25]`                 |
| `df.loc[...]`          | Acesso por rótulos           | `ds.loc[0:10, 'name']`               |
| `df.iloc[...]`         | Acesso por inteiros          | `ds.iloc[0:10, 0:3]`                 |
| `df.at[...]`           | Valor único por rótulo       | `ds.at[0, 'name']`                   |
| `df.iat[...]`          | Valor único por posição      | `ds.iat[0, 0]`                       |
| `df.head(n)`           | Primeiras n linhas           | `ds.head(10)`                        |
| `df.tail(n)`           | Últimas n linhas             | `ds.tail(10)`                        |
| `df.sample(n)`         | Amostra aleatória            | `ds.sample(100)`                     |
| `df.select_dtypes()`   | Selecionar por Dtype         | `ds.select_dtypes(include='number')` |
| `df.query()`           | Expressão de consulta        | `ds.query('age > 25')`               |
| `df.where()`           | Substituição condicional     | `ds.where(ds['age'] > 0, 0)`         |
| `df.mask()`            | `where` inverso              | `ds.mask(ds['age'] < 0, 0)`          |
| `df.isin()`            | Verificação de pertencimento | `ds['city'].isin(['NYC', 'LA'])`     |
| `df.get()`             | Acesso seguro à coluna       | `ds.get('col', default=None)`        |
| `df.xs()`              | Seção transversal            | `ds.xs('key')`                       |
| `df.pop()`             | Remover coluna               | `ds.pop('col')`                      |

***

<div id="statistical">
  ## Métodos Estatísticos
</div>

| Método           | Descrição                    | Equivalente em SQL |
| ---------------- | ---------------------------- | ------------------ |
| `mean()`         | Média                        | `AVG()`            |
| `median()`       | Mediana                      | `MEDIAN()`         |
| `mode()`         | Moda                         | -                  |
| `std()`          | Desvio padrão                | `STDDEV()`         |
| `var()`          | Variância                    | `VAR()`            |
| `min()`          | Valor mínimo                 | `MIN()`            |
| `max()`          | Máximo                       | `MAX()`            |
| `sum()`          | Soma                         | `SUM()`            |
| `prod()`         | Produto                      | -                  |
| `count()`        | Contagem de valores não NULL | `COUNT()`          |
| `nunique()`      | Contagem de valores únicos   | `UNIQ()`           |
| `value_counts()` | Frequência de valores        | `GROUP BY`         |
| `quantile()`     | Quantil                      | `QUANTILE()`       |
| `describe()`     | Estatísticas resumidas       | -                  |
| `corr()`         | Matriz de correlação         | `CORR()`           |
| `cov()`          | Matriz de covariância        | `COV()`            |
| `corrwith()`     | Correlação por pares         | -                  |
| `rank()`         | Classificação dos valores    | `RANK()`           |
| `abs()`          | Valores absolutos            | `ABS()`            |
| `round()`        | Arredondamento de valores    | `ROUND()`          |
| `clip()`         | Limitação de valores         | -                  |
| `cumsum()`       | Soma acumulada               | função de janela   |
| `cumprod()`      | Produto acumulado            | função de janela   |
| `cummin()`       | Mínimo acumulado             | função de janela   |
| `cummax()`       | Máximo acumulado             | função de janela   |
| `diff()`         | Diferença                    | função de janela   |
| `pct_change()`   | Variação percentual          | função de janela   |
| `skew()`         | Assimetria                   | `SKEW()`           |
| `kurt()`         | Curtose                      | `KURT()`           |
| `sem()`          | Erro padrão                  | -                  |
| `all()`          | Todos true                   | -                  |
| `any()`          | Algum true                   | -                  |
| `idxmin()`       | Índice do mínimo             | -                  |
| `idxmax()`       | Índice do máximo             | -                  |

**Exemplos:**

```python theme={null}
ds = pd.read_csv("data.csv")

# Basic statistics
print(ds['salary'].mean())
print(ds['age'].std())
print(ds.describe())

# Group statistics
print(ds.groupby('department')['salary'].mean())
print(ds.groupby('city').agg({'salary': ['mean', 'std'], 'age': 'count'}))
```

***

<div id="manipulation">
  ## Manipulação de dados
</div>

| Método              | Descrição                  |
| ------------------- | -------------------------- |
| `drop()`            | Remover linhas/colunas     |
| `drop_duplicates()` | Remover duplicatas         |
| `duplicated()`      | Marcar duplicatas          |
| `dropna()`          | Remover valores ausentes   |
| `fillna()`          | Preencher valores ausentes |
| `ffill()`           | Preenchimento para frente  |
| `bfill()`           | Preenchimento para trás    |
| `interpolate()`     | Interpolar valores         |
| `replace()`         | Substituir valores         |
| `rename()`          | Renomear colunas/índice    |
| `rename_axis()`     | Renomear eixo              |
| `assign()`          | Adicionar novas colunas    |
| `astype()`          | Converter tipos            |
| `convert_dtypes()`  | Inferir tipos              |
| `copy()`            | Copiar DataFrame           |

**Exemplos:**

```python theme={null}
ds = pd.read_csv("data.csv")

# Drop operations
result = ds.drop(columns=['unused_col'])
result = ds.drop_duplicates(subset=['user_id'])
result = ds.dropna(subset=['email'])

# Fill operations
result = ds.fillna(0)
result = ds.fillna({'age': 0, 'name': 'Unknown'})

# Transform operations
result = ds.rename(columns={'old_name': 'new_name'})
result = ds.assign(
    full_name=lambda x: x['first_name'] + ' ' + x['last_name'],
    age_group=lambda x: pd.cut(x['age'], bins=[0, 25, 50, 100])
)
```

***

<div id="sorting">
  ## Ordenação e ranking
</div>

| Método          | Descrição           |
| --------------- | ------------------- |
| `sort_values()` | Ordenar por valores |
| `sort_index()`  | Ordenar por índice  |
| `nlargest()`    | N maiores valores   |
| `nsmallest()`   | N menores valores   |

**Exemplos:**

```python theme={null}
# Sort by single column
result = ds.sort_values('salary', ascending=False)

# Sort by multiple columns
result = ds.sort_values(['department', 'salary'], ascending=[True, False])

# Get top/bottom N
result = ds.nlargest(10, 'salary')
result = ds.nsmallest(5, 'age')
```

***

<div id="reshaping">
  ## Reorganização
</div>

| Método              | Descrição                     |
| ------------------- | ----------------------------- |
| `pivot()`           | Tabela dinâmica               |
| `pivot_table()`     | Pivot com agregação           |
| `melt()`            | Despivotar                    |
| `stack()`           | Empilhar colunas no índice    |
| `unstack()`         | Desempilhar índice em colunas |
| `transpose()` / `T` | Transpor                      |
| `explode()`         | Explodir listas em linhas     |
| `squeeze()`         | Reduzir dimensões             |
| `droplevel()`       | Remover nível do índice       |
| `swaplevel()`       | Trocar níveis do índice       |
| `reorder_levels()`  | Reordenar níveis              |

**Exemplos:**

```python theme={null}
# Pivot table
result = ds.pivot_table(
    values='amount',
    index='region',
    columns='product',
    aggfunc='sum'
)

# Melt (unpivot)
result = ds.melt(
    id_vars=['name'],
    value_vars=['score1', 'score2', 'score3'],
    var_name='test',
    value_name='score'
)

# Explode arrays
result = ds.explode('tags')
```

***

<div id="combining">
  ## Combinação / Junção
</div>

| Método            | Descrição               |
| ----------------- | ----------------------- |
| `merge()`         | Mesclagem no estilo SQL |
| `join()`          | Junção por índice       |
| `concat()`        | Concatenar              |
| `append()`        | Acrescentar linhas      |
| `combine()`       | Combinar com função     |
| `combine_first()` | Combinar com prioridade |
| `update()`        | Atualizar valores       |
| `compare()`       | Mostrar diferenças      |

**Exemplos:**

```python theme={null}
# Merge (join)
result = pd.merge(df1, df2, on='id', how='left')
result = df1.join(df2, on='id')

# Concatenate
result = pd.concat([df1, df2, df3])
result = pd.concat([df1, df2], axis=1)
```

***

<div id="binary">
  ## Operações binárias
</div>

| Método                       | Descrição                 |
| ---------------------------- | ------------------------- |
| `add()` / `radd()`           | Adição                    |
| `sub()` / `rsub()`           | Subtração                 |
| `mul()` / `rmul()`           | Multiplicação             |
| `div()` / `rdiv()`           | Divisão                   |
| `truediv()` / `rtruediv()`   | Divisão real              |
| `floordiv()` / `rfloordiv()` | Divisão inteira           |
| `mod()` / `rmod()`           | Módulo                    |
| `pow()` / `rpow()`           | Potência                  |
| `dot()`                      | Multiplicação de matrizes |

**Exemplos:**

```python theme={null}
# Arithmetic operations
result = ds['col1'].add(ds['col2'])
result = ds['price'].mul(ds['quantity'])

# With fill_value for missing data
result = ds['col1'].add(ds['col2'], fill_value=0)
```

***

<div id="comparison">
  ## Operações de comparação
</div>

| Método      | Descrição          |
| ----------- | ------------------ |
| `eq()`      | Igual a            |
| `ne()`      | Diferente de       |
| `lt()`      | Menor que          |
| `le()`      | Menor ou igual a   |
| `gt()`      | Maior que          |
| `ge()`      | Maior ou igual a   |
| `equals()`  | Verifica igualdade |
| `compare()` | Mostra diferenças  |

***

<div id="application">
  ## Aplicação de funções
</div>

| Método                  | Descrição                   |
| ----------------------- | --------------------------- |
| `apply()`               | Aplicar função              |
| `applymap()`            | Aplicar elemento a elemento |
| `map()`                 | Mapear valores              |
| `agg()` / `aggregate()` | Agregar                     |
| `transform()`           | Transformar                 |
| `pipe()`                | Encadear funções            |
| `groupby()`             | Agrupar por                 |

**Exemplos:**

```python theme={null}
# Apply function
result = ds['name'].apply(lambda x: x.upper())
result = ds.apply(lambda row: row['a'] + row['b'], axis=1)

# Aggregate
result = ds.agg({'col1': 'sum', 'col2': 'mean'})
result = ds.agg(['sum', 'mean', 'std'])

# Pipe
result = (ds
    .pipe(filter_active)
    .pipe(calculate_metrics)
    .pipe(format_output)
)
```

***

<div id="timeseries">
  ## Séries temporais
</div>

| Método               | Descrição                        |
| -------------------- | -------------------------------- |
| `rolling()`          | Janela deslizante                |
| `expanding()`        | Janela expansiva                 |
| `ewm()`              | Ponderação exponencial           |
| `resample()`         | Reamostrar séries temporais      |
| `shift()`            | Deslocar valores                 |
| `asfreq()`           | Converter frequência             |
| `asof()`             | Valor mais recente até o momento |
| `at_time()`          | Selecionar por horário           |
| `between_time()`     | Selecionar intervalo de tempo    |
| `first()` / `last()` | Primeiros/últimos períodos       |
| `to_period()`        | Converter para período           |
| `to_timestamp()`     | Converter para timestamp         |
| `tz_convert()`       | Converter fuso horário           |
| `tz_localize()`      | Definir fuso horário local       |

**Exemplos:**

```python theme={null}
# Rolling window
result = ds['value'].rolling(window=7).mean()

# Expanding window
result = ds['value'].expanding().sum()

# Shift
result = ds['value'].shift(1)  # Lag
result = ds['value'].shift(-1)  # Lead
```

***

<div id="missing">
  ## Dados ausentes
</div>

| Método                  | Descrição                  |
| ----------------------- | -------------------------- |
| `isna()` / `isnull()`   | Detectar valores ausentes  |
| `notna()` / `notnull()` | Detectar valores presentes |
| `dropna()`              | Remover valores ausentes   |
| `fillna()`              | Preencher valores ausentes |
| `ffill()`               | Preenchimento para frente  |
| `bfill()`               | Preenchimento para trás    |
| `interpolate()`         | Interpolar                 |
| `replace()`             | Substituir valores         |

***

<div id="io">
  ## Métodos de E/S
</div>

| Método           | Descrição                           |
| ---------------- | ----------------------------------- |
| `to_csv()`       | Exportar para CSV                   |
| `to_json()`      | Exportar para JSON                  |
| `to_excel()`     | Exportar para Excel                 |
| `to_parquet()`   | Exportar para Parquet               |
| `to_feather()`   | Exportar para Feather               |
| `to_sql()`       | Exportar para um banco de dados SQL |
| `to_pickle()`    | Pickle                              |
| `to_html()`      | Tabela HTML                         |
| `to_latex()`     | Tabela LaTeX                        |
| `to_markdown()`  | Tabela Markdown                     |
| `to_string()`    | Representação textual               |
| `to_dict()`      | Dicionário                          |
| `to_records()`   | Registros                           |
| `to_numpy()`     | Array do NumPy                      |
| `to_clipboard()` | Área de transferência               |

Consulte [Operações de E/S](/docs/pt-BR/chdb/datastore/io) para ver a documentação detalhada.

***

<div id="iteration">
  ## Iteração
</div>

| Método         | Descrição                    |
| -------------- | ---------------------------- |
| `items()`      | Itera sobre (coluna, Series) |
| `iterrows()`   | Itera sobre (índice, Series) |
| `itertuples()` | Itera como tuplas nomeadas   |

***

<div id="differences">
  ## Principais diferenças em relação ao Pandas
</div>

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

```python theme={null}
# Pandas returns Series
pdf['col']  # → pd.Series

# DataStore returns ColumnExpr (lazy)
ds['col']   # → ColumnExpr
```

<div id="lazy-execution">
  ### 2. Execução preguiçosa
</div>

```python theme={null}
# DataStore operations are lazy
result = ds.filter(ds['age'] > 25)  # Not executed yet
df = result.to_df()  # Executed here
```

<div id="no-inplace-parameter">
  ### 3. Não há parâmetro inplace
</div>

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

# DataStore (always returns new object)
ds = ds.drop(columns=['col'])
```

<div id="comparing-results">
  ### 4. Comparando resultados
</div>

```python theme={null}
# Use to_pandas() for comparison
pd.testing.assert_frame_equal(
    ds.to_pandas(),
    expected_df
)
```

Consulte [Principais diferenças](/docs/pt-BR/chdb/guides/pandas-differences) para obter todos os detalhes.