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

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.

• 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

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 para mais detalhes.

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

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

Benchmark com 10M de linhas. Consulte o script de benchmark e o Guia de desempenho para mais detalhes.

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

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

• Métodos de fábrica - Criação de 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 de 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

• Modelo de Execução - Lazy evaluation e cache
• Referência de classe - Referência completa da API

• 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

• 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

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

• Novo no DataStore? Comece com o Guia de início rápido
• Vem do pandas? Leia o Guia de migração
• Quer saber mais? Explore a Referência da API