> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<div id="overview">
  ## Resumen de herramientas de depuración
</div>

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

<div id="decision-matrix">
  ## Matriz de decisión rápida
</div>

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

<div id="quick-setup">
  ## Configuración rápida
</div>

<div id="enable-all">
  ### Habilitar la depuración completa
</div>

```python theme={null}
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()
```

***

<div id="explain">
  ## Método explain()
</div>

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

```python title="Query" theme={null}
ds = pd.read_csv("data.csv")

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

# Ver plan
query.explain()
```

```text title="Response" theme={null}
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()](/es/products/chdb/debugging/explain) para más información.

***

<div id="profiling">
  ## Perfilado
</div>

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

```python title="Query" theme={null}
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)
```

```text title="Response" theme={null}
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](/es/products/chdb/debugging/profiling) para más detalles.

***

<div id="logging">
  ## Logging
</div>

Consulte los registros detallados de ejecución.

```python theme={null}
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:

```text theme={null}
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](/es/products/chdb/debugging/logging) para más detalles.

***

<div id="scenarios">
  ## Escenarios comunes de depuración
</div>

<div id="scenario-wrong-results">
  ### 1. La consulta no devuelve los resultados esperados
</div>

```python theme={null}
# 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()
```

<div id="scenario-slow">
  ### 2. La consulta se ejecuta lentamente
</div>

```python theme={null}
# 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
```

<div id="scenario-engine">
  ### 3. Comprender la selección del motor
</div>

```python theme={null}
# 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)
```

<div id="scenario-cache">
  ### 4. Depuración de problemas de caché
</div>

```python theme={null}
# 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
```

***

<div id="best-practices">
  ## Buenas prácticas
</div>

<div id="best-practice-1">
  ### 1. Depura en desarrollo, no en producción
</div>

```python theme={null}
# Desarrollo
config.enable_debug()
config.enable_profiling()

# Producción
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)
```

<div id="best-practice-2">
  ### 2. Utiliza explain() antes de ejecutar consultas grandes
</div>

```python theme={null}
# Construir consulta
query = ds.filter(...).groupby(...).agg(...)

# Verificar el plan primero
query.explain()

# Si el plan es correcto, ejecutar
result = query.to_df()
```

<div id="best-practice-3">
  ### 3. Perfila antes de optimizar
</div>

```python theme={null}
# No adivines qué es lento: mídelo
config.enable_profiling()
result = your_pipeline()
get_profiler().report()
```

<div id="best-practice-4">
  ### 4. Revisa el SQL si los resultados son incorrectos
</div>

```python theme={null}
# Ver el SQL generado
print(query.to_sql())

# Comparar con el SQL esperado
# Ejecutar el SQL directamente en ClickHouse para verificar
```

***

<div id="overview">
  ## Resumen de herramientas de depuración
</div>

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

***

<div id="next-steps">
  ## Próximos pasos
</div>

* [Método explain()](/es/products/chdb/debugging/explain) - Documentación detallada del plan de ejecución
* [Guía de perfilado](/es/products/chdb/debugging/profiling) - Medición del rendimiento
* [Configuración de logging](/es/products/chdb/debugging/logging) - Configuración del nivel de log y del formato