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

# DataStore: API compatível com pandas com otimização SQL

> DataStore oferece uma API compatível com pandas com otimização SQL para análise de dados de alto desempenho

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

DataStore é a API compatível com pandas do chDB que combina a interface familiar de DataFrame do pandas com o poder da otimização de consultas SQL, permitindo que você escreva código no estilo do pandas e obtenha o desempenho do ClickHouse.

<div id="key-features">
  ## Principais recursos
</div>

* **Compatibilidade com pandas**: 209 métodos de DataFrame do pandas, 56 métodos `.str`, 42+ métodos `.dt`
* **Otimização de SQL**: as operações são compiladas automaticamente para consultas SQL otimizadas
* **Lazy Evaluation**: as operações são adiadas até que os resultados sejam necessários
* **630+ métodos de API**: API abrangente para manipulação de dados
* **Extensões do ClickHouse**: acessores adicionais (`.arr`, `.json`, `.url`, `.ip`, `.geo`) não disponíveis no pandas

<div id="architecture">
  ## Arquitetura
</div>

<Image size="md" img="https://mintcdn.com/private-7c7dfe99/QiEdJri7g6Jn-guK/images/chdb/datastore_architecture.png?fit=max&auto=format&n=QiEdJri7g6Jn-guK&q=85&s=4c1aeaf14a157d6e02aa729d8825ef24" alt="Arquitetura do DataStore" width="2816" height="1536" data-path="images/chdb/datastore_architecture.png" />

O DataStore usa **avaliação preguiçosa** com **execução com dois engines**:

1. **Cadeia de Operações Lazy**: as operações são registradas, não executadas imediatamente
2. **Seleção Inteligente de Engine**: o QueryPlanner encaminha cada segmento para o engine ideal (chDB para SQL, Pandas para operações complexas)
3. **Cache Intermediário**: os resultados são armazenados em cache em cada passo para exploração iterativa rápida

Consulte [Modelo de Execução](/docs/pt-BR/chdb/datastore/execution-model) para mais detalhes.

<div id="migration">
  ## Migração do Pandas com uma linha
</div>

```python theme={null}
# Before (pandas)
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# After (DataStore) - just change the import!
from chdb import datastore as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()
```

Seu código existente em pandas continua funcionando sem alterações, mas agora é executado pelo mecanismo do ClickHouse.

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

O DataStore oferece ganhos significativos de desempenho em relação ao pandas, especialmente em agregações e pipelines complexos:

| 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 com 10M de linhas. Consulte o [script de benchmark](https://github.com/chdb-io/chdb/blob/main/refs/benchmark_datastore_vs_pandas.py) e o [Guia de desempenho](/docs/pt-BR/chdb/guides/pandas-performance) para mais detalhes.*

<div id="when-to-use">
  ## Quando usar o DataStore
</div>

**Use o DataStore quando:**

* Estiver trabalhando com grandes conjuntos de dados (milhões de linhas)
* Precisar realizar agregações e operações de GroupBy
* Precisar consultar dados de arquivos, bancos de dados ou armazenamento em nuvem
* Estiver criando pipelines de dados complexos
* Quiser a API do pandas com melhor desempenho

**Use a API de SQL direto quando:**

* Preferir escrever SQL diretamente
* Precisar de controle mais granular sobre a execução de consultas
* Estiver trabalhando com recursos específicos do ClickHouse não expostos na API do pandas

<div id="comparison">
  ## Comparação de funcionalidades
</div>

| Funcionalidade                   | Pandas | Polars   | DuckDB | DataStore        |
| -------------------------------- | ------ | -------- | ------ | ---------------- |
| Compatível com a API do Pandas   | -      | Parcial  | Não    | **Completa**     |
| Avaliação preguiçosa             | Não    | Sim      | Sim    | **Sim**          |
| Suporte a consultas SQL          | Não    | Sim      | Sim    | **Sim**          |
| Funções do ClickHouse            | Não    | Não      | Não    | **Sim**          |
| Acessores de String/DateTime     | Sim    | Sim      | Não    | **Sim + extras** |
| Array/JSON/URL/IP/Geo            | Não    | Parcial  | Não    | **Sim**          |
| Consultas diretas em arquivos    | Não    | Sim      | Sim    | **Sim**          |
| Suporte a armazenamento em nuvem | Não    | Limitado | Sim    | **Sim**          |

<div id="api-stats">
  ## Estatísticas da API
</div>

| Categoria                   | Contagem | Cobertura                           |
| --------------------------- | -------- | ----------------------------------- |
| Métodos de DataFrame        | 209      | 100% do pandas                      |
| Acessor Series.str          | 56       | 100% do pandas                      |
| Acessor Series.dt           | 42+      | 100%+ (inclui extras do ClickHouse) |
| Acessor Series.arr          | 37       | Específico do ClickHouse            |
| Acessor Series.json         | 13       | Específico do ClickHouse            |
| Acessor Series.url          | 15       | Específico do ClickHouse            |
| Acessor Series.ip           | 9        | Específico do ClickHouse            |
| Acessor Series.geo          | 14       | Específico do ClickHouse            |
| **Total de métodos da API** | **630+** | -                                   |

<div id="navigation">
  ## Navegação na documentação
</div>

<div id="getting-started">
  ### Primeiros passos
</div>

* [Início rápido](/docs/pt-BR/chdb/datastore/quickstart) - Instalação e uso básico
* [Migração a partir do Pandas](/docs/pt-BR/chdb/guides/migration-from-pandas) - Guia de migração passo a passo

<div id="api-reference">
  ### Referência da API
</div>

* [Métodos de fábrica](/docs/pt-BR/chdb/datastore/factory-methods) - Criação de DataStore a partir de várias fontes
* [Construção de consultas](/docs/pt-BR/chdb/datastore/query-building) - Operações de consulta em estilo SQL
* [Compatibilidade com pandas](/docs/pt-BR/chdb/datastore/pandas-compat) - Todos os 209 métodos compatíveis com pandas
* [Acessores](/docs/pt-BR/chdb/datastore/accessors) - Acessores de String, DateTime, Array, JSON, URL, IP e Geo
* [Agregação](/docs/pt-BR/chdb/datastore/aggregation) - Funções de agregação e de janela
* [Operações de E/S](/docs/pt-BR/chdb/datastore/io) - Leitura e gravação de dados

<div id="advanced-topics">
  ### Tópicos avançados
</div>

* [Modelo de Execução](/docs/pt-BR/chdb/datastore/execution-model) - Lazy evaluation e cache
* [Referência de classe](/docs/pt-BR/chdb/datastore/class-reference) - Referência completa da API

<div id="configuration-debugging">
  ### Configuração e depuração
</div>

* [Configuração](/docs/pt-BR/chdb/configuration/index) - Todas as opções de configuração
* [Modo de desempenho](/docs/pt-BR/chdb/configuration/performance-mode) - Modo SQL-first para máxima taxa de transferência
* [Depuração](/docs/pt-BR/chdb/debugging/index) - Explain, profiling e logging

<div id="pandas-user-guides">
  ### Guias do usuário do Pandas
</div>

* [Cookbook do Pandas](/docs/pt-BR/chdb/guides/pandas-cookbook) - Padrões comuns
* [Principais diferenças](/docs/pt-BR/chdb/guides/pandas-differences) - Diferenças importantes em relação ao pandas
* [Guia de desempenho](/docs/pt-BR/chdb/guides/pandas-performance) - Dicas de otimização
* [SQL para usuários do Pandas](/docs/pt-BR/chdb/guides/pandas-to-sql) - Entenda o SQL por trás das operações do pandas

<div id="quick-example">
  ## Exemplo rápido
</div>

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

# Read data from various sources
ds = pd.read_csv("sales.csv")
# or: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# or: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# Familiar pandas operations - automatically optimized to SQL
result = (ds
    .filter(ds['amount'] > 1000)           # WHERE amount > 1000
    .groupby('region')                      # GROUP BY region
    .agg({'amount': ['sum', 'mean']})       # SUM(amount), AVG(amount)
    .sort_values('sum', ascending=False)    # ORDER BY sum DESC
    .head(10)                               # LIMIT 10
)

# View the generated SQL
print(result.to_sql())

# Execute and get results
df = result.to_df()  # Returns pandas DataFrame
```

<div id="next-steps">
  ## Próximos passos
</div>

* **Novo no DataStore?** Comece com o [Guia de início rápido](/docs/pt-BR/chdb/datastore/quickstart)
* **Vem do pandas?** Leia o [Guia de migração](/docs/pt-BR/chdb/guides/migration-from-pandas)
* **Quer saber mais?** Explore a [Referência da API](/docs/pt-BR/chdb/datastore/class-reference)