Débogage de DataStore - ClickHouse Documentation

DataStore propose des outils complets de débogage pour comprendre et optimiser vos pipelines de données.

Vue d’ensemble des outils de débogage

Outil	Objectif	Quand l’utiliser
`explain()`	Voir le plan d’exécution	Comprendre quelle requête SQL sera exécutée
Profiler	Mesurer les performances	Repérer les opérations lentes
journalisation	Voir 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 plus de détails.

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

Voir le Guide de profilage pour plus de détails.

Journalisation

Consultez les logs 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 des 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 de débogage courants

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 liés au 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ébogage 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. Analysez les performances avant d’optimiser

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

4. Vérifiez les requêtes SQL lorsque les résultats sont incorrects

# 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
Plan d’exécution détaillé	`ds.explain(verbose=True)`	+ Métadonnées
Afficher le SQL	`ds.to_sql()`	Chaîne de requête SQL
Activer le débogage	`config.enable_debug()`	Logs détaillés
Activer le profilage	`config.enable_profiling()`	Données de temporisation
Rapport du profileur	`get_profiler().report()`	Résumé des performances
Réinitialiser le profileur	`get_profiler().reset()`	Effacement des données de temporisation

É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

​Vue d’ensemble des outils de débogage

​Matrice de décision rapide

​Configuration rapide

​Activer le débogage complet

​Méthode explain()

​Profilage

​Journalisation

​Scénarios de débogage courants

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

​2. Requête lente

​3. Comprendre le choix du moteur

​4. Débogage des problèmes liés au cache

​Bonnes pratiques

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

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

​3. Analysez les performances avant d’optimiser

​4. Vérifiez les requêtes SQL lorsque les résultats sont incorrects

​Résumé des outils de débogage

​Étapes suivantes