التهيئة على مستوى الدالة

إعداد محرك التنفيذ وتصحيح Dtype على مستوى الدالة

يوفّر DataStore تحكمًا دقيقًا في التنفيذ على مستوى الدالة، بما في ذلك تحديد المحرك وتصحيح Dtype.

​

تهيئة دالة Engine

عيّن محرك التنفيذ مختلفًا لوظائف محددة.

​

إعداد محركات الدوال

from chdb.datastore.config import function_config

# Force specific functions to use chdb
function_config.use_chdb('length', 'substring', 'concat')

# Force specific functions to use pandas
function_config.use_pandas('upper', 'lower', 'capitalize')

# Set default preference
function_config.prefer_chdb()    # Default to chdb
function_config.prefer_pandas()  # Default to pandas

# Reset to auto
function_config.reset()

​

متى يُستخدم

افرض استخدام chdb في الحالات التالية:

• الدوال التي تحقق أداءً أفضل في ClickHouse
• الدوال التي تستفيد من تحسينات SQL
• عمليات السلاسل النصية/التاريخ والوقت واسعة النطاق

افرض استخدام pandas في الحالات التالية:

• الدوال ذات السلوك الخاص بـ pandas
• عندما تكون مطابقة pandas الدقيقة مطلوبة
• عمليات السلاسل النصية المخصّصة

​

مثال

from chdb import datastore as pd
from chdb.datastore.config import function_config

# Configure function engines
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper')

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

# length() will use chdb
ds['name_len'] = ds['name'].str.len()

# substring() will use chdb  
ds['prefix'] = ds['name'].str.slice(0, 3)

# upper() will use pandas
ds['name_upper'] = ds['name'].str.upper()

---

​

الدوال المشتركة

تتوفّر أكثر من 159 دالة في كلٍّ من محركَي chdb وpandas:

الفئة	الدوال
السلاسل النصية	length, upper, lower, trim, ltrim, rtrim, concat, substring, replace, reverse, contains, startswith, endswith
الرياضيات	abs, round, floor, ceil, exp, log, log10, sqrt, pow, sin, cos, tan
DateTime	year, month, day, hour, minute, second, dayofweek, dayofyear, quarter
التجميع	sum, avg, min, max, count, std, var, median

بالنسبة إلى الدوال المشتركة، يُحدَّد المحرك بناءً على:

1. الإعداد الصريح للدالة (إذا كان مضبوطًا)
2. إعداد execution_engine العام
3. الاختيار التلقائي استنادًا إلى السياق

---

​

الدوال الخاصة بـ chdb فقط

بعض الدوال لا تتوفر إلا عبر ClickHouse:

الفئة	الدوال
Array	arraySum, arrayAvg, arraySort, arrayDistinct, groupArray, arrayElement
JSON	JSONExtractString, JSONExtractInt, JSONExtractFloat, JSONHas
URL	domain, path, protocol, extractURLParameter
IP	IPv4StringToNum, IPv4NumToString, isIPv4String
Geo	greatCircleDistance, geoDistance, geoToH3
Hash	cityHash64, xxHash64, sipHash64, MD5, SHA256
Conditional	sumIf, countIf, avgIf, minIf, maxIf

تستخدم هذه الدوال محرك chdb تلقائيًا بغض النظر عن الإعدادات.

---

​

دوال خاصة بـ pandas

بعض الدوال لا تتوفر إلا من خلال pandas:

الفئة	الدوال
Apply	دوال lambda مخصصة، ودوال يعرّفها المستخدم
Complex Pivot	جداول Pivot مع تجميعات مخصصة
Stack/Unstack	عمليات معقدة لإعادة تشكيل البيانات
Interpolate	طُرق الاستيفاء للسلاسل الزمنية

تستخدم هذه الدوال تلقائيًا محرك pandas بغضّ النظر عن الإعدادات.

---

​

تصحيح Dtype

اضبط كيفية قيام DataStore بتصحيح أنواع البيانات بين المحركات.

​

مستويات التصحيح

from chdb.datastore.dtype_correction.config import CorrectionLevel
from chdb.datastore.config import config

# No correction
config.set_correction_level(CorrectionLevel.NONE)

# Critical types only (NULL handling, boolean)
config.set_correction_level(CorrectionLevel.CRITICAL)

# High priority (default) - common type mismatches
config.set_correction_level(CorrectionLevel.HIGH)

# Medium - more aggressive correction
config.set_correction_level(CorrectionLevel.MEDIUM)

# All - correct all possible types
config.set_correction_level(CorrectionLevel.ALL)

​

تفاصيل مستوى التصحيح

المستوى	الوصف	الأنواع المصحَّحة
NONE	من دون تصحيح تلقائي	لا شيء
CRITICAL	تصحيحات أساسية	معالجة NULL، وتحويل القيم المنطقية
HIGH (افتراضي)	تصحيحات شائعة	دقة الأعداد الصحيحة/العائمة، وDateTime، وترميز السلاسل النصية
MEDIUM	مزيد من التصحيحات	دقة Decimal، ومعالجة المنطقة الزمنية
ALL	أقصى تصحيح	جميع فروق الأنواع

​

متى تحتاج الأنواع إلى تصحيح

يمكن أن تظهر اختلافات في الأنواع عندما:

1. ClickHouse → pandas: أحجام مختلفة للأعداد الصحيحة (Int64 مقابل int64)
2. pandas → ClickHouse: تحويل كائنات Python إلى أنواع SQL
3. NULL handling: NA في pandas مقابل NULL في ClickHouse
4. Boolean: تمثيلات مختلفة للقيم المنطقية
5. DateTime: اختلافات في المناطق الزمنية

​

مثال

from chdb.datastore.dtype_correction.config import CorrectionLevel
from chdb.datastore.config import config

# Strict mode - expect exact type matches
config.set_correction_level(CorrectionLevel.NONE)

# Relaxed mode - auto-fix type issues
config.set_correction_level(CorrectionLevel.ALL)

---

​

واجهة برمجة تطبيقات تهيئة دالة

​

الكائن function_config

from chdb.datastore.config import function_config

# Force engine for functions
function_config.use_chdb(*function_names)
function_config.use_pandas(*function_names)

# Set default preference
function_config.prefer_chdb()
function_config.prefer_pandas()

# Reset to default (auto)
function_config.reset()

# Check configuration
function_config.get_engine('length')  # Returns 'chdb', 'pandas', or 'auto'

​

تجاوز المحرّك لكل استدعاء

تدعم بعض الطرائق تجاوز المحرّك لكل استدعاء:

# Using engine parameter (where supported)
ds['result'] = ds['col'].str.upper(engine='pandas')

---

​

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

​

1. ابدأ بالإعدادات الافتراضية

# Use auto mode, let DataStore decide
config.use_auto()

​

2. هيِّئ لأعباء عمل محددة

# For ClickHouse-optimized string processing
function_config.use_chdb('length', 'substring', 'concat')

# For pandas-compatible string behavior
function_config.use_pandas('upper', 'lower')

​

3. استخدم مستوى التصحيح المناسب

# Development: more permissive
config.set_correction_level(CorrectionLevel.ALL)

# Production: stricter
config.set_correction_level(CorrectionLevel.HIGH)

​

4. اختبر كلا المحركين

# Test with chdb
config.use_chdb()
result_chdb = process_data()

# Test with pandas
config.use_pandas()
result_pandas = process_data()

# Compare results
assert result_chdb.equals(result_pandas)