تصحيح أخطاء DataStore

استكشف أخطاء عمليات DataStore وأصلحها باستخدام explain() وتحليل الأداء والتسجيل

يوفّر DataStore أدوات شاملة لتصحيح الأخطاء لمساعدتك على فهم مسارات معالجة البيانات وتحسينها.

​

نظرة عامة على أدوات تصحيح الأخطاء

الأداة	الغرض	متى تُستخدم
explain()	عرض خطة التنفيذ	لفهم استعلام SQL الذي سيُنفَّذ
محلّل الأداء	قياس الأداء	لتحديد العمليات البطيئة
التسجيل	عرض تفاصيل التنفيذ	لتشخيص السلوك غير المتوقع

​

مصفوفة اتخاذ القرار السريعة

الحاجة	الأداة	الأمر
عرض خطة التنفيذ	explain()	ds.explain()
قياس الأداء	محلّل الأداء	config.enable_profiling()
تصحيح أخطاء استعلامات SQL	التسجيل	config.enable_debug()
كل ما سبق	مجتمعة	انظر أدناه

​

الإعداد السريع

​

تمكين جميع خيارات تصحيح الأخطاء

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

---

​

الدالة explain()

اطّلع على خطة التنفيذ قبل تشغيل الاستعلام.

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

راجع توثيق explain() لمزيد من التفاصيل.

---

​

تحليل الأداء

قِس زمن تنفيذ كل عملية.

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

راجع دليل تحليل الأداء لمزيد من التفاصيل.

---

​

التسجيل

اطّلع على سجلات التنفيذ التفصيلية.

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

مثال على مخرجات السجل:

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)

راجع إعدادات التسجيل لمزيد من التفاصيل.

---

​

سيناريوهات شائعة لتصحيح الأخطاء

​

1. الاستعلام لا يُرجع النتائج المتوقعة

# 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. الاستعلام يعمل ببطء

# 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. فهم آلية اختيار المحرّك

# 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. تصحيح أخطاء مشكلات ذاكرة التخزين المؤقت

# 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

---

​

أفضل الممارسات

​

1. أجرِ تصحيح الأخطاء في Development، لا في بيئة الإنتاج

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

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

​

2. استخدم explain() قبل تشغيل الاستعلامات الكبيرة

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

# Check plan first
query.explain()

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

​

3. حلّل الأداء قبل التحسين

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

​

4. تحقّق من استعلام SQL عندما تكون النتائج غير صحيحة

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

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

---

​

ملخص أدوات تصحيح الأخطاء

الأداة	الأمر	المخرجات
شرح خطة التنفيذ	ds.explain()	خطوات التنفيذ + SQL
شرح مفصل	ds.explain(verbose=True)	+ البيانات الوصفية
عرض SQL	ds.to_sql()	سلسلة استعلام SQL
تمكين التصحيح	config.enable_debug()	السجلات التفصيلية
تمكين تحليل الأداء	config.enable_profiling()	بيانات التوقيت
تقرير محلّل الأداء	get_profiler().report()	ملخص الأداء
مسح محلّل الأداء	get_profiler().reset()	مسح بيانات التوقيت

---

​

الخطوات التالية

• الدالة explain() - توثيق مفصل لخطة التنفيذ
• دليل تحليل الأداء - قياس الأداء
• تهيئة التسجيل - إعداد مستوى السجل والتنسيق