DataStore: API compatível com o Pandas com otimização de SQL

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

DataStore é a API compatível com o Pandas do chDB que combina a conhecida interface de DataFrame do pandas com o poder da otimização de consultas SQL e permite escrever código no estilo do pandas com o desempenho do ClickHouse.

​

Principais recursos

• 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 convertidas automaticamente em consultas SQL otimizadas
• Avaliação preguiçosa: 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

​

Arquitetura

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

1. Encadeamento preguiçoso de operações: as operações são registradas, não executadas imediatamente
2. Seleção inteligente de engine: o QueryPlanner direciona 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 a cada etapa para uma exploração iterativa mais rápida

Consulte o Modelo de Execução para mais detalhes.

​

Migração com uma única linha a partir do Pandas

# Antes (pandas)
import pandas as pd
df = pd.read_csv("data.csv")
result = df[df['age'] > 25].groupby('city')['salary'].mean()

# Depois (DataStore) - basta mudar o 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 pandas existente funciona sem alterações, mas agora roda no mecanismo do ClickHouse.

​

Comparação de desempenho

O DataStore oferece ganhos significativos de desempenho em comparação com o pandas, especialmente em agregação e pipelines complexos:

Operação	Pandas	DataStore	Ganho de velocidade
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 linhas. Veja o script de benchmark e o Guia de desempenho para mais detalhes.

​

Quando usar DataStore

Use o DataStore quando:

• Estiver trabalhando com grandes conjuntos de dados (milhões de linhas)
• Estiver realizando agregações e operações de groupby
• Estiver consultando 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 puro quando:

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

​

Comparação de funcionalidades

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

​

Estatísticas da API

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

​

Navegação na documentação

​

Primeiros passos

• guia de início rápido - Instalação e uso básico
• Migração do Pandas - Guia de migração passo a passo

​

Referência da API

• Métodos de fábrica - Criação do DataStore a partir de várias fontes
• Construção de consultas - Operações de consulta em estilo SQL
• Compatibilidade com pandas - Todos os 209 métodos compatíveis com pandas
• Acessores - Acessores String, DateTime, Array, JSON, URL, IP e Geo
• Agregação - Funções de agregação e de janela
• Operações de E/S - Leitura e gravação de dados

​

Tópicos avançados

• Modelo de Execução - Avaliação preguiçosa e cache
• Referência da classe - Referência completa da API

​

Configuração e depuração

• Configuração - Todas as opções de configuração
• Modo de desempenho - Modo SQL-first para máxima taxa de transferência
• Depuração - Explain, profiling e logging

​

Guias para usuários do Pandas

• Cookbook do Pandas - Padrões comuns
• Principais diferenças - Diferenças importantes em relação ao pandas
• Guia de desempenho - Dicas de otimização
• SQL para usuários do Pandas - Entenda o SQL por trás das operações do pandas

​

Exemplo rápido

from chdb import datastore as pd

# Leia dados de várias fontes
ds = pd.read_csv("sales.csv")
# ou: ds = pd.DataStore.uri("s3://bucket/sales.parquet")
# ou: ds = pd.DataStore.from_mysql("mysql://user:pass@host/db/table")

# Operações familiares do pandas - automaticamente otimizadas para 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
)

# Visualize o SQL gerado
print(result.to_sql())

# Execute e obtenha os resultados
df = result.to_df()  # Retorna um pandas DataFrame

​

Próximos passos

• Está começando a usar o DataStore? Comece com o Guia de início rápido
• Usa pandas? Leia o Guia de migração
• Quer saber mais? Explore a Referência da API