Depuración de DataStore

Depura las operaciones de DataStore con explain(), profiling y logging

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

​

Configuración rápida

​

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()

---

​

Método explain()

Consulte el plan de ejecución antes de ejecutar una consulta.

Query

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

query = (ds
    .filter(ds['amount'] > 1000)
    .groupby('region')
    .agg({'amount': ['sum', 'mean']})
)

# Ver plan
query.explain()

Response

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

Consulte la documentación de explain() para más información.

---

​

Perfilado

Mida el tiempo de ejecución de cada operación.

Query

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)

Response

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

Consulta la Guía de perfilado para más detalles.

---

​

Logging

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

Ejemplo de salida del log:

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)

Consulta Configuración del logging para más detalles.

---

​

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

---

​

Buenas prácticas

​

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

---

​

Próximos pasos

• Método explain() - Documentación detallada del plan de ejecución
• Guía de perfilado - Medición del rendimiento
• Configuración de logging - Configuración del nivel de log y del formato