O DataStore oferece recursos completos de depuração para entender e otimizar seus pipelines de dados.
Visão geral das ferramentas de depuração
| Ferramenta | Finalidade | Quando usar |
|---|
explain() | Ver o plano de execução | Entender qual SQL será executado |
| Profiler | Medir o desempenho | Encontrar operações lentas |
| Logging | Ver detalhes da execução | Depurar comportamentos inesperados |
| Necessidade | Ferramenta | Comando |
|---|
| Ver o plano de execução | explain() | ds.explain() |
| Medir o desempenho | Profiler | config.enable_profiling() |
| Depurar consultas SQL | Logging | config.enable_debug() |
| Todos os itens acima | Combinado | Veja abaixo |
from chdb import datastore as pd
from chdb.datastore.config import config
# Habilitar todos os recursos de depuração
config.enable_debug() # Logging detalhado
config.enable_profiling() # Rastreamento de desempenho
ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})
# Visualizar o plano de execução
result.explain()
# Obter relatório do Profiler
from chdb.datastore.config import get_profiler
profiler = get_profiler()
profiler.report()
Consulte o plano de execução antes de executar uma consulta.
ds = pd.read_csv("data.csv")
query = (ds
.filter(ds['amount'] > 1000)
.groupby('region')
.agg({'amount': ['sum', 'mean']})
)
# Ver o plano de execução
query.explain()
Pipeline:
Source: file('data.csv', 'CSVWithNames')
Filter: amount > 1000
GroupBy: region
Aggregate: sum(amount), avg(amount)
Generated SQL:
SELECT region, SUM(amount) AS sum, AVG(amount) AS mean
FROM file('data.csv', 'CSVWithNames')
WHERE amount > 1000
GROUP BY region
Meça o tempo de execução de cada operação.
from chdb.datastore.config import config, get_profiler
# Habilitar profiling
config.enable_profiling()
# Executar operações
ds = pd.read_csv("large_data.csv")
result = (ds
.filter(ds['amount'] > 100)
.groupby('category')
.agg({'amount': 'sum'})
.sort('sum', ascending=False)
.head(10)
.to_df()
)
# Visualizar relatório
profiler = get_profiler()
profiler.report(min_duration_ms=0.1)
Relatório de Desempenho
==================
Passo Duration Chamadas
---- -------- -----
read_csv 1.234s 1
filter 0.002s 1
groupby 0.001s 1
agg 0.089s 1
sort 0.045s 1
head 0.001s 1
to_df (SQL execution) 0.567s 1
---- -------- -----
Total 1.939s 7
Visualize logs detalhados da execução.
from chdb.datastore.config import config
# Ativar logging de depuração
config.enable_debug()
# Executar operações - os logs exibirão:
# - Consultas SQL geradas
# - Execution engine utilizado
# - Acertos/erros de cache
# - Informações de temporização
DEBUG - DataStore: Creating from file 'data.csv'
DEBUG - Query: SELECT region, SUM(amount) FROM ... WHERE amount > 1000 GROUP BY region
DEBUG - Engine: Using chdb for aggregation
DEBUG - Execution time: 0.089s
DEBUG - Cache: Storing result (key: abc123)
Cenários comuns de depuração
1. Consulta não retorna os resultados esperados
# Etapa 1: Veja o plano de execução
query = ds.filter(ds['age'] > 25).groupby('city').sum()
query.explain(verbose=True)
# Etapa 2: Ative o logging para ver o SQL
config.enable_debug()
# Etapa 3: Execute e verifique os logs
result = query.to_df()
# Passo 1: Ativar o perfilamento
config.enable_profiling()
# Passo 2: Executar sua consulta
result = process_data()
# Passo 3: Verificar o relatório do Profiler
profiler = get_profiler()
profiler.report()
# Passo 4: Identificar operações lentas e otimizar
3. Entendendo a seleção de Engine
# Ativar logging detalhado
config.enable_debug()
# Executar operações
result = ds.filter(ds['x'] > 10).apply(custom_func)
# Os logs mostrarão qual engine foi usado para cada operação:
# DEBUG - filter: Usando engine chdb
# DEBUG - apply: Usando engine pandas (função personalizada)
4. Depuração de problemas no cache
# Ativar debug para ver operações de cache
config.enable_debug()
# Primeira execução
result1 = ds.filter(ds['x'] > 10).to_df()
# LOG: Cache miss, executando consulta
# Segunda execução (deve usar cache)
result2 = ds.filter(ds['x'] > 10).to_df()
# LOG: Cache hit, retornando resultado em cache
# Se o cache não estiver sendo usado quando esperado, verifique:
# - As operações são idênticas?
# - O cache está habilitado? config.cache_enabled
1. Depure no Development, não em produção
# Desenvolvimento
config.enable_debug()
config.enable_profiling()
# Produção
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)
2. Use explain() antes de executar consultas grandes
# Monte a consulta
query = ds.filter(...).groupby(...).agg(...)
# Verifique primeiro o plano
query.explain()
# Se o plano parecer adequado, execute
result = query.to_df()
3. Meça o desempenho antes de otimizar
# Não adivinhe o que está lento - meça
config.enable_profiling()
result = your_pipeline()
get_profiler().report()
4. Verifique o SQL quando os resultados estiverem incorretos
# Visualizar SQL gerado
print(query.to_sql())
# Comparar com o SQL esperado
# Executar SQL diretamente no ClickHouse para verificar
Resumo das ferramentas de depuração
| Ferramenta | Comando | Saída |
|---|
| Plano de execução | ds.explain() | Etapas de execução + SQL |
| Explicação detalhada | ds.explain(verbose=True) | + Metadados |
| Ver SQL | ds.to_sql() | String de consulta SQL |
| Habilitar depuração | config.enable_debug() | Logs detalhados |
| Habilitar perfilamento | config.enable_profiling() | Dados de tempo |
| Relatório do Profiler | get_profiler().report() | Resumo de desempenho |
| Limpar Profiler | get_profiler().reset() | Limpar dados de tempo |
Última modificação em 10 de junho de 2026
