Débogage de DataStore

Déboguer les opérations DataStore avec explain(), le profilage et la journalisation

DataStore offre une gamme complète d’outils de débogage pour comprendre et optimiser vos pipelines de données.

​

Aperçu des outils de débogage

Outil	Objectif	Quand l’utiliser
explain()	Afficher le plan d’exécution	Comprendre quelles instructions SQL seront exécutées
Profiler	Mesurer les performances	Identifier les opérations lentes
journalisation	Afficher les détails d’exécution	Déboguer un comportement inattendu

​

Matrice de décision rapide

Besoin	Outil	Commande
Voir le plan d’exécution	explain()	ds.explain()
Mesurer les performances	Profiler	config.enable_profiling()
Déboguer les requêtes SQL	journalisation	config.enable_debug()
Tout ce qui précède	Combinaison	Voir ci-dessous

​

Configuration rapide

​

Activer le débogage complet

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éthode explain()

Consultez le plan d’exécution avant d’exécuter une requête.

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

Consultez la documentation sur explain() pour en savoir plus.

---

​

Profilage

Mesurez le temps d’exécution de chaque opération.

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

Consultez le Guide de profilage pour en savoir plus.

---

​

Journalisation

Consultez les journaux d’exécution détaillés.

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

Exemple de sortie 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)

Consultez Configuration de la journalisation pour plus de détails.

---

​

Scénarios courants de débogage

​

1. La requête ne renvoie pas les résultats attendus

# 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. Requête lente

# 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. Comprendre le choix du moteur

# 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. Débogage des problèmes de cache

# 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

---

​

Bonnes pratiques

​

1. Déboguez en environnement de développement, pas en production

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

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

​

2. Utilisez explain() avant d’exécuter des requêtes volumineuses

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

# Check plan first
query.explain()

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

​

3. Mesurez avant d’optimiser

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

​

4. Vérifiez la requête SQL lorsque les résultats sont erronés

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

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

---

​

Résumé des outils de débogage

Outil	Commande	Sortie
Plan d’exécution	ds.explain()	Étapes d’exécution + SQL
Explain détaillé	ds.explain(verbose=True)	+ Métadonnées
Afficher la requête SQL	ds.to_sql()	Texte de la requête SQL
Activer le débogage	config.enable_debug()	Logs détaillés
Activer le profilage	config.enable_profiling()	Mesures de temps
Rapport du Profiler	get_profiler().report()	Résumé des performances
Réinitialiser le Profiler	get_profiler().reset()	Réinitialiser les mesures de temps

---

​

Étapes suivantes

• Méthode explain() - Documentation détaillée du plan d’exécution
• Guide de profilage - Mesure des performances
• Configuration de la journalisation - Configuration du niveau de journalisation et du format