تصحيح أخطاء DataStore

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

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

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

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

الحاجة	الأداة	الأمر
عرض خطة التنفيذ	`explain()`	`ds.explain()`
قياس الأداء	محلّل الأداء	`config.enable_profiling()`
تصحيح استعلامات SQL	Logging	`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()

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

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

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

تحليل الأداء

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

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

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

التسجيل

اعرض سجلات التنفيذ التفصيلية.

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
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() - توثيق مفصل لخطة التنفيذ
دليل تحليل الأداء - قياس الأداء
تهيئة التسجيل - إعداد مستوى السجل والتنسيق