Depuración de DataStore - ClickHouse Documentation

DataStore ofrece un conjunto completo de herramientas de depuración para comprender y optimizar sus canalizaciones 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	Detectar operaciones lentas
Logging	Ver detalles de ejecución	Diagnosticar 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	Ver más abajo

Configuración rápida

Activar toda la depuración

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

# Enable all debugging
config.enable_debug()        # Verbose logging
config.enable_profiling()    # Performance tracking

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

# View execution plan
result.explain()

# Get profiler report
from chdb.datastore.config import get_profiler
profiler = get_profiler()
profiler.report()

Método explain()

Consulta 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']})
)

# View 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 obtener más detalles.

Perfilado

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

Query

from chdb.datastore.config import config, get_profiler

# Enable profiling
config.enable_profiling()

# Run operations
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()
)

# View report
profiler = get_profiler()
profiler.report(min_duration_ms=0.1)

Response

Performance Report
==================
Step                          Duration    Calls
----                          --------    -----
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

Consulta registros detallados de ejecución.

from chdb.datastore.config import config

# Enable debug logging
config.enable_debug()

# Run operations - logs will show:
# - SQL queries generated
# - Execution engine used
# - Cache hits/misses
# - Timing information

Ejemplo de salida de logs:

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)

Consulte Configuración de logging para más detalles.

Escenarios comunes de solución de problemas

1. La consulta no devuelve los resultados esperados

# Step 1: View the execution plan
query = ds.filter(ds['age'] > 25).groupby('city').sum()
query.explain(verbose=True)

# Step 2: Enable logging to see SQL
config.enable_debug()

# Step 3: Run and check logs
result = query.to_df()

2. Consulta lenta

# Step 1: Enable profiling
config.enable_profiling()

# Step 2: Run your query
result = process_data()

# Step 3: Check profiler report
profiler = get_profiler()
profiler.report()

# Step 4: Identify slow operations and optimize

3. Comprender la selección del motor

# Enable verbose logging
config.enable_debug()

# Run operations
result = ds.filter(ds['x'] > 10).apply(custom_func)

# Logs will show which engine was used for each operation:
# DEBUG - filter: Using chdb engine
# DEBUG - apply: Using pandas engine (custom function)

4. Depuración de problemas de caché

# Enable debug to see cache operations
config.enable_debug()

# First run
result1 = ds.filter(ds['x'] > 10).to_df()
# LOG: Cache miss, executing query

# Second run (should use cache)
result2 = ds.filter(ds['x'] > 10).to_df()
# LOG: Cache hit, returning cached result

# If not caching when expected, check:
# - Are operations identical?
# - Is cache enabled? config.cache_enabled

Buenas prácticas

1. Depura en desarrollo, no en producción

# Development
config.enable_debug()
config.enable_profiling()

# Production
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)

2. Usa explain() antes de ejecutar consultas grandes

# Build query
query = ds.filter(...).groupby(...).agg(...)

# Check plan first
query.explain()

# If plan looks good, execute
result = query.to_df()

3. Mide el rendimiento antes de optimizar

# Don't guess what's slow - measure it
config.enable_profiling()
result = your_pipeline()
get_profiler().report()

4. Revisa el SQL si los resultados son incorrectos

# View generated SQL
print(query.to_sql())

# Compare with expected SQL
# Run SQL directly in ClickHouse to verify

Resumen de herramientas de depuración

Herramienta	Comando	Salida
Plan de ejecución	`ds.explain()`	Pasos de ejecución + SQL
Explain detallado	`ds.explain(verbose=True)`	+ metadatos
Ver SQL	`ds.to_sql()`	Cadena de consulta SQL
Habilitar depuración	`config.enable_debug()`	logs detallados
Habilitar perfilado	`config.enable_profiling()`	Datos de temporización
Informe del Profiler	`get_profiler().report()`	Resumen de rendimiento
Reiniciar Profiler	`get_profiler().reset()`	Borrar 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

​Resumen de herramientas de depuración

​Matriz de decisión rápida

​Configuración rápida

​Activar toda la depuración

​Método explain()

​Perfilado

​Logging

​Escenarios comunes de solución de problemas

​1. La consulta no devuelve los resultados esperados

​2. Consulta lenta

​3. Comprender la selección del motor

​4. Depuración de problemas de caché

​Buenas prácticas

​1. Depura en desarrollo, no en producción

​2. Usa explain() antes de ejecutar consultas grandes

​3. Mide el rendimiento antes de optimizar

​4. Revisa el SQL si los resultados son incorrectos

​Resumen de herramientas de depuración

​Próximos pasos

Resumen de herramientas de depuración

Matriz de decisión rápida

Configuración rápida

Activar toda la depuración

Método explain()

Perfilado

Logging

Escenarios comunes de solución de problemas

1. La consulta no devuelve los resultados esperados

2. Consulta lenta

3. Comprender la selección del motor

4. Depuración de problemas de caché

Buenas prácticas

1. Depura en desarrollo, no en producción

2. Usa explain() antes de ejecutar consultas grandes

3. Mide el rendimiento antes de optimizar

4. Revisa el SQL si los resultados son incorrectos

Resumen de herramientas de depuración

Próximos pasos