Configuração do motor de execução

Configure o motor de execução do DataStore - auto, chdb ou pandas

O DataStore pode executar operações usando diferentes backends. Este guia explica como configurar e otimizar a seleção do motor de execução.

​

Motores disponíveis

Motor	Descrição	Ideal para
auto	Seleciona automaticamente o melhor motor para cada operação	Uso geral (padrão)
chdb	Força todas as operações a serem executadas via ClickHouse SQL	Grandes conjuntos de dados, agregações
pandas	Força todas as operações a serem executadas via pandas	Testes de compatibilidade, recursos específicos do pandas

​

Configurando o motor

​

Configuração global

from chdb.datastore.config import config

# Opção 1: Usando o método set
config.set_execution_engine('auto')    # Padrão
config.set_execution_engine('chdb')    # Forçar ClickHouse
config.set_execution_engine('pandas')  # Forçar pandas

# Opção 2: Usando atalhos
config.use_auto()     # Seleção automática
config.use_chdb()     # Forçar ClickHouse
config.use_pandas()   # Forçar pandas

​

Verificando o motor atual

print(config.execution_engine)  # 'auto', 'chdb' ou 'pandas'

---

​

Modo automático

No modo auto (padrão), o DataStore seleciona o motor mais adequado para cada operação:

​

Operações executadas no chDB

• Filtragem compatível com SQL (filter(), where())
• Seleção de colunas (select())
• Ordenação (sort(), orderby())
• Agrupamento e agregação (groupby().agg())
• Junções (join(), merge())
• Valores distintos (distinct(), drop_duplicates())
• Limitação de resultados (limit(), head(), tail())

​

Operações executadas no pandas

• Funções apply personalizadas (apply(custom_func))
• Tabelas dinâmicas complexas com agregações customizadas
• Operações que não podem ser expressas em SQL
• Quando a entrada já é um DataFrame do pandas

​

Exemplo

from chdb import datastore as pd
from chdb.datastore.config import config

config.use_auto()  # Padrão

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

# Isso usa chDB (SQL)
result = (ds
    .filter(ds['amount'] > 100)   # SQL: WHERE
    .groupby('region')            # SQL: GROUP BY
    .agg({'amount': 'sum'})       # SQL: SUM()
)

# Isso usa pandas (função personalizada)
result = ds.apply(lambda row: complex_calculation(row), axis=1)

---

​

Modo chDB

Force todas as operações por meio do ClickHouse SQL:

config.use_chdb()

​

Quando usar

• Processamento de grandes volumes de dados (milhões de linhas)
• Cargas de trabalho com muita agregação
• Quando você quer o máximo de otimização de SQL
• Comportamento consistente em todas as operações

​

Características de desempenho

Tipo de operação	Desempenho
GroupBy/Agregação	Excelente (até 20x mais rápido)
Filtragem complexa	Excelente
Ordenação	Muito bom
Filtros simples individuais	Bom (leve sobrecarga)

​

Limitações

• Funções personalizadas em Python podem não ser compatíveis
• Alguns recursos específicos do pandas exigem conversão

---

​

Modo pandas

Force todas as operações a passar pelo pandas:

config.use_pandas()

​

Quando usar

• Testes de compatibilidade com o pandas
• Uso de funcionalidades específicas do pandas
• Depuração de problemas relacionados ao pandas
• Quando os dados já estão no formato do pandas

​

Características de desempenho

Tipo de operação	Desempenho
Operações simples e isoladas	Bom
Funções personalizadas	Excelente
Agregações complexas	Mais lentas que o chDB
Grandes volumes de dados	Uso intensivo de memória

---

​

Motor entre DataStores

Configure o motor para operações que combinam colunas de diferentes DataStores:

# Definir engine cross-DataStore
config.set_cross_datastore_engine('auto')
config.set_cross_datastore_engine('chdb')
config.set_cross_datastore_engine('pandas')

​

Exemplo

ds1 = pd.read_csv("sales.csv")
ds2 = pd.read_csv("inventory.csv")

# Esta operação envolve dois DataStores
result = ds1.join(ds2, on='product_id')
# Usa a configuração cross_datastore_engine

---

​

Lógica de seleção do motor

​

Árvore de decisão do modo automático

Operação solicitada
    │
    ├─ Pode ser expressa em SQL?
    │      │
    │      ├─ Sim → Use chDB
    │      │
    │      └─ Não → Use pandas
    │
    └─ Operação Cross-DataStore?
           │
           └─ Use a configuração cross_datastore_engine

​

Override em nível de função

Algumas funções podem ter o motor configurado explicitamente:

from chdb.datastore.config import function_config

# Forçar funções específicas a usar um engine específico
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper', 'lower')

Consulte Configuração de função para mais detalhes.

---

​

Comparação de desempenho

Resultados do benchmark em 10 milhões de linhas:

Operação	pandas (ms)	chdb (ms)	Ganho de desempenho
Contagem com GroupBy	347	17	19.93x
Operações combinadas	1,535	234	6.56x
Pipeline complexo	2,047	380	5.39x
Filter+Sort+Head	1,537	350	4.40x
Agregação com GroupBy	406	141	2.88x
Filtro único	276	526	0.52x

Principais conclusões:

• o chDB se destaca em agregações e pipelines complexos
• o pandas é um pouco mais rápido em operações simples e isoladas
• use o modo auto para aproveitar o melhor dos dois

---

​

Boas práticas

​

1. Comece pelo modo automático

config.use_auto()  # Deixe o DataStore decidir

​

2. Faça profiling antes de forçar

config.enable_profiling()
# Execute sua carga de trabalho
# Verifique o relatório do Profiler para ver onde o tempo é gasto

​

3. Forçar o motor para cargas de trabalho específicas

# Para workloads com agregação pesada
config.use_chdb()

# Para testes de compatibilidade com pandas
config.use_pandas()

​

4. Use explain() para entender a execução

ds = pd.read_csv("data.csv")
query = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'sum'})

# Veja qual SQL será gerado
query.explain()

---

​

Solução de problemas

​

Problema: Operação mais lenta que o esperado

# Verificar o engine atual
print(config.execution_engine)

# Ativar debug para ver o que está acontecendo
config.enable_debug()

# Tentar forçar um engine específico
config.use_chdb()  # or config.use_pandas()

​

Problema: operação não suportada no modo chdb

# Algumas operações do pandas não são suportadas em SQL
# Solução: use o modo automático
config.use_auto()

# Ou converta explicitamente para pandas primeiro
df = ds.to_df()
result = df.some_pandas_specific_operation()

​

Problema: uso excessivo de memória com grandes volumes de dados

# Use o engine chdb para evitar carregar todos os dados na memória
config.use_chdb()

# Filtre antecipadamente para reduzir o tamanho dos dados
result = ds.filter(ds['date'] >= '2024-01-01').to_df()

# Para maior throughput em grandes datasets, use o modo de desempenho
# que habilita leitura paralela de Parquet e agregação em SQL único
config.use_performance_mode()

Modo de desempenho

Se você estiver executando cargas de trabalho pesadas de agregação e não precisar de compatibilidade exata com a saída do pandas (ordem das linhas, MultiIndex, correções de dtype), considere usar o Modo de desempenho. Ele define automaticamente o motor como chdb e remove toda a sobrecarga de compatibilidade com o pandas.