DataStore proporciona herramientas integrales de depuración para comprender y optimizar sus pipelines de datos.
Resumen de herramientas de depuración
| Herramienta | Propósito | Cuándo usarla |
|---|
explain() | Ver el plan de ejecución | Entender qué SQL se ejecutará |
| Profiler | Medir el rendimiento | Encontrar operaciones lentas |
| Logging | Ver detalles de la ejecución | Depurar comportamientos inesperados |
Matriz de decisión rápida
| Necesidad | Herramienta | Comando |
|---|
| Ver el plan de ejecución | explain() | ds.explain() |
| Medir el rendimiento | Profiler | config.enable_profiling() |
| Depurar consultas SQL | Logging | config.enable_debug() |
| Todo lo anterior | Combinado | Véase abajo |
Habilitar la depuración completa
from chdb import datastore as pd
from chdb.datastore.config import config
# Habilitar toda la depuración
config.enable_debug() # Registro detallado
config.enable_profiling() # Seguimiento de rendimiento
ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})
# Ver el plan de ejecución
result.explain()
# Obtener informe del Profiler
from chdb.datastore.config import get_profiler
profiler = get_profiler()
profiler.report()
Consulte el plan de ejecución antes de ejecutar una consulta.
ds = pd.read_csv("data.csv")
query = (ds
.filter(ds['amount'] > 1000)
.groupby('region')
.agg({'amount': ['sum', 'mean']})
)
# Ver plan
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
Mida el tiempo de ejecución de cada operación.
from chdb.datastore.config import config, get_profiler
# Habilitar perfilado
config.enable_profiling()
# Ejecutar operaciones
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()
)
# Ver informe
profiler = get_profiler()
profiler.report(min_duration_ms=0.1)
Informe de rendimiento
==================
Paso Duración Llamadas
---- -------- -----
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
Consulte los registros detallados de ejecución.
from chdb.datastore.config import config
# Habilitar el logging de depuración
config.enable_debug()
# Ejecutar operaciones - los logs mostrarán:
# - Consultas SQL generadas
# - Motor de ejecución utilizado
# - Aciertos/fallos de caché
# - Información de tiempos
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)
Escenarios comunes de depuración
1. La consulta no devuelve los resultados esperados
# Paso 1: Ver el plan de ejecución
query = ds.filter(ds['age'] > 25).groupby('city').sum()
query.explain(verbose=True)
# Paso 2: Habilitar el logging para ver el SQL
config.enable_debug()
# Paso 3: Ejecutar y revisar los logs
result = query.to_df()
2. La consulta se ejecuta lentamente
# Paso 1: Activa el perfilado
config.enable_profiling()
# Paso 2: Ejecuta tu consulta
result = process_data()
# Paso 3: Revisa el informe del perfilador
profiler = get_profiler()
profiler.report()
# Paso 4: Identifica las operaciones lentas y optimízalas
3. Comprender la selección del motor
# Habilitar el registro detallado
config.enable_debug()
# Ejecutar operaciones
result = ds.filter(ds['x'] > 10).apply(custom_func)
# Los logs mostrarán qué motor se usó para cada operación:
# DEBUG - filter: Using chdb engine
# DEBUG - apply: Using pandas engine (custom function)
4. Depuración de problemas de caché
# Habilitar debug para ver las operaciones de caché
config.enable_debug()
# Primera ejecución
result1 = ds.filter(ds['x'] > 10).to_df()
# LOG: Fallo de caché, ejecutando consulta
# Segunda ejecución (debería usar la caché)
result2 = ds.filter(ds['x'] > 10).to_df()
# LOG: Acierto de caché, devolviendo resultado en caché
# Si no se almacena en caché cuando se espera, verificar:
# - ¿Las operaciones son idénticas?
# - ¿Está la caché habilitada? config.cache_enabled
1. Depura en desarrollo, no en producción
# Desarrollo
config.enable_debug()
config.enable_profiling()
# Producción
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)
2. Utiliza explain() antes de ejecutar consultas grandes
# Construir consulta
query = ds.filter(...).groupby(...).agg(...)
# Verificar el plan primero
query.explain()
# Si el plan es correcto, ejecutar
result = query.to_df()
3. Perfila antes de optimizar
# No adivines qué es lento: mídelo
config.enable_profiling()
result = your_pipeline()
get_profiler().report()
4. Revisa el SQL si los resultados son incorrectos
# Ver el SQL generado
print(query.to_sql())
# Comparar con el SQL esperado
# Ejecutar el SQL directamente en ClickHouse para verificar
Resumen de herramientas de depuración
| Herramienta | Comando | Salida |
|---|
| Plan de ejecución | ds.explain() | Pasos de ejecución + SQL |
| Explicación detallada | ds.explain(verbose=True) | + Metadatos |
| Ver SQL | ds.to_sql() | Consulta SQL como texto |
| Activar depuración | config.enable_debug() | Logs detallados |
| Activar perfilado | config.enable_profiling() | Datos de temporización |
| Informe de Profiler | get_profiler().report() | Resumen de rendimiento |
| Restablecer Profiler | get_profiler().reset() | Borra los datos de temporización |
Última modificación el 10 de junio de 2026
