Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Débogage de DataStore

View as MarkdownEdit this pageReport an issueSet up docs MCP

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.

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

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

# View plan
query.explain()
Responsetext
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.

Querypython
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)
Responsetext
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

Navigation