--- title: 'مرجع واجهة برمجة تطبيقات Python لـ chDB' sidebarTitle: 'واجهة Python البرمجية' slug: /chdb/api/python description: 'المرجع الكامل لواجهة برمجة تطبيقات Python الخاصة بـ chDB' keywords: ['chdb', 'مضمن', 'clickhouse-lite', 'python', 'api', 'مرجع'] doc_type: 'reference' ---
## دوال الاستعلام الأساسية
### `chdb.query`
تنفيذ استعلام SQL باستخدام محرك chDB. هذه هي دالة الاستعلام الرئيسية التي تنفّذ عبارات SQL باستخدام محرك ClickHouse المضمّن. وهي تدعم تنسيقات إخراج متعددة، ويمكنها العمل مع قواعد البيانات المؤقتة أو المستندة إلى الملفات. **البنية** ```python chdb.query(sql, output_format='CSV', path='', udf_path='') ``` **المعلمات** | المعلمة | النوع | القيمة الافتراضية | الوصف | | --------------- | ----- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sql` | str | *required* | سلسلة استعلام SQL المراد تنفيذها | | `output_format` | str | `"CSV"` | تنسيق إخراج النتائج. التنسيقات المدعومة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"Arrow"` - تنسيق Apache Arrow
• `"Parquet"` - تنسيق Parquet
• `"DataFrame"` - Pandas DataFrame
• `"ArrowTable"` - PyArrow Table
• `"Debug"` - تمكين التسجيل التفصيلي | | `path` | str | `""` | مسار ملف قاعدة البيانات. تكون القيمة الافتراضية قاعدة بيانات مؤقتة غير دائمة (تعادل `":memory:"`).
مرّر مسار ملف للاحتفاظ بالبيانات على القرص | | `udf_path` | str | `""` | مسار دليل UDF القديم المعتمد على العمليات الفرعية. غير مطلوب لدوال UDF الأصلية في بايثون ([`@func`](#func-decorator) / [`create_function`](#create-function)) | **القيم المعادة** يعيد نتيجة استعلام بالتنسيق المحدد: | نوع القيمة المعادة | الحالة | | ------------------ | ------------------------------------------------------------------- | | `str` | للتنسيقات النصية مثل CSV وJSON | | `pd.DataFrame` | عندما تكون قيمة `output_format` هي `"DataFrame"` أو `"dataframe"` | | `pa.Table` | عندما تكون قيمة `output_format` هي `"ArrowTable"` أو `"arrowtable"` | | chdb result object | للتنسيقات الأخرى | **الاستثناءات** | الاستثناء | الحالة | | ------------- | -------------------------------------------------------------- | | `ChdbError` | إذا فشل تنفيذ استعلام SQL | | `ImportError` | إذا كانت التبعيات المطلوبة لتنسيقات DataFrame/Arrow غير متوفرة | **أمثلة** ```pycon >>> # Basic CSV query >>> result = chdb.query("SELECT 1, 'hello'") >>> print(result) "1,hello" ``` ```pycon >>> # Query with DataFrame output >>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame") >>> print(df) id msg 0 1 hello ``` ```pycon >>> # Query with file-based database >>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb") ``` ***
### `chdb.sql`
تنفيذ استعلام SQL باستخدام محرك chDB. هذه هي دالة الاستعلام الرئيسية التي تنفّذ عبارات SQL باستخدام محرك ClickHouse المضمّن. وهي تدعم تنسيقات إخراج متعددة، ويمكنها العمل مع قواعد بيانات مؤقتة أو مستندة إلى الملفات. **البنية** ```python chdb.sql(sql, output_format='CSV', path='', udf_path='') ``` **المعلمات** | معلمة | Type | Default | Description | | --------------- | ---- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sql` | str | *required* | سلسلة استعلام SQL المطلوب تنفيذها | | `output_format` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المدعومة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"Arrow"` - تنسيق Apache Arrow
• `"Parquet"` - تنسيق Parquet
• `"DataFrame"` - Pandas DataFrame
• `"ArrowTable"` - PyArrow Table
• `"Debug"` - تمكين التسجيل التفصيلي | | `path` | str | `""` | مسار ملف قاعدة البيانات. القيمة الافتراضية هي قاعدة بيانات مؤقتة غير دائمة (تعادل `":memory:"`).
مرّر مسار ملف للاحتفاظ بالبيانات على القرص | | `udf_path` | str | `""` | المسار إلى دليل UDF القديم المعتمد على العمليات الفرعية. لا يلزم لدوال UDF الأصلية في بايثون ([`@func`](#func-decorator) / [`create_function`](#create-function)) | **القيم المعادة** تعيد نتيجة استعلام بالتنسيق المحدد: | نوع القيمة المعادة | Condition | | ------------------ | ------------------------------------------------------------------- | | `str` | للتنسيقات النصية مثل CSV وJSON | | `pd.DataFrame` | عندما تكون قيمة `output_format` هي `"DataFrame"` أو `"dataframe"` | | `pa.Table` | عندما تكون قيمة `output_format` هي `"ArrowTable"` أو `"arrowtable"` | | chdb result object | للتنسيقات الأخرى | **الاستثناءات** | استثناء | Condition | | ------------------------- | ---------------------------------------------------------- | | [`ChdbError`](#chdberror) | إذا فشل تنفيذ استعلام SQL | | `ImportError` | إذا كانت التبعيات المطلوبة لتنسيقات DataFrame/Arrow مفقودة | **أمثلة** ```pycon >>> # Basic CSV query >>> result = chdb.query("SELECT 1, 'hello'") >>> print(result) "1,hello" ``` ```pycon >>> # Query with DataFrame output >>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame") >>> print(df) id msg 0 1 hello ``` ```pycon >>> # Query with file-based database >>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb") ``` ***
### `chdb.to_arrowTable`
حوّل نتيجة استعلام إلى PyArrow Table. يحوّل نتيجة استعلام chdb إلى PyArrow Table لمعالجة البيانات العمودية بكفاءة. ويُرجِع جدولًا فارغًا إذا كانت النتيجة فارغة. **البنية** ```python chdb.to_arrowTable(res) ``` **المعلمات** | المعلمة | الوصف | | ------- | ------------------------------------------------------ | | `res` | كائن نتيجة query في chDB يحتوي على بيانات Arrow ثنائية | **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ---------------------------------- | | `pa.Table` | جدول PyArrow يحتوي على نتائج query | **الأخطاء المرفوعة** | نوع الخطأ | الوصف | | ------------- | ------------------------------------- | | `ImportError` | إذا لم يكن pyarrow أو pandas مثبّتَين | **مثال** ```pycon >>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow") >>> table = chdb.to_arrowTable(result) >>> print(table.to_pandas()) id msg 0 1 hello ``` ***
### `chdb.to_df`
حوِّل نتيجة الاستعلام إلى إطار بيانات Pandas. يحوِّل نتيجة استعلام في chDB إلى إطار بيانات Pandas عبر تحويلها أولًا إلى جدول PyArrow ثم إلى Pandas باستخدام تعدد الخيوط لتحسين الأداء. **البنية** ```python chdb.to_df(r) ``` **المعلمات** | المعلمة | الوصف | | ------- | ---------------------------------------------------------- | | `r` | كائن نتيجة استعلام في chDB يحتوي على بيانات Arrow الثنائية | **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | -------------------------------------------- | | `pd.DataFrame` | إطار بيانات pandas يحتوي على نتائج الاستعلام | **الاستثناءات** | الاستثناء | الحالة | | ------------- | ------------------------------------- | | `ImportError` | إذا لم يكن pyarrow أو pandas مثبّتَين | **مثال** ```pycon >>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow") >>> df = chdb.to_df(result) >>> print(df) id msg 0 1 hello ```
## إدارة الاتصالات والجلسات
تتوفر دوال الجلسة التالية:
### `chdb.connect`
أنشئ اتصالًا بخادم chDB الذي يعمل في الخلفية. تنشئ هذه الدالة [اتصالًا](#chdb-state-sqlitelike-connection) بمحرك قاعدة البيانات chDB ‏(ClickHouse). يُرجع كل استدعاء اتصالًا مستقلًا، ويمكن فتح أي عدد من الاتصالات بمسار قاعدة البيانات نفسه في الوقت ذاته. ```python chdb.connect(connection_string: str = ':memory:') → Connection ``` **المعلمات:** | المعلمة | النوع | الافتراضي | الوصف | | ------------------- | ----- | ------------ | ------------------------------------------------- | | `connection_string` | str | `":memory:"` | سلسلة اتصال قاعدة البيانات. راجع التنسيقات أدناه. | **التنسيقات الأساسية** | التنسيق | الوصف | | ------------------------- | ---------------------------- | | `":memory:"` | قاعدة بيانات مؤقتة (افتراضي) | | `"test.db"` | ملف قاعدة بيانات بمسار نسبي | | `"file:test.db"` | مثل المسار النسبي | | `"/path/to/test.db"` | ملف قاعدة بيانات بمسار مطلق | | `"file:/path/to/test.db"` | مثل المسار المطلق | **مع معلمات الاستعلام** | التنسيق | الوصف | | -------------------------------------------------- | ------------------- | | `"file:test.db?param1=value1¶m2=value2"` | مسار نسبي مع معلمات | | `"file::memory:?verbose&log-level=test"` | مؤقتة مع معلمات | | `"///path/to/test.db?param1=value1¶m2=value2"` | مسار مطلق مع معلمات | **التعامل مع معلمات الاستعلام** تُمرَّر معلمات الاستعلام إلى محرك ClickHouse كوسيطات بدء تشغيل. معالجة خاصة للمعلمات: | المعلمة الخاصة | تتحول إلى | الوصف | | ---------------- | -------------- | -------------------- | | `mode=ro` | `--readonly=1` | وضع القراءة فقط | | `verbose` | (علامة) | يفعّل التسجيل المفصل | | `log-level=test` | (إعداد) | يضبط مستوى التسجيل | للحصول على القائمة الكاملة للمعلمات، راجع `clickhouse local --help --verbose` **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Connection` | كائن اتصال بقاعدة البيانات يدعم:
• إنشاء مؤشرات باستخدام `Connection.cursor()`
• تنفيذ الاستعلامات مباشرةً باستخدام `Connection.query()`
• استعلامات البث باستخدام `Connection.send_query()`
• بروتوكول مدير السياق للتنظيف التلقائي | **الاستثناءات** | الاستثناء | الحالة | | -------------- | ------------------------------- | | `RuntimeError` | إذا فشل الاتصال بقاعدة البيانات | تشغّل العملية محركًا مضمنًا واحدًا مرتبطًا بمسار قاعدة بيانات واحد. يمكن لاتصالات متعددة بالمسار نفسه أن تتعايش وتنفّذ الاستعلامات بالتزامن. يؤدي فتح مسار *مختلف* أثناء وجود أي اتصال مفتوح إلى إثارة `RuntimeError`؛ أغلِق الاتصالات المفتوحة أولًا. **أمثلة** ```pycon >>> # Temporary database >>> conn = connect() >>> conn = connect(":memory:") >>> >>> # File-based database >>> conn = connect("my_data.db") >>> conn = connect("/path/to/data.db") >>> >>> # With parameters >>> conn = connect("data.db?mode=ro") # Read-only mode >>> conn = connect(":memory:?verbose&log-level=debug") # Debug logging >>> >>> # Using context manager for automatic cleanup >>> with connect("data.db") as conn: ... result = conn.query("SELECT 1") ... print(result) >>> # Connection automatically closed ``` **انظر أيضًا** * [`Connection`](#chdb-state-sqlitelike-connection) - فئة لاتصال قاعدة البيانات * [`Cursor`](#chdb-state-sqlitelike-cursor) - مؤشر قاعدة بيانات لعمليات DB-API 2.0
## التعامل مع الاستثناءات
### **فئة** `chdb.ChdbError`
الفئات الأساسية: `Exception` الفئة الأساسية للاستثناءات المرتبطة بـ chDB. يُرفَع هذا الاستثناء عندما يفشل تنفيذ استعلام في chDB أو عند حدوث خطأ. وهو يرث من فئة Exception القياسية في Python، ويوفّر معلومات عن الخطأ من محرك ClickHouse الداخلي. ***
### **الفئة** `chdb.session.Session`
الفئات الأساسية: `object` ستحتفظ الجلسة بحالة الاستعلام. إذا كانت قيمة path هي None، فستستخدم الجلسة قاعدة البيانات المؤقتة (`:memory:`) المشتركة على مستوى العملية، بحيث تتمكن جميع الجلسات التي لا تحدد مسارًا من رؤية جداول بعضها بعضًا؛ ولا يُزال دليلها المؤقت إلا عند إغلاق آخر جلسة أو اتصال من هذا النوع. يمكنك أيضًا تمرير مسار لإنشاء قاعدة بيانات في ذلك المسار للاحتفاظ ببياناتك. يمكنك أيضًا استخدام سلسلة اتصال لتمرير المسار ومعلمات أخرى. ```python class chdb.session.Session(path=None) ``` **أمثلة** | سلسلة الاتصال | الوصف | | -------------------------------------------------- | ------------------------------------ | | `":memory:"` | قاعدة بيانات مؤقتة | | `"test.db"` | مسار نسبي | | `"file:test.db"` | مثل ما سبق | | `"/path/to/test.db"` | مسار مطلق | | `"file:/path/to/test.db"` | مثل ما سبق | | `"file:test.db?param1=value1¶m2=value2"` | مسار نسبي مع معلمات استعلام | | `"file::memory:?verbose&log-level=test"` | قاعدة بيانات مؤقتة مع معلمات استعلام | | `"///path/to/test.db?param1=value1¶m2=value2"` | مسار مطلق مع معلمات استعلام | **معالجة وسائط سلسلة الاتصال** سلاسل الاتصال التي تحتوي على معلمات استعلام مثل “[file:test.db?param1=value1&param2=value2](file:test.db?param1=value1\¶m2=value2)” سيتم تمرير “param1=value1” إلى محرك ClickHouse كوسائط بدء التشغيل. لمزيد من التفاصيل، راجع `clickhouse local –help –verbose` طريقة معالجة بعض الوسائط الخاصة: * تتحول “mode=ro” إلى “–readonly=1” في clickhouse (وضع القراءة فقط) **مهم** * يمكن أن تتعايش عدة جلسات، ما دامت تشترك في مسار قاعدة البيانات نفسه. * لاستخدام مسار مختلف لقاعدة البيانات، أغلق الجلسة أو الجلسات المفتوحة أولًا. ***
#### `cleanup`
نظِّف موارد الجلسة مع معالجة الاستثناءات. تحاول هذه الطريقة إغلاق الجلسة مع تجاهل أي استثناءات قد تحدث أثناء عملية التنظيف. وهي مفيدة بشكل خاص في سيناريوهات معالجة الأخطاء أو عندما تحتاج إلى ضمان تنفيذ التنظيف بغضّ النظر عن حالة الجلسة. **البنية** ```python cleanup() ``` لن تتسبب هذه الطريقة مطلقًا في ظهور أي استثناء، مما يجعل استدعاءها آمنًا داخل كتل finally أو في الدوال المدمِّرة. **أمثلة** ```pycon >>> session = Session("test.db") >>> try: ... session.query("INVALID SQL") ... finally: ... session.cleanup() # Safe cleanup regardless of errors ``` **انظر أيضًا** * [`close()`](#chdb-session-session-close) - للإغلاق الصريح للجلسة مع تمرير الأخطاء ***
#### `close`
أغلق الجلسة وحرّر الموارد. تُغلق هذه الدالة الاتصال الأساسي وتعيد تعيين حالة الجلسة العامة. بعد استدعاء هذه الدالة، تصبح الجلسة غير صالحة ولا يمكن استخدامها لإجراء مزيد من الاستعلامات. **البنية** ```python close() ``` تُستدعى هذه الطريقة تلقائيًا عند استخدام الجلسة كمدير سياق أو عند حذف كائن الجلسة. **مهم** ستؤدي أي محاولة لاستخدام الجلسة بعد استدعاء `close()` إلى حدوث خطأ. **أمثلة** ```pycon >>> session = Session("test.db") >>> session.query("SELECT 1") >>> session.close() # Explicitly close the session ``` ***
#### `query`
نفِّذ استعلام SQL وأعِد النتائج. تُنفِّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد النتائج بالتنسيق المحدد. وتدعم هذه الطريقة تنسيقات إخراج متعددة، كما تحافظ على حالة الجلسة بين الاستعلامات. **البنية** ```python query(sql, fmt='CSV', udf_path='') ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ---------- | ----- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sql` | str | *مطلوب* | سلسلة استعلام SQL المطلوب تنفيذها | | `fmt` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المتاحة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"TabSeparated"` - قيم مفصولة بعلامات جدولة
• `"Pretty"` - تنسيق جدول منسّق
• `"JSONCompact"` - تنسيق JSON مضغوط
• `"Arrow"` - تنسيق Apache Arrow
• `"Parquet"` - تنسيق Parquet | | `udf_path` | str | `""` | مسار دليل UDF القديم المعتمد على العمليات الفرعية. لا يلزم للدوال الأصلية في بايثون UDF ([`@func`](#func-decorator) / [`create_function`](#create-function)). إذا لم يتم تحديده، فسيُستخدم مسار UDF من تهيئة الجلسة | **القيم المعادة** يعيد نتائج الاستعلام بالتنسيق المحدد. ويعتمد نوع القيمة المعادة الفعلي على معلمة التنسيق: * تنسيقات السلاسل النصية (CSV وJSON وما إلى ذلك) تعيد `str` * التنسيقات الثنائية (Arrow وParquet) تعيد `bytes` **الاستثناءات** | الاستثناء | الحالة | | -------------- | ------------------------------------- | | `RuntimeError` | إذا كانت الجلسة مغلقة أو غير صالحة | | `ValueError` | إذا كان استعلام SQL به خطأ في الصياغة | تنسيق “Debug” غير مدعوم، وسيُحوَّل تلقائيًا إلى “CSV” مع عرض تحذير. ولأغراض تصحيح الأخطاء، استخدم معلمات سلسلة الاتصال بدلًا من ذلك. **تحذير** تنفّذ هذه الطريقة الاستعلام بشكل متزامن وتحمّل جميع النتائج إلى الذاكرة. بالنسبة إلى مجموعات النتائج الكبيرة، فكّر في استخدام [`send_query()`](#chdb-session-session-send_query) للحصول على نتائج متدفقة. **أمثلة** ```pycon >>> session = Session("test.db") >>> >>> # Basic query with default CSV format >>> result = session.query("SELECT 1 as number") >>> print(result) number 1 ``` ```pycon >>> # Query with JSON format >>> result = session.query("SELECT 1 as number", fmt="JSON") >>> print(result) {"number": "1"} ``` ```pycon >>> # Complex query with table creation >>> session.query("CREATE TABLE test (id INT, name String) ENGINE = Memory") >>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')") >>> result = session.query("SELECT * FROM test ORDER BY id") >>> print(result) id,name 1,Alice 2,Bob ``` **انظر أيضًا** * [`send_query()`](#chdb-session-session-send_query) - لتنفيذ الاستعلام المتدفق * [`sql`](#chdb-session-session-sql) - اسم مستعار لهذه الطريقة ***
#### `send_query`
نفّذ استعلام SQL وأعِد مكرّرًا لنتيجة متدفقة. تُنفّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد كائن نتيجة متدفقة يتيح لك التكرار عبر النتائج دون تحميل كل شيء إلى الذاكرة دفعة واحدة. ويُعد هذا مفيدًا بشكل خاص مع مجموعات النتائج الكبيرة. **البنية** ```python send_query(sql, fmt='CSV') → StreamingResult ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------- | ----- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sql` | str | *required* | سلسلة استعلام SQL المطلوب تنفيذها | | `fmt` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المتاحة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"TabSeparated"` - قيم مفصولة بعلامات تبويب
• `"JSONCompact"` - تنسيق JSON مضغوط
• `"Arrow"` - تنسيق Apache Arrow
• `"Parquet"` - تنسيق Parquet | **القيم المُعادة** | نوع القيمة المُعادة | الوصف | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `StreamingResult` | مُكرِّر نتائج متدفقة يُرجِع نتائج الاستعلام تدريجيًا. ويمكن استخدام هذا المُكرِّر في حلقات for أو تحويله إلى بُنى بيانات أخرى | **الاستثناءات** | الاستثناء | الشرط | | -------------- | ------------------------------------ | | `RuntimeError` | إذا كانت الجلسة مغلقة أو غير صالحة | | `ValueError` | إذا كان استعلام SQL غير صحيح الصياغة | تنسيق “Debug” غير مدعوم، وسيُحوَّل تلقائيًا إلى “CSV” مع تحذير. ولأغراض تصحيح الأخطاء، استخدم معلمات سلسلة الاتصال بدلًا من ذلك. يجب استهلاك كائن StreamingResult المُعاد بسرعة أو تخزينه على نحو مناسب، لأنه يحتفظ باتصال بقاعدة البيانات. **أمثلة** ```pycon >>> session = Session("test.db") >>> session.query("CREATE TABLE big_table (id INT, data String) ENGINE = MergeTree() order by id") >>> >>> # Insert large dataset >>> for i in range(1000): ... session.query(f"INSERT INTO big_table VALUES ({i}, 'data_{i}')") >>> >>> # Stream results to avoid memory issues >>> streaming_result = session.send_query("SELECT * FROM big_table ORDER BY id") >>> for chunk in streaming_result: ... print(f"Processing chunk: {len(chunk)} bytes") ... # Process chunk without loading entire result set ``` ```pycon >>> # Using with context manager >>> with session.send_query("SELECT COUNT(*) FROM big_table") as stream: ... for result in stream: ... print(f"Count result: {result}") ``` **راجع أيضًا** * [`query()`](#chdb-session-session-query) - لتنفيذ الاستعلامات غير المتدفقة * `chdb.state.sqlitelike.StreamingResult` - مُكرِّر النتائج المتدفقة ***
#### `sql`
نفِّذ استعلام SQL وأعِد النتائج. تُنفِّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد النتائج بالتنسيق المحدد. كما تدعم هذه الطريقة تنسيقات إخراج متعددة، وتحافظ على حالة الجلسة بين الاستعلامات. **بنية** ```python sql(sql, fmt='CSV', udf_path='') ``` **المعلمات** | المعلمة | النوع | القيمة الافتراضية | الوصف | | ---------- | ----- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sql` | str | *required* | سلسلة استعلام SQL المطلوب تنفيذه | | `fmt` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المتاحة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"TabSeparated"` - قيم مفصولة بعلامات تبويب
• `"Pretty"` - تنسيق جدول منسق
• `"JSONCompact"` - تنسيق JSON مضغوط
• `"Arrow"` - تنسيق Apache Arrow
• `"Parquet"` - تنسيق Parquet | | `udf_path` | str | `""` | مسار دليل UDF القديم المعتمد على العمليات الفرعية. لا يلزم لدوال بايثون UDF الأصلية ([`@func`](#func-decorator) / [`create_function`](#create-function)). إذا لم يتم تحديده، فسيُستخدم مسار UDF من تهيئة الجلسة | **القيم المعادة** تُعيد نتائج الاستعلام بالتنسيق المحدد. ويعتمد نوع القيمة المعادة الفعلي على معلمة التنسيق: * تُعيد تنسيق السلاسل النصية ‏(مثل CSV وJSON وغيرها) قيمة من النوع `str` * تُعيد التنسيقات الثنائية ‏(Arrow وParquet) قيمة من النوع `bytes` **الاستثناءات:** | الاستثناء | الحالة | | -------------- | ------------------------------------ | | `RuntimeError` | إذا كانت الجلسة مغلقة أو غير صالحة | | `ValueError` | إذا كان استعلام SQL غير صحيح الصياغة | تنسيق “Debug” غير مدعوم، وسيُحوَّل تلقائيًا إلى “CSV” مع عرض تحذير. لتصحيح الأخطاء، استخدم معلمات سلسلة الاتصال بدلًا من ذلك. **تحذير** تنفّذ هذه الطريقة الاستعلام بشكل متزامن وتحمّل جميع النتائج إلى الذاكرة. بالنسبة إلى مجموعات النتائج الكبيرة، يُرجى التفكير في استخدام [`send_query()`](#chdb-session-session-send_query) للحصول على نتائج متدفقة. **أمثلة** ```pycon >>> session = Session("test.db") >>> >>> # Basic query with default CSV format >>> result = session.query("SELECT 1 as number") >>> print(result) number 1 ``` ```pycon >>> # Query with JSON format >>> result = session.query("SELECT 1 as number", fmt="JSON") >>> print(result) {"number": "1"} ``` ```pycon >>> # Complex query with table creation >>> session.query("CREATE TABLE test (id INT, name String) ENGINE = MergeTree() order by id") >>> session.query("INSERT INTO test VALUES (1, 'Alice'), (2, 'Bob')") >>> result = session.query("SELECT * FROM test ORDER BY id") >>> print(result) id,name 1,Alice 2,Bob ``` **انظر أيضًا** * [`send_query()`](#chdb-session-session-send_query) - لتنفيذ الاستعلامات المتدفقة * [`sql`](#chdb-session-session-sql) - اسم مستعار لهذه الطريقة
## إدارة الحالة
### `chdb.state.connect`
أنشئ [اتصالًا](#chdb-state-sqlitelike-connection) مع الخادم الخلفي لـ chDB. تنشئ هذه الدالة اتصالًا بمحرك قاعدة بيانات chDB ‏(ClickHouse). يعيد كل استدعاء اتصالًا مستقلًا، ويمكن فتح أي عدد من الاتصالات إلى مسار قاعدة البيانات نفسه في الوقت ذاته. **الصياغة** ```python chdb.state.connect(connection_string: str = ':memory:') → Connection ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ---------------------------------- | ----- | ------------ | ------------------------------------------------- | | `connection_string(str, optional)` | str | `":memory:"` | سلسلة اتصال قاعدة البيانات. راجع التنسيقات أدناه. | **التنسيقات الأساسية** تنسيقات سلاسل الاتصال المدعومة: | التنسيق | الوصف | | ------------------------- | ----------------------------------- | | `":memory:"` | قاعدة بيانات داخل الذاكرة (افتراضي) | | `"test.db"` | ملف قاعدة بيانات بمسار نسبي | | `"file:test.db"` | مثل المسار النسبي | | `"/path/to/test.db"` | ملف قاعدة بيانات بمسار مطلق | | `"file:/path/to/test.db"` | مثل المسار المطلق | **مع معلمات الاستعلام** | التنسيق | الوصف | | -------------------------------------------------- | ---------------------- | | `"file:test.db?param1=value1¶m2=value2"` | مسار نسبي مع معلمات | | `"file::memory:?verbose&log-level=test"` | داخل الذاكرة مع معلمات | | `"///path/to/test.db?param1=value1¶m2=value2"` | مسار مطلق مع معلمات | **معالجة معلمات الاستعلام** تُمرَّر معلمات الاستعلام إلى محرك ClickHouse كوسيطات بدء تشغيل. توجد معالجة خاصة لبعض المعلمات: | المعلمة الخاصة | تتحول إلى | الوصف | | ---------------- | -------------- | -------------------- | | `mode=ro` | `--readonly=1` | وضع القراءة فقط | | `verbose` | (flag) | يفعّل التسجيل المفصل | | `log-level=test` | (setting) | يضبط مستوى التسجيل | للحصول على قائمة كاملة بالمعلمات، راجع `clickhouse local --help --verbose` **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Connection` | كائن اتصال بقاعدة البيانات يدعم:
• إنشاء المؤشرات باستخدام `Connection.cursor()`
• تنفيذ الاستعلامات المباشرة باستخدام `Connection.query()`
• الاستعلامات المتدفقة باستخدام `Connection.send_query()`
• بروتوكول مدير السياق للتنظيف التلقائي | **الاستثناءات** | الاستثناء | الحالة | | -------------- | ------------------------------- | | `RuntimeError` | إذا فشل الاتصال بقاعدة البيانات | تشغّل العملية محركًا مضمنًا واحدًا مرتبطًا بمسار قاعدة بيانات واحد. يمكن لاتصالات متعددة بالمسار نفسه أن تتعايش وتنفّذ الاستعلامات بالتزامن. يؤدي فتح مسار *مختلف* في أثناء وجود أي اتصال مفتوح إلى ظهور `RuntimeError`؛ لذا أغلق الاتصالات المفتوحة أولًا. **أمثلة** ```pycon >>> # Temporary database >>> conn = connect() >>> conn = connect(":memory:") >>> >>> # File-based database >>> conn = connect("my_data.db") >>> conn = connect("/path/to/data.db") >>> >>> # With parameters >>> conn = connect("data.db?mode=ro") # Read-only mode >>> conn = connect(":memory:?verbose&log-level=debug") # Debug logging >>> >>> # Using context manager for automatic cleanup >>> with connect("data.db") as conn: ... result = conn.query("SELECT 1") ... print(result) >>> # Connection automatically closed ``` **انظر أيضًا** * `Connection` - فئة اتصال بقاعدة البيانات * `Cursor` - مؤشر قاعدة البيانات لعمليات DB-API 2.0
### **الفئة** `chdb.state.sqlitelike.Connection`
الفئات الأساسية: `object` **الصياغة** ```python class chdb.state.sqlitelike.Connection(connection_string: str) ``` ***
#### `close`
أغلق الاتصال ونظّف الموارد. تُغلق هذه الطريقة اتصال قاعدة البيانات وتُنظّف أي موارد مرتبطة به، بما في ذلك المؤشرات النشطة. بعد استدعاء هذه الطريقة، يصبح الاتصال غير صالح ولا يمكن استخدامه في أي عمليات لاحقة. **الصياغة** ```python close() → None ``` تسترجع هذه الطريقة النتيجة نفسها عند استدعائها أكثر من مرة، لذا فإن استدعاءها عدة مرات آمن. **تحذير** سيتم إلغاء أي استعلامات متدفقة جارية عند إغلاق الاتصال. تأكد من معالجة جميع البيانات المهمة قبل إغلاق الاتصال. **أمثلة** ```pycon >>> conn = connect("test.db") >>> # Use connection for queries >>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory") >>> # Close when done >>> conn.close() ``` ```pycon >>> # Using with context manager (automatic cleanup) >>> with connect("test.db") as conn: ... conn.query("SELECT 1") ... # Connection automatically closed ``` ***
#### `cursor`
أنشئ كائن [Cursor](#chdb-state-sqlitelike-cursor) لتنفيذ الاستعلامات. تُنشئ هذه الطريقة مؤشر قاعدة بيانات يوفّر واجهة DB-API 2.0 القياسية لتنفيذ الاستعلامات وجلب النتائج. ويتيح المؤشر تحكمًا دقيقًا في تنفيذ الاستعلام واسترجاع النتائج. **الصياغة** ```python cursor() → Cursor ``` **يعيد** | نوع القيمة المعادة | الوصف | | ----------- | ---------------------------------- | | `Cursor` | كائن Cursor لعمليات قاعدة البيانات | سيؤدي إنشاء مؤشر جديد إلى استبدال أي مؤشر موجود مرتبط بهذا الاتصال. لا يُدعَم إلا مؤشر واحد لكل اتصال. **أمثلة** ```pycon >>> conn = connect(":memory:") >>> cursor = conn.cursor() >>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory") >>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')") >>> cursor.execute("SELECT * FROM test") >>> rows = cursor.fetchall() >>> print(rows) ((1, 'Alice'),) ``` **انظر أيضًا** * [`Cursor`](#chdb-state-sqlitelike-cursor) - تنفيذ لمؤشّر قاعدة البيانات ***
#### `query`
نفّذ استعلام SQL وأعِد النتائج كاملةً. تُنفِّذ هذه الطريقة استعلام SQL بشكل متزامن وتُعيد مجموعة النتائج كاملةً. وهي تدعم تنسيقات إخراج متعددة وتُطبّق تلقائيًا المعالجة اللاحقة الخاصة بكل تنسيق. **الصياغة** ```python query(query: str, format: str = 'CSV') → Any ``` **المعلمات:** | المعلمة | النوع | الافتراضي | الوصف | | -------- | ----- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | str | *required* | سلسلة استعلام SQL المراد تنفيذه | | `format` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المدعومة:
• `"CSV"` - قيم مفصولة بفواصل (string)
• `"JSON"` - تنسيق JSON ‏(string)
• `"Arrow"` - تنسيق Apache Arrow ‏(bytes)
• `"Dataframe"` - Pandas DataFrame (يتطلب pandas)
• `"Arrowtable"` - PyArrow Table (يتطلب pyarrow) | **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ---------------------------- | | `str` | للتنسيقات النصية (CSV, JSON) | | `bytes` | لتنسيق Arrow | | `pandas.DataFrame` | لتنسيق dataframe | | `pyarrow.Table` | لتنسيق arrowtable | **الاستثناءات** | الاستثناء | الشرط | | -------------- | ---------------------------------------- | | `RuntimeError` | إذا فشل تنفيذ الاستعلام | | `ImportError` | إذا لم تكن الحزم المطلوبة للتنسيق مثبّتة | **تحذير** تُحمِّل هذه الطريقة مجموعة النتائج بالكامل إلى الذاكرة. بالنسبة إلى النتائج الكبيرة، يُنصح باستخدام [`send_query()`](#chdb-state-sqlitelike-connection-send_query) للبث. **أمثلة** ```pycon >>> conn = connect(":memory:") >>> >>> # Basic CSV query >>> result = conn.query("SELECT 1 as num, 'hello' as text") >>> print(result) num,text 1,hello ``` ```pycon >>> # DataFrame format >>> df = conn.query("SELECT number FROM numbers(5)", "dataframe") >>> print(df) number 0 0 1 1 2 2 3 3 4 4 ``` **انظر أيضًا** * [`send_query()`](#chdb-state-sqlitelike-connection-send_query) - لتنفيذ الاستعلامات المتدفقة ***
#### `send_query`
نفّذ استعلام SQL وأعِد مكرّرًا لنتيجة متدفقة. تنفّذ هذه الطريقة استعلام SQL وتُعيد كائن StreamingResult يتيح لك التكرار عبر النتائج دون تحميل كل شيء في الذاكرة دفعة واحدة. وهذا مثالي لمعالجة مجموعات النتائج الكبيرة. **البنية** ```python send_query(query: str, format: str = 'CSV') → StreamingResult ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | -------- | ----- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | str | *required* | سلسلة استعلام SQL المراد تنفيذه | | `format` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المدعومة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"Arrow"` - تنسيق Apache Arrow (يتيح استخدام الطريقة `record_batch()`)
• `"dataframe"` - أجزاء Pandas DataFrame
• `"arrowtable"` - أجزاء PyArrow Table | **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `StreamingResult` | مكرّر تدفقي لنتائج الاستعلام يدعم:
• بروتوكول Iterator (لحلقات for)
• بروتوكول Context manager (لعبارات with)
• الجلب اليدوي باستخدام الطريقة `fetch()`
• تدفّق PyArrow RecordBatch (بتنسيق Arrow فقط) | **الاستثناءات** | الاستثناء | الشرط | | -------------- | ---------------------------------------- | | `RuntimeError` | إذا فشل تنفيذ الاستعلام | | `ImportError` | إذا لم تكن الحزم المطلوبة للتنسيق مثبّتة | تنسيق “Arrow” فقط هو الذي يدعم الطريقة `record_batch()` على `StreamingResult` المُعاد. **أمثلة** ```pycon >>> conn = connect(":memory:") >>> >>> # Basic streaming >>> stream = conn.send_query("SELECT number FROM numbers(1000)") >>> for chunk in stream: ... print(f"Processing chunk: {len(chunk)} bytes") ``` ```pycon >>> # Using context manager for cleanup >>> with conn.send_query("SELECT * FROM large_table") as stream: ... chunk = stream.fetch() ... while chunk: ... process_data(chunk) ... chunk = stream.fetch() ``` ```pycon >>> # Arrow format with RecordBatch streaming >>> stream = conn.send_query("SELECT * FROM data", "Arrow") >>> reader = stream.record_batch(rows_per_batch=10000) >>> for batch in reader: ... print(f"Batch shape: {batch.num_rows} x {batch.num_columns}") ``` **انظر أيضًا** * [`query()`](#chdb-state-sqlitelike-connection-query) - لتنفيذ الاستعلامات غير المتدفقة * [`StreamingResult`](#chdb-state-sqlitelike-streamingresult) - مكرّر نتائج البث ***
### **فئة** `chdb.state.sqlitelike.StreamingResult`
الفئات الأساسية: `object` مكرِّر نتائج متدفقة لمعالجة نتائج الاستعلامات الكبيرة. توفّر هذه الفئة واجهة تكرار لنتائج الاستعلامات المتدفقة دون تحميل مجموعة النتائج بالكامل إلى الذاكرة. وهي تدعم تنسيقات إخراج متنوعة وتوفّر أساليب للجلب اليدوي للنتائج وبثّ RecordBatch من PyArrow. ```python class chdb.state.sqlitelike.StreamingResult ``` ***
#### `fetch`
اجلب الجزء التالي من نتائج الاستعلام المتدفقة. تسترجع هذه الطريقة الجزء التالي المتاح من البيانات من نتيجة الاستعلام المتدفق. ويعتمد تنسيق البيانات المُعادة على التنسيق المحدد عند بدء الاستعلام المتدفق. **الصياغة** ```python fetch() → Any ``` **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ----------------------------------- | | `str` | للتنسيقات النصية (CSV، JSON) | | `bytes` | للتنسيقات الثنائية (Arrow، Parquet) | | `None` | عند استنفاد دفق النتائج | **أمثلة** ```pycon >>> stream = conn.send_query("SELECT * FROM large_table") >>> chunk = stream.fetch() >>> while chunk is not None: ... process_data(chunk) ... chunk = stream.fetch() ``` ***
#### `cancel`
ألغِ الاستعلام المتدفق وحرِّر الموارد. تلغي هذه الطريقة أي استعلام متدفق جارٍ وتحرِّر الموارد المرتبطة به. ويجب استدعاؤها عندما تريد إيقاف معالجة النتائج قبل انتهاء التدفق. **الصياغة** ```python cancel() → None ``` **أمثلة** ```pycon >>> stream = conn.send_query("SELECT * FROM very_large_table") >>> for i, chunk in enumerate(stream): ... if i >= 10: # Only process first 10 chunks ... stream.cancel() ... break ... process_data(chunk) ``` ***
#### `close`
أغلق النتيجة المتدفقة ونظّف الموارد. اسم مستعار لـ [`cancel()`](#streamingresult-cancel). يُغلق مُكرِّر النتيجة المتدفقة ويحرّر أي موارد مرتبطة بها. **الصياغة** ```python close() → None ``` ***
#### `record_batch`
أنشئ `PyArrow RecordBatchReader` لمعالجة الدُفعات بكفاءة. تُنشئ هذه الطريقة كائن `PyArrow RecordBatchReader` يتيح التكرار بكفاءة عبر نتائج الاستعلام بتنسيق Arrow. وهذه هي الطريقة الأكثر كفاءة لمعالجة مجموعات النتائج الكبيرة عند استخدام `PyArrow`. **الصياغة** ```python record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ---------------- | ----- | --------- | --------------------- | | `rows_per_batch` | int | `1000000` | عدد الصفوف في كل دفعة | **القيم المعادة** | نوع القيمة المعادة | الوصف | | ---------------------- | ------------------------------------------------------ | | `pa.RecordBatchReader` | قارئ RecordBatchReader من PyArrow للتكرار على الدُفعات | لا تتوفر هذه الطريقة إلا إذا بدأ الاستعلام المتدفق باستخدام `format="Arrow"`. وسيؤدي استخدامها مع تنسيقات أخرى إلى حدوث خطأ. **أمثلة** ```pycon >>> stream = conn.send_query("SELECT * FROM data", format="Arrow") >>> reader = stream.record_batch(rows_per_batch=10000) >>> for batch in reader: ... print(f"Processing batch: {batch.num_rows} rows") ... df = batch.to_pandas() ... process_dataframe(df) ``` ***
#### بروتوكول المكرِّر
يدعم StreamingResult بروتوكول المكرِّر في بايثون، مما يسمح باستخدامه مباشرةً في حلقات for: ```pycon >>> stream = conn.send_query("SELECT number FROM numbers(1000000)") >>> for chunk in stream: ... print(f"Chunk size: {len(chunk)} bytes") ``` ***
#### بروتوكول مدير السياق
يدعم StreamingResult بروتوكول مدير السياق للتنظيف التلقائي للموارد: ```pycon >>> with conn.send_query("SELECT * FROM data") as stream: ... for chunk in stream: ... process(chunk) >>> # Stream automatically closed ``` ***
### **الصنف** `chdb.state.sqlitelike.Cursor`
الصنف الأساسي: `object` ```python class chdb.state.sqlitelike.Cursor(connection) ``` ***
#### `close`
أغلِق المؤشر ونظِّف الموارد. تُغلق هذه الطريقة المؤشر وتُنظِّف أي موارد مرتبطة به. بعد استدعاء هذه الطريقة، يصبح المؤشر غير صالح ولا يمكن استخدامه في عمليات لاحقة. **الصيغة** ```python close() → None ``` هذه الطريقة مكررة الأثر — لذا من الآمن استدعاؤها عدة مرات. ويُغلَق المؤشر تلقائيًا أيضًا عند إغلاق الاتصال. **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT 1") >>> result = cursor.fetchone() >>> cursor.close() # Cleanup cursor resources ``` ***
#### `column_names`
أعِد قائمة بأسماء الأعمدة من آخر استعلام نُفِّذ. تُرجِع هذه الطريقة أسماء الأعمدة من أحدث استعلام SELECT تم تنفيذه. وتُرجَع الأسماء بالترتيب نفسه الذي تظهر به في مجموعة النتائج. **الصيغة** ```python column_names() → list ``` **القيمة المُعادة** | نوع القيمة المُعادة | الوصف | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | `list` | قائمة بسلاسل نصية تمثل أسماء الأعمدة، أو قائمة فارغة إذا لم يُنفَّذ أي استعلام أو لم يُرجِع الاستعلام أي أعمدة | **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT id, name, email FROM users LIMIT 1") >>> print(cursor.column_names()) ['id', 'name', 'email'] ``` **انظر أيضًا** * [`column_types()`](#chdb-state-sqlitelike-cursor-column_types) - الحصول على معلومات عن نوع العمود * [`description`](#chdb-state-sqlitelike-cursor-description) - وصف العمود في DB-API 2.0 ***
#### `column_types`
أعِد قائمةً بأنواع الأعمدة من آخر استعلام تم تنفيذه. تعيد هذه الطريقة أسماء أنواع أعمدة ClickHouse من أحدث استعلام SELECT تم تنفيذه. وتُعاد الأنواع بالترتيب نفسه الذي تظهر به في مجموعة النتائج. **الصيغة** ```python column_types() → list ``` **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `list` | قائمة بسلاسل نصية لأسماء الأنواع في ClickHouse، أو قائمة فارغة إذا لم يُنفَّذ أي استعلام أو إذا لم يُرجِع الاستعلام أي أعمدة | **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT toInt32(1), toString('hello')") >>> print(cursor.column_types()) ['Int32', 'String'] ``` **انظر أيضًا** * [`column_names()`](#chdb-state-sqlitelike-cursor-column_names) - الحصول على معلومات عن أسماء الأعمدة * [`description`](#chdb-state-sqlitelike-cursor-description) - وصف الأعمدة وفقًا لـ DB-API 2.0 ***
#### `commit`
ثبّت أي معاملة قيد الانتظار. تُثبّت هذه الطريقة أي معاملة قاعدة بيانات قيد الانتظار. في ClickHouse، تُثبَّت معظم العمليات تلقائيًا، لكن هذه الطريقة مُتاحة من أجل التوافق مع DB-API 2.0. يُثبّت ClickHouse العمليات تلقائيًا في العادة، لذا لا تكون استدعاءات `commit` الصريحة ضروريةً غالبًا. وهذه الطريقة مُتاحة من أجل التوافق مع سير العمل القياسي لـ DB-API 2.0. **الصيغة** ```python commit() → None ``` **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("INSERT INTO test VALUES (1, 'data')") >>> cursor.commit() ``` ***
#### `property description : list`
يعيد وصف الأعمدة وفقًا لمواصفة DB-API 2.0. تعيد هذه الخاصية قائمة من tuples، يتكوّن كل منها من 7 عناصر تصف كل عمود في مجموعة نتائج آخر استعلام SELECT تم تنفيذه. يحتوي كل Tuple على: (name, type_code, display_size, internal_size, precision, scale, null_ok) حاليًا، لا يتم توفير سوى `name` و `type_code`، بينما تُضبط الحقول الأخرى على None. **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | -------------------------------------------------------------------------------- | | `list` | قائمة من 7-tuples تصف كل عمود، أو قائمة فارغة إذا لم يتم تنفيذ أي استعلام SELECT | يتوافق هذا مع مواصفة DB-API 2.0 الخاصة بـ cursor.description. ولا يحتوي إلا العنصران الأولان (`name` و `type_code`) على بيانات فعلية في هذا التنفيذ. **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT id, name FROM users LIMIT 1") >>> for desc in cursor.description: ... print(f"Column: {desc[0]}, Type: {desc[1]}") Column: id, Type: Int32 Column: name, Type: String ``` **انظر أيضًا** * [`column_names()`](#chdb-state-sqlitelike-cursor-column_names) - الحصول على أسماء الأعمدة فقط * [`column_types()`](#chdb-state-sqlitelike-cursor-column_types) - الحصول على أنواع الأعمدة فقط ***
#### `execute`
نفّذ استعلام SQL وجهّز النتائج للاسترداد. تنفّذ هذه الطريقة استعلام SQL وتجهّز النتائج لاستردادها باستخدام طرق الجلب. كما تتولى تحليل بيانات النتائج وإجراء التحويل التلقائي لأنواع بيانات ClickHouse. **الصيغة** ```python execute(query: str) → None ``` **المعلمات:** | المعلمة | النوع | الوصف | | ------- | ----- | -------------------------------- | | `query` | str | سلسلة استعلام SQL المطلوب تنفيذه | **الاستثناءات** | الاستثناء | الشرط | | ----------- | -------------------------------------------- | | `Exception` | إذا فشل تنفيذ الاستعلام أو فشل تحليل النتيجة | تتبع هذه الطريقة مواصفات DB-API 2.0 الخاصة بـ `cursor.execute()`. بعد التنفيذ، استخدم `fetchone()` أو `fetchmany()` أو `fetchall()` من أجل استرجاع النتائج. تحوّل هذه الطريقة تلقائيًا أنواع بيانات ClickHouse إلى أنواع Python المناسبة: * أنواع Int/UInt → int * أنواع Float → float * String/FixedString → str * DateTime → datetime.datetime * Date → datetime.date * Bool → bool **أمثلة** ```pycon >>> cursor = conn.cursor() >>> >>> # Execute DDL >>> cursor.execute("CREATE TABLE test (id INT, name String) ENGINE = Memory") >>> >>> # Execute DML >>> cursor.execute("INSERT INTO test VALUES (1, 'Alice')") >>> >>> # Execute SELECT and fetch results >>> cursor.execute("SELECT * FROM test") >>> rows = cursor.fetchall() >>> print(rows) ((1, 'Alice'),) ``` **انظر أيضًا** * [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - استرجاع صف واحد * [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - استرجاع عدة صفوف * [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - استرجاع جميع الصفوف المتبقية ***
#### `fetchall`
اجلب جميع الصفوف المتبقية من نتيجة الاستعلام. تسترجع هذه الطريقة جميع الصفوف المتبقية من مجموعة نتائج الاستعلام الحالية بدءًا من موضع المؤشر الحالي. وتُرجع `tuple` من `tuple` للصفوف مع تطبيق تحويل أنواع Python المناسب. **البنية** ```python fetchall() → tuple ``` **القيمة المعادة:** | Return Type | Description | | ----------- | --------------------------------------------------------------------------------------------------------- | | `tuple` | Tuple تحتوي على جميع صفوف Tuple المتبقية في مجموعة النتائج. وتُرجع Tuple فارغة إذا لم تكن هناك صفوف متاحة | **تحذير** تُحمّل هذه الطريقة جميع الصفوف المتبقية إلى الذاكرة دفعة واحدة. بالنسبة إلى مجموعات النتائج الكبيرة، فكّر في استخدام [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) لمعالجة النتائج على دفعات. **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT id, name FROM users") >>> all_users = cursor.fetchall() >>> for user_id, user_name in all_users: ... print(f"User {user_id}: {user_name}") ``` **انظر أيضًا** * [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - جلب صف واحد * [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - جلب عدة صفوف على دفعات ***
#### `fetchmany`
اجلب عدة صفوف من نتيجة الاستعلام. تسترجع هذه الطريقة ما يصل إلى `size` صفًا من مجموعة نتائج الاستعلام الحالية. وتُرجع tuple من tuples للصفوف، بحيث يحتوي كل صف على قيم الأعمدة مع تحويل مناسب إلى أنواع Python. **الصيغة** ```python fetchmany(size: int = 1) → tuple ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------- | ----- | --------- | ------------------------------------- | | `size` | int | `1` | الحد الأقصى لعدد الصفوف المطلوب جلبها | **القيم المعادة** | نوع الإرجاع | الوصف | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `tuple` | قيمة `Tuple` تحتوي على ما يصل إلى 'size' من الصفوف في هيئة tuples. وقد تحتوي على عدد أقل من الصفوف إذا استُنفدت مجموعة النتائج | تتبع هذه الطريقة مواصفات DB-API 2.0. وستُرجع عددًا أقل من 'size' صفوف إذا استُنفدت مجموعة النتائج. **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT * FROM large_table") >>> >>> # Process results in batches >>> while True: ... batch = cursor.fetchmany(100) # Fetch 100 rows at a time ... if not batch: ... break ... process_batch(batch) ``` **انظر أيضًا** * [`fetchone()`](#chdb-state-sqlitelike-cursor-fetchone) - جلب صف واحد * [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - جلب جميع الصفوف المتبقية ***
#### `fetchone`
اجلب الصف التالي من نتيجة الاستعلام. تسترجع هذه الطريقة الصف التالي المتاح من مجموعة نتائج الاستعلام الحالية. وتُرجع قيمة من نوع tuple تحتوي على قيم الأعمدة مع تطبيق التحويل المناسب إلى أنواع Python. **الصيغة** ```python fetchone() → tuple | None ``` **يعيد:** | نوع الإرجاع | الوصف | | ----------------- | ---------------------------------------------------------------------------- | | `Optional[tuple]` | الصف التالي على شكل tuple من قيم الأعمدة، أو None إذا لم تعد هناك صفوف متاحة | تتبع هذه method مواصفات DB-API 2.0. وتُحوَّل قيم الأعمدة تلقائيًا إلى أنواع Python المناسبة استنادًا إلى أنواع أعمدة ClickHouse. **أمثلة** ```pycon >>> cursor = conn.cursor() >>> cursor.execute("SELECT id, name FROM users") >>> row = cursor.fetchone() >>> while row is not None: ... user_id, user_name = row ... print(f"User {user_id}: {user_name}") ... row = cursor.fetchone() ``` **انظر أيضًا** * [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) - استرجاع عدة صفوف * [`fetchall()`](#chdb-state-sqlitelike-cursor-fetchall) - استرجاع جميع الصفوف المتبقية ***
### `chdb.state.sqlitelike`
حوِّل نتيجة الاستعلام إلى PyArrow Table. تُحوِّل هذه الدالة نتائج استعلامات chdb إلى تنسيق PyArrow Table، مما يوفّر وصولًا فعّالًا إلى البيانات المخزّنة عموديًا وإمكانية التشغيل البيني مع مكتبات معالجة البيانات الأخرى. **الصيغة** ```python chdb.state.sqlitelike.to_arrowTable(res) ``` **المعلمات:** | المعلمة | النوع | الوصف | | ------- | ----- | ------------------------------------------------------ | | `res` | - | كائن نتيجة query من chdb يحتوي على بيانات بتنسيق Arrow | **القيمة المعادة** | نوع الإرجاع | الوصف | | --------------- | ---------------------------------- | | `pyarrow.Table` | جدول PyArrow يحتوي على نتائج query | **الاستثناءات** | الاستثناء | الشرط | | ------------- | -------------------------------------------- | | `ImportError` | إذا لم تكن حزمتا pyarrow أو pandas مثبّتتَين | تتطلب هذه الدالة تثبيت كلٍّ من pyarrow وpandas. ثبّتهما باستخدام: `pip install pyarrow pandas` **تحذير** تُرجِع النتائج الفارغة جدول PyArrow فارغًا بلا schema. **أمثلة** ```pycon >>> import chdb >>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow") >>> table = to_arrowTable(result) >>> print(table.schema) num: int64 text: string >>> print(table.to_pandas()) num text 0 1 hello ``` ***
### `chdb.state.sqlitelike.to_df`
حوِّل نتيجة الاستعلام إلى Pandas DataFrame. تُحوِّل هذه الدالة نتائج استعلامات chdb إلى Pandas DataFrame عبر تحويلها أولًا إلى PyArrow Table ثم إلى DataFrame. ويوفّر ذلك إمكانات مريحة لتحليل البيانات باستخدام واجهة Pandas البرمجية. **الصيغة** ```python chdb.state.sqlitelike.to_df(r) ``` **المعلمات:** | Parameter | Type | Description | | --------- | ---- | ---------------------------------------------------------- | | `r` | - | كائن نتيجة الاستعلام من chdb يحتوي على بيانات بتنسيق Arrow | **القيمة المعادة:** | Return Type | Description | | ------------------ | -------------------------------------------------------------------------------- | | `pandas.DataFrame` | كائن DataFrame يحتوي على نتائج الاستعلام بأسماء الأعمدة وأنواع البيانات المناسبة | **الاستثناءات** | Exception | Condition | | ------------- | ------------------------------------------- | | `ImportError` | إذا لم تكن حزمتا pyarrow أو pandas مثبّتتين | تستخدم هذه الدالة المعالجة متعددة الخيوط لتحويل Arrow إلى Pandas لتحسين الأداء عند التعامل مع مجموعات البيانات الكبيرة. **انظر أيضًا** * [`to_arrowTable()`](#chdb-state-sqlitelike-to_arrowtable) - للتحويل إلى تنسيق PyArrow Table **أمثلة** ```pycon >>> import chdb >>> result = chdb.query("SELECT 1 as num, 'hello' as text", "Arrow") >>> df = to_df(result) >>> print(df) num text 0 1 hello >>> print(df.dtypes) num int64 text object dtype: object ```
## تكامل DataFrame
### **الصنف** `chdb.dataframe.Table`
الأصناف الأساسية: ```python class chdb.dataframe.Table(*args: Any, **kwargs: Any) ```
## واجهة Database API ‏(DBAPI) 2.0
يوفّر chDB واجهة متوافقة مع Python DB-API 2.0 للاتصال بقواعد البيانات، مما يتيح لك استخدام chDB مع الأدوات وأطر العمل التي تعتمد واجهات قواعد بيانات قياسية. تتضمن واجهة chDB DB-API 2.0 ما يلي: * **الاتصالات**: إدارة اتصالات قاعدة البيانات باستخدام سلاسل الاتصال * **المؤشرات**: تنفيذ الاستعلامات واسترجاع النتائج * **نظام الأنواع**: ثوابت أنواع ومحوّلات متوافقة مع DB-API 2.0 * **معالجة الأخطاء**: تسلسل هرمي قياسي لاستثناءات قواعد البيانات * **أمان الخيوط**: المستوى 1 من أمان الخيوط (يمكن للخيوط مشاركة الوحدات، لكن ليس الاتصالات) ***
### الدوال الأساسية
تتضمن واجهة Database API ‏(DBAPI) 2.0 الدوال الأساسية التالية:
#### `chdb.dbapi.connect`
أنشئ اتصالًا جديدًا بقاعدة البيانات. **الصيغة** ```python chdb.dbapi.connect(*args, **kwargs) ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------- | ----- | --------- | ------------------------------------------------------------------- | | `path` | str | `None` | مسار ملف قاعدة البيانات. تكون None لقاعدة بيانات مؤقتة غير دائمة | **الاستثناءات** | الاستثناء | الشرط | | ------------------------------------ | ---------------------- | | [`err.Error`](#chdb-dbapi-err-error) | إذا تعذر إنشاء الاتصال | ***
#### `chdb.dbapi.get_client_info()`
يسترجع معلومات إصدار العميل. يعيد إصدار عميل chDB كسلسلة نصية للتوافق مع MySQLdb. **الصيغة** ```python chdb.dbapi.get_client_info() ``` **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ----------------------------------------------- | | `str` | سلسلة الإصدار بصيغة 'major.minor.patch' | ***
### مُنشئات الأنواع
#### `chdb.dbapi.Binary(x)`
إرجاع x كنوع ثنائي. تُحوِّل هذه الدالة المُدخل إلى النوع bytes لاستخدامه مع الحقول الثنائية في قاعدة البيانات، وذلك وفقًا لمواصفة DB-API 2.0. **الصيغة** ```python chdb.dbapi.Binary(x) ``` **المعلمات** | المعلمة | النوع | الوصف | | ------- | ----- | ---------------------------------------- | | `x` | - | بيانات الإدخال المراد تحويلها إلى بايتات | **القيمة المُعادة** | نوع القيمة المُعادة | الوصف | | ------------------- | ------------------------------------- | | `bytes` | بيانات الإدخال بعد تحويلها إلى بايتات | ***
### الصنف Connection
#### **الصنف** `chdb.dbapi.connections.Connection(path=None)`
الفئات الأساسية: `object` اتصال متوافق مع DB-API 2.0 بقاعدة بيانات chDB. يوفّر هذا الصنف واجهة DB-API قياسية للاتصال بقواعد بيانات chDB والتفاعل معها. ويدعم قواعد البيانات المؤقتة وقواعد البيانات القائمة على الملفات. يدير الاتصال محرك chDB الأساسي ويوفّر أساليب لتنفيذ الاستعلامات وإدارة المعاملات (بلا تأثير في ClickHouse) وإنشاء المؤشرات. ```python class chdb.dbapi.connections.Connection(path=None) ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------- | ----- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | str | `None` | مسار ملف قاعدة البيانات. إذا كانت القيمة None (وهي الافتراضية)، تُستخدم قاعدة بيانات مؤقتة غير دائمة (تعادل `':memory:'`). مرّر مسار ملف مثل 'database.db' للاحتفاظ بالبيانات على القرص. | **المتغيرات** | المتغير | النوع | الوصف | | ---------- | ----- | -------------------------------------------------------------- | | `encoding` | str | ترميز الأحرف للاستعلامات، والقيمة الافتراضية هي 'utf8' | | `open` | bool | تكون قيمته True إذا كان الاتصال مفتوحًا، وFalse إذا كان مغلقًا | **أمثلة** ```pycon >>> # Temporary database >>> conn = Connection() >>> cursor = conn.cursor() >>> cursor.execute("SELECT 1") >>> result = cursor.fetchall() >>> conn.close() ``` ```pycon >>> # File-based database >>> conn = Connection('mydata.db') >>> with conn.cursor() as cur: ... cur.execute("CREATE TABLE users (id INT, name STRING) ENGINE = MergeTree() order by id") ... cur.execute("INSERT INTO users VALUES (1, 'Alice')") >>> conn.close() ``` ```pycon >>> # Context manager usage >>> with Connection() as cur: ... cur.execute("SELECT version()") ... version = cur.fetchone() ``` لا يدعم ClickHouse المعاملات التقليدية، لذا فإن العمليتين commit() و rollback() لا تُحدثان أي تأثير، لكنهما متاحتان للامتثال لمعيار DB-API. ***
#### `close`
أغلق اتصال قاعدة البيانات. يُغلق اتصال chDB الأساسي ويضع علامة على هذا الاتصال باعتباره مغلقًا. وأي عمليات لاحقة على هذا الاتصال ستؤدي إلى ظهور خطأ. **الصيغة** ```python close() ``` **الاستثناءات التي قد تُرفع** | الاستثناء | الحالة | | ------------------------------------ | ----------------------------- | | [`err.Error`](#chdb-dbapi-err-error) | إذا كان الاتصال مغلقًا بالفعل | ***
#### `commit`
اعتمد المعاملة الحالية. **الصيغة** ```python commit() ``` هذا الإجراء بلا تأثير في chDB/ClickHouse لأنه لا يدعم المعاملات التقليدية. وهو متاح للامتثال لمعيار DB-API 2.0. ***
#### `cursor`
أنشئ مؤشرًا جديدًا لتنفيذ الاستعلامات. **الصيغة** ```python cursor(cursor=None) ``` **المعلمات** | المعلمة | النوع | الوصف | | -------- | ----- | ------------------------- | | `cursor` | - | يُتجاهل، ويُوفَّر للتوافق | **العوائد** | نوع الإرجاع | الوصف | | ----------- | --------------------------- | | `Cursor` | كائن مؤشر جديد لهذا الاتصال | **الاستثناءات** | الاستثناء | الشرط | | ------------------------------------ | ----------------- | | [`err.Error`](#chdb-dbapi-err-error) | إذا أُغلق الاتصال | **مثال** ```pycon >>> conn = Connection() >>> cur = conn.cursor() >>> cur.execute("SELECT 1") >>> result = cur.fetchone() ``` ***
#### `escape`
أفلِت قيمة بحيث يمكن تضمينها بأمان في استعلامات SQL. **الصيغة** ```python escape(obj, mapping=None) ``` **المعاملات** | المعامل | النوع | الوصف | | --------- | ----- | ---------------------------------------------------- | | `obj` | - | القيمة المراد إفلاتها (سلسلة نصية، بايتات، رقم، إلخ) | | `mapping` | - | تعيين اختياري للمحارف لعملية الإفلات | **القيمة المعادة** | نوع الإرجاع | الوصف | | ----------- | ---------------------------------------------- | | - | نسخة مُفلَتة من المُدخل ومناسبة لاستعلامات SQL | **مثال** ```pycon >>> conn = Connection() >>> safe_value = conn.escape("O'Reilly") >>> query = f"SELECT * FROM users WHERE name = {safe_value}" ``` ***
#### `escape_string`
قم بإفلات قيمة نصية لاستعلامات SQL. **الصيغة** ```python escape_string(s) ``` **المعلمات** | المعلمة | النوع | الوصف | | ------- | ----- | ------------------------ | | `s` | str | سلسلة نصية مطلوب تهريبها | **القيمة المعادة** | نوع الإرجاع | الوصف | | ----------- | ---------------------------------------- | | `str` | سلسلة نصية مُهرَّبة وآمنة للتضمين في SQL | ***
#### `property open`
تحقّق مما إذا كان الاتصال مفتوحًا. **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ------------------------------------------------- | | `bool` | صحيح إذا كان الاتصال مفتوحًا، وخطأ إذا كان مغلقًا | ***
#### `query`
نفّذ استعلام SQL مباشرةً وأعِد النتائج الأولية. تتجاوز هذه الطريقة واجهة المؤشر وتنفّذ الاستعلامات مباشرةً. لاستخدام DB-API القياسي، يُفضَّل استخدام الطريقة cursor(). **الصيغة** ```python query(sql, fmt='CSV') ``` **المعلمات:** | المعلمة | النوع | الافتراضي | الوصف | | ------- | ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | | `sql` | str or bytes | *مطلوب* | استعلام SQL المطلوب تنفيذه | | `fmt` | str | `"CSV"` | تنسيق الإخراج. تشمل التنسيقات المدعومة "CSV" و"JSON" و"Arrow" و"Parquet" وغيرها. | **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ------------------------------- | | - | نتيجة الاستعلام بالتنسيق المحدد | **الاستثناءات** | الاستثناء | الشرط | | ------------------------------------------------------ | --------------------------------------- | | [`err.InterfaceError`](#chdb-dbapi-err-interfaceerror) | إذا كان الاتصال مغلقًا أو فشل الاستعلام | **مثال** ```pycon >>> conn = Connection() >>> result = conn.query("SELECT 1, 'hello'", "CSV") >>> print(result) "1,hello\n" ``` ***
#### `property resp`
يعرض آخر استجابة للاستعلام. **القيمة المُعادة** | نوع القيمة المُعادة | الوصف | | ------------------- | ----------------------------------------- | | - | الاستجابة الخام من آخر استدعاء لـ query() | تُحدَّث هذه الخاصية في كل مرة يُستدعى فيها query() مباشرةً. ولا تعكس الاستعلامات التي تُنفَّذ عبر المؤشرات. ***
#### `rollback`
التراجع عن المعاملة الحالية. **البنية** ```python rollback() ``` هذه عملية بلا تأثير في chDB/ClickHouse لأنه لا يدعم المعاملات التقليدية. وهي مُتاحة للامتثال لـ DB-API 2.0. ***
### فئة المؤشر
#### **فئة** `chdb.dbapi.cursors.Cursor`
يرث من: `object` مؤشر DB-API 2.0 لتنفيذ الاستعلامات وجلب النتائج. يوفّر المؤشر أساليب لتنفيذ عبارات SQL، وإدارة نتائج الاستعلام، والتنقّل عبر مجموعات النتائج. كما يدعم ربط المعلمات والعمليات المجمّعة، ويلتزم بمواصفات DB-API 2.0. لا تُنشئ مثيلات مؤشر مباشرةً. استخدم `Connection.cursor()` بدلًا من ذلك. ```python class chdb.dbapi.cursors.Cursor(connection) ``` | المتغير | النوع | الوصف | | ----------------- | ----- | ---------------------------------------------------------------- | | `description` | tuple | البيانات الوصفية لأعمدة نتيجة آخر استعلام | | `rowcount` | int | عدد الصفوف المتأثرة بآخر استعلام (-1 إذا كان غير معروف) | | `arraysize` | int | العدد الافتراضي للصفوف التي يتم جلبها دفعةً واحدة (الافتراضي: 1) | | `lastrowid` | - | معرّف آخر صف أُدرج (إن أمكن) | | `max_stmt_length` | int | الحد الأقصى لحجم التعليمة لـ executemany() (الافتراضي: 1024000) | **أمثلة** ```pycon >>> conn = Connection() >>> cur = conn.cursor() >>> cur.execute("SELECT 1 as id, 'test' as name") >>> result = cur.fetchone() >>> print(result) # (1, 'test') >>> cur.close() ``` راجع [DB-API 2.0 Cursor Objects](https://www.python.org/dev/peps/pep-0249/#cursor-objects) للاطلاع على التفاصيل الكاملة للمواصفات. ***
#### `callproc`
نفّذ إجراءً مخزّنًا (تنفيذ مبدئي). **الصيغة** ```python callproc(procname, args=()) ``` **المعلمات** | معلمة | Type | Description | | ---------- | -------- | ------------------------------------ | | `procname` | str | اسم الإجراء المخزن المطلوب تنفيذه | | `args` | sequence | المعلمات المراد تمريرها إلى الإجراء | **القيمة المعادة** | Return Type | Description | | ----------- | ------------------------------------ | | `sequence` | المعامل `args` الأصلي (من دون تعديل) | لا يدعم chDB/ClickHouse الإجراءات المخزنة بالمفهوم التقليدي. تُوفَّر هذه method للامتثال لمعيار DB-API 2.0، لكنها لا تنفّذ أي عملية فعلية. استخدم execute() لجميع عمليات SQL. **التوافق** هذا تنفيذ شكلي. لا يدعم ClickHouse engine الأساسي ميزات الإجراءات المخزنة التقليدية، مثل معاملات OUT/INOUT، ومجموعات النتائج المتعددة، ومتغيرات الخادم. ***
#### `close`
أغلِق المؤشر وحرِّر الموارد المرتبطة به. بعد إغلاقه، يصبح المؤشر غير قابل للاستخدام، وأي عملية عليه سترفع استثناءً. يؤدي إغلاق المؤشر إلى استهلاك جميع البيانات المتبقية وتحرير المؤشر الأساسي. **الصيغة** ```python close() ``` ***
#### `execute`
نفّذ استعلام SQL مع ربط اختياري للمعلمات. تُنفِّذ هذه الطريقة تعليمة SQL واحدة مع استبدال اختياري للمعلمات. وتدعم عدة أنماط لعناصر نائبة للمعلمات لمزيد من المرونة. **البنية** ```python execute(query, args=None) ``` **المعلمات** | Parameter | Type | Default | Description | | --------- | --------------- | ------- | -------------------------------------- | | `query` | str | *مطلوب* | استعلام SQL المراد تنفيذه | | `args` | tuple/list/dict | `None` | المعلمات المراد ربطها بالعناصر النائبة | **القيمة المُعادة** | Return Type | Description | | ----------- | ------------------------------------------ | | `int` | عدد الصفوف المتأثرة (-1 إذا كان غير معروف) | **أنماط المعلمات** | Style | Example | | ------------------- | --------------------------------------------- | | نمط علامة الاستفهام | `"SELECT * FROM users WHERE id = ?"` | | النمط المُسمّى | `"SELECT * FROM users WHERE name = %(name)s"` | | نمط التنسيق | `"SELECT * FROM users WHERE age = %s"` (قديم) | **أمثلة** ```pycon >>> # Question mark parameters >>> cur.execute("SELECT * FROM users WHERE id = ? AND age > ?", (123, 18)) >>> >>> # Named parameters >>> cur.execute("SELECT * FROM users WHERE name = %(name)s", {'name': 'Alice'}) >>> >>> # No parameters >>> cur.execute("SELECT COUNT(*) FROM users") ``` **الاستثناءات** | الاستثناء | الحالة | | ------------------------------------------------------ | ----------------------------------------------------- | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا كان المؤشر مغلقًا أو كانت query غير صحيحة الصياغة | | [`InterfaceError`](#chdb-dbapi-err-interfaceerror) | إذا حدث خطأ في قاعدة البيانات أثناء التنفيذ | ***
#### `executemany(query, args)`
نفِّذ استعلامًا عدة مرات باستخدام مجموعات مختلفة من المعلمات. تُنفِّذ هذه الطريقة استعلام SQL نفسه بكفاءة عدة مرات مع قيم مختلفة للمعلمات. وهي مفيدة بشكل خاص في عمليات INSERT المجمّعة. **الصيغة** ```python executemany(query, args) ``` **المعلمات** | المعلمة | النوع | الوصف | | ------- | ----- | ----------------------------------------------------------- | | `query` | str | استعلام SQL يُنفَّذ عدة مرات | | `args` | تسلسل | تسلسل من tuples/dicts/lists للمعلمات الخاصة بكل عملية تنفيذ | **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ----------------------------------------------------- | | `int` | العدد الإجمالي للصفوف المتأثرة في جميع عمليات التنفيذ | **أمثلة** ```pycon >>> # Bulk insert with question mark parameters >>> users_data = [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')] >>> cur.executemany("INSERT INTO users VALUES (?, ?)", users_data) >>> >>> # Bulk insert with named parameters >>> users_data = [ ... {'id': 1, 'name': 'Alice'}, ... {'id': 2, 'name': 'Bob'} ... ] >>> cur.executemany( ... "INSERT INTO users VALUES (%(id)s, %(name)s)", ... users_data ... ) ``` تُحسّن هذه الطريقة الأداء في عمليات INSERT وUPDATE متعددة الصفوف من خلال تحسين آلية تنفيذ الاستعلام. ***
#### `fetchall()`
استرجع جميع الصفوف المتبقية من نتيجة الاستعلام. **البنية** ```python fetchall() ``` **يعيد** | نوع القيمة المعادة | الوصف | | ------------------ | -------------------------------------------- | | `list` | قائمة من قيم Tuple تمثل جميع الصفوف المتبقية | **يثير** | الاستثناء | الشرط | | ------------------------------------------------------ | ---------------------------------- | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا لم يتم استدعاء execute() أولاً | **تحذير** قد تستهلك هذه الطريقة كميات كبيرة من الذاكرة عند التعامل مع مجموعات نتائج كبيرة. فكّر في استخدام `fetchmany()` مع مجموعات النتائج الكبيرة. **مثال** ```pycon >>> cursor.execute("SELECT id, name FROM users") >>> all_rows = cursor.fetchall() >>> print(len(all_rows)) # Number of total rows ``` ***
#### `fetchmany`
يجلب عدة صفوف من نتيجة الاستعلام. **البنية** ```python fetchmany(size=1) ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------- | ----- | --------- | ----------------------------------------------------------------------------- | | `size` | int | `1` | عدد الصفوف المراد جلبها. إذا لم يتم تحديده، فستُستخدم القيمة cursor.arraysize | **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ----------------------------------------- | | `list` | قائمة من tuples تمثل الصفوف التي تم جلبها | **الاستثناءات** | الاستثناء | الشرط | | ------------------------------------------------------ | ---------------------------------- | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا لم يتم استدعاء execute() أولًا | **مثال** ```pycon >>> cursor.execute("SELECT id, name FROM users") >>> rows = cursor.fetchmany(3) >>> print(rows) # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')] ``` ***
#### `fetchone`
يجلب الصف التالي من نتيجة الاستعلام. **الصياغة** ```python fetchone() ``` **القيم المعادة** | نوع الإرجاع | الوصف | | --------------- | -------------------------------------------------------------- | | `tuple or None` | الصف التالي على هيئة tuple، أو None إذا لم تعد هناك صفوف متاحة | **الاستثناءات** | الاستثناء | الشرط | | ------------------------------------------------------ | ------------------------------------ | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا لم يتم استدعاء `execute()` أولًا | **مثال** ```pycon >>> cursor.execute("SELECT id, name FROM users LIMIT 3") >>> row = cursor.fetchone() >>> print(row) # (1, 'Alice') >>> row = cursor.fetchone() >>> print(row) # (2, 'Bob') ``` ***
#### `max_stmt_length = 1024000`
الحد الأقصى لحجم تعليمة `statement` التي تُنشئها [`executemany()`](#chdb-dbapi-cursors-cursor-executemany). القيمة الافتراضية هي 1024000. ***
#### `mogrify`
يعيد سلسلة الاستعلام الدقيقة التي ستُرسَل إلى قاعدة البيانات. تُظهر هذه الطريقة استعلام SQL النهائي بعد استبدال المعلمات، مما يفيد في تصحيح الأخطاء والتسجيل. **الصيغة** ```python mogrify(query, args=None) ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------- | --------------- | --------- | -------------------------------------- | | `query` | str | *مطلوب* | استعلام SQL يتضمن عناصر نائبة للمعلمات | | `args` | tuple/list/dict | `None` | المعلمات المراد إحلالها | **القيم المعادة** | نوع الإرجاع | الوصف | | ----------- | -------------------------------------------------- | | `str` | سلسلة استعلام SQL النهائية بعد إحلال المعلمات فيها | **مثال** ```pycon >>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,)) "SELECT * FROM users WHERE id = 123" ``` تتبع هذه الطريقة الامتداد الخاص بـ DB-API 2.0 كما يستخدمه Psycopg. ***
#### `nextset`
انتقل إلى مجموعة النتائج التالية (غير مدعوم). **الصيغة** ```python nextset() ``` **يعيد** | نوع الإرجاع | الوصف | | ----------- | ---------------------------------------------------------- | | `None` | يعيد `None` دائمًا لأن مجموعات النتائج المتعددة غير مدعومة | لا يدعم chDB/ClickHouse إرجاع مجموعات نتائج متعددة من استعلام واحد. تُوفَّر هذه الطريقة للامتثال لـ DB-API 2.0، لكنها تعيد `None` دائمًا. ***
#### `setinputsizes`
يضبط أحجام الإدخال للمعلمات (تنفيذ شكلي لا يؤدي أي إجراء). **البنية** ```python setinputsizes(*args) ``` **المعلمات** | المعلمة | النوع | الوصف | | ------- | ----- | ---------------------------------- | | `*args` | - | مواصفات حجم المعلمات (يتم تجاهلها) | لا تقوم هذه الطريقة بأي شيء، لكنها مطلوبة وفقًا لمواصفة DB-API 2.0. يتولى chDB تلقائيًا معالجة تحديد حجم المعلمات داخليًا. ***
#### `setoutputsizes`
ضبط أحجام أعمدة الإخراج (تنفيذ شكلي بلا تأثير فعلي). **الصيغة** ```python setoutputsizes(*args) ``` **المعلمات** | المعلمة | النوع | الوصف | | ------- | ----- | -------------------------------- | | `*args` | - | مواصفات حجم العمود (يتم تجاهلها) | لا تقوم هذه الطريقة بأي شيء، لكنها مطلوبة وفقًا لمواصفة DB-API 2.0. يتولى chDB تلقائيًا معالجة تحديد حجم المخرجات داخليًا. ***
### فئات الأخطاء
فئات الاستثناءات لعمليات قاعدة البيانات في chdb. توفّر هذه الوحدة تسلسلاً هرمياً كاملاً لفئات الاستثناءات للتعامل مع الأخطاء المرتبطة بقاعدة البيانات في chdb، وذلك وفقاً لمواصفة Python Database API الإصدار 2.0. يأتي التسلسل الهرمي للاستثناءات على النحو التالي: ```default StandardError ├── Warning └── Error ├── InterfaceError └── DatabaseError ├── DataError ├── OperationalError ├── IntegrityError ├── InternalError ├── ProgrammingError └── NotSupportedError ``` تمثل كل فئة من فئات الاستثناء فئةً محددة من أخطاء قاعدة البيانات: | Exception | Description | | ------------------- | ------------------------------------------------------ | | `Warning` | تحذيرات غير خطيرة أثناء عمليات قاعدة البيانات | | `InterfaceError` | مشكلات في واجهة قاعدة البيانات نفسها | | `DatabaseError` | الفئة الأساسية لجميع الأخطاء المرتبطة بقاعدة البيانات | | `DataError` | مشكلات في معالجة البيانات (قيم غير صالحة، أخطاء أنواع) | | `OperationalError` | مشكلات تشغيلية في قاعدة البيانات (الاتصال، الموارد) | | `IntegrityError` | انتهاكات للقيود (المفاتيح الخارجية، التفرّد) | | `InternalError` | أخطاء داخلية في قاعدة البيانات أو تلف فيها | | `ProgrammingError` | أخطاء في بنية SQL وسوء استخدام واجهة API | | `NotSupportedError` | ميزات أو عمليات غير مدعومة | تتوافق فئات الاستثناء هذه مع مواصفة Python DB API 2.0، وتوفّر معالجة متسقة للأخطاء عبر مختلف عمليات قاعدة البيانات. **راجع أيضًا** * [مواصفة Python Database API الإصدار 2.0](https://peps.python.org/pep-0249/) * `chdb.dbapi.connections` - إدارة اتصالات قاعدة البيانات * `chdb.dbapi.cursors` - عمليات مؤشرات قاعدة البيانات **أمثلة** ```pycon >>> try: ... cursor.execute("SELECT * FROM nonexistent_table") ... except ProgrammingError as e: ... print(f"SQL Error: {e}") ... SQL Error: Table 'nonexistent_table' doesn't exist ``` ```pycon >>> try: ... cursor.execute("INSERT INTO users (id) VALUES (1), (1)") ... except IntegrityError as e: ... print(f"Constraint violation: {e}") ... Constraint violation: Duplicate entry '1' for key 'PRIMARY' ``` ***
#### **الاستثناء** `chdb.dbapi.err.DataError`
يرث من: [`DatabaseError`](#chdb-dbapi-err-databaseerror) يُرفَع هذا الاستثناء عند حدوث أخطاء ناتجة عن مشكلات في البيانات التي تجري معالجتها. يُرفَع هذا الاستثناء عندما تفشل عمليات قاعدة البيانات بسبب مشكلات في البيانات قيد المعالجة، مثل: * عمليات القسمة على صفر * قيم رقمية خارج النطاق * قيم تاريخ/وقت غير صالحة * أخطاء اقتطاع السلاسل النصية * فشل تحويل الأنواع * تنسيق بيانات غير صالح لنوع العمود **الاستثناءات المُثارة** | الاستثناء | الحالة | | ---------------------------------------- | ------------------------------------------ | | [`DataError`](#chdb-dbapi-err-dataerror) | عند فشل التحقق من صحة البيانات أو معالجتها | **أمثلة** ```pycon >>> # Division by zero in SQL >>> cursor.execute("SELECT 1/0") DataError: Division by zero ``` ```pycon >>> # Invalid date format >>> cursor.execute("INSERT INTO table VALUES ('invalid-date')") DataError: Invalid date format ``` ***
#### **استثناء** `chdb.dbapi.err.DatabaseError`
الفئات الأساسية: [`Error`](#chdb-dbapi-err-error) استثناء يُرفَع عند حدوث أخطاء مرتبطة بقاعدة البيانات. هذه هي الفئة الأساسية لجميع الأخطاء المتعلقة بقاعدة البيانات. وهي تشمل كل الأخطاء التي تحدث أثناء عمليات قاعدة البيانات وترتبط بقاعدة البيانات نفسها لا بالواجهة. تشمل الحالات الشائعة ما يلي: * أخطاء تنفيذ SQL * مشكلات الاتصال بقاعدة البيانات * مشكلات متعلقة بالمعاملات * انتهاكات القيود الخاصة بقاعدة البيانات تُعد هذه الفئة الأساسية لأنواع أخطاء قاعدة البيانات الأكثر تحديدًا، مثل [`DataError`](#chdb-dbapi-err-dataerror) و[`OperationalError`](#chdb-dbapi-err-operationalerror) وغيرها. ***
#### **استثناء** `chdb.dbapi.err.Error`
الفئات الأساسية: [`StandardError`](#chdb-dbapi-err-standarderror) استثناء يُعد الفئة الأساسية لجميع استثناءات الأخطاء الأخرى (وليس `Warning`). هذه هي الفئة الأساسية لجميع استثناءات الأخطاء في chdb، باستثناء التحذيرات. وهي تمثل الفئة الأم لجميع حالات أخطاء قاعدة البيانات التي تمنع إكمال العمليات بنجاح. يتبع هذا التسلسل الهرمي للاستثناءات مواصفة Python DB API 2.0. **انظر أيضًا** * [`Warning`](#chdb-dbapi-err-warning) - للتحذيرات غير الجسيمة التي لا تمنع اكتمال العملية
#### **الاستثناء** `chdb.dbapi.err.IntegrityError`
الفئات الأساسية: [`DatabaseError`](#chdb-dbapi-err-databaseerror) يُثار هذا الاستثناء عندما تتأثر السلامة العلائقية لقاعدة البيانات. ويُثار عند انتهاك عمليات قاعدة البيانات لقيود السلامة، بما في ذلك: * انتهاك قيد المفتاح الخارجي * انتهاك المفتاح الأساسي أو القيد الفريد (مفاتيح مكررة) * انتهاك قيد التحقق * انتهاك قيد `NOT NULL` * انتهاك السلامة المرجعية **يُثير** | الاستثناء | الشرط | | -------------------------------------------------- | ------------------------------------ | | [`IntegrityError`](#chdb-dbapi-err-integrityerror) | عند انتهاك قيود سلامة قاعدة البيانات | **أمثلة** ```pycon >>> # Duplicate primary key >>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')") >>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')") IntegrityError: Duplicate entry '1' for key 'PRIMARY' ``` ```pycon >>> # Foreign key violation >>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)") IntegrityError: Cannot add or update a child row: foreign key constraint fails ``` ***
#### **استثناء** `chdb.dbapi.err.InterfaceError`
الفئات الأساسية: [`Error`](#chdb-dbapi-err-error) يُثار هذا الاستثناء عند حدوث أخطاء تتعلق بواجهة قاعدة البيانات، لا بقاعدة البيانات نفسها. يُثار هذا الاستثناء عند وجود مشكلات في تنفيذ واجهة قاعدة البيانات، مثل: * معلمات اتصال غير صالحة * إساءة استخدام API (استدعاء الأساليب على اتصالات مغلقة) * أخطاء بروتوكول على مستوى الواجهة * فشل استيراد الوحدة أو تهيئتها **يُثير** | الاستثناء | الحالة | | -------------------------------------------------- | ---------------------------------------------------------------------- | | [`InterfaceError`](#chdb-dbapi-err-interfaceerror) | عندما تواجه واجهة قاعدة البيانات أخطاء لا تتعلق بعمليات قاعدة البيانات | تكون هذه الأخطاء عادةً أخطاء برمجية أو مشكلات في التهيئة، ويمكن حلها من خلال إصلاح كود العميل أو التهيئة. ***
#### **الاستثناء** `chdb.dbapi.err.InternalError`
الفئات الأساسية: [`DatabaseError`](#chdb-dbapi-err-databaseerror) يُرفَع هذا الاستثناء عندما تواجه قاعدة البيانات خطأً داخليًا. يُرفَع هذا الاستثناء عندما يواجه نظام قاعدة البيانات أخطاءً داخلية لا يتسبب بها التطبيق، مثل: * حالة مؤشر غير صالحة (لم يعد المؤشر صالحًا) * حالات عدم اتساق في حالة المعاملة (المعاملة غير متزامنة) * مشكلات تلف في قاعدة البيانات * تلف في بنية البيانات الداخلية * أخطاء قاعدة بيانات على مستوى النظام **يرفع** | الاستثناء | الحالة | | ------------------------------------------------ | ------------------------------------------------- | | [`InternalError`](#chdb-dbapi-err-internalerror) | عندما تواجه قاعدة البيانات حالات عدم اتساق داخلية | **تحذير** قد تشير الأخطاء الداخلية إلى مشكلات خطيرة في قاعدة البيانات تتطلب انتباه مسؤول قاعدة البيانات. ولا يمكن عادةً معالجة هذه الأخطاء من خلال منطق إعادة المحاولة على مستوى التطبيق. تكون هذه الأخطاء عمومًا خارج نطاق تحكم التطبيق، وقد تتطلب إعادة تشغيل قاعدة البيانات أو تنفيذ عمليات إصلاح. ***
#### **استثناء** `chdb.dbapi.err.NotSupportedError`
الفئات الأساسية: [`DatabaseError`](#chdb-dbapi-err-databaseerror) يُرفع هذا الاستثناء عندما لا تكون إحدى الطرق أو Database API مدعومة. يُرفع هذا الاستثناء عندما يحاول التطبيق استخدام ميزات في قاعدة البيانات أو طرق API لا تدعمها تهيئة قاعدة البيانات الحالية أو إصدارها الحالي، مثل: * طلب `rollback()` على الاتصالات التي لا تدعم المعاملات * استخدام ميزات SQL متقدمة لا يدعمها إصدار قاعدة البيانات * استدعاء طرق غير مُنفّذة في برنامج التشغيل الحالي * محاولة استخدام ميزات معطّلة في قاعدة البيانات **الاستثناءات** | Exception | Condition | | -------------------------------------------------------- | ------------------------------------------------- | | [`NotSupportedError`](#chdb-dbapi-err-notsupportederror) | عند الوصول إلى ميزات غير مدعومة في قاعدة البيانات | **أمثلة** ```pycon >>> # Transaction rollback on non-transactional connection >>> connection.rollback() NotSupportedError: Transactions are not supported ``` ```pycon >>> # Using unsupported SQL syntax >>> cursor.execute("SELECT * FROM table WITH (NOLOCK)") NotSupportedError: WITH clause not supported in this database version ``` راجع وثائق قاعدة البيانات وإمكانات المشغّل لتجنّب هذه الأخطاء. وفكّر في اعتماد آليات احتياطية بديلة بسلاسة متى أمكن. ***
#### **استثناء** `chdb.dbapi.err.OperationalError`
الفئات الأساسية: [`DatabaseError`](#chdb-dbapi-err-databaseerror) استثناء يُرفَع عند وقوع أخطاء مرتبطة بتشغيل قاعدة البيانات. يُرفَع هذا الاستثناء عند حدوث أخطاء أثناء تشغيل قاعدة البيانات ولا تكون بالضرورة ضمن سيطرة المبرمج، بما في ذلك: * انقطاع الاتصال بقاعدة البيانات بشكل غير متوقع * تعذّر العثور على خادم قاعدة البيانات أو تعذّر الوصول إليه * حالات فشل معالجة المعاملات * أخطاء تخصيص الذاكرة أثناء المعالجة * نفاد مساحة القرص أو الموارد * أخطاء داخلية في خادم قاعدة البيانات * إخفاقات المصادقة أو التفويض **يُثير** | Exception | Condition | | ------------------------------------------------------ | ------------------------------------------------- | | [`OperationalError`](#chdb-dbapi-err-operationalerror) | عند فشل عمليات قاعدة البيانات بسبب مشكلات تشغيلية | تكون هذه الأخطاء عادةً مؤقتة، وقد تُحل بإعادة محاولة تنفيذ العملية أو بمعالجة المشكلات على مستوى النظام. **تحذير** قد تشير بعض الأخطاء التشغيلية إلى مشكلات خطيرة في النظام تتطلب تدخّلًا إداريًا. ***
#### **استثناء** `chdb.dbapi.err.ProgrammingError`
الفئات الأساسية: [`DatabaseError`](#chdb-dbapi-err-databaseerror) يُرفَع هذا الاستثناء عند حدوث أخطاء برمجية في عمليات قاعدة البيانات. يُرفَع هذا الاستثناء عندما تكون هناك أخطاء برمجية في استخدام التطبيق لقاعدة البيانات، بما في ذلك: * تعذّر العثور على جدول أو عمود * وجود الجدول أو الفهرس مسبقًا عند الإنشاء * أخطاء في بناء جملة SQL في التعليمات * تحديد عدد غير صحيح من المعلمات في التعليمات المُحضّرة * عمليات SQL غير صالحة (مثل `DROP` على كائنات غير موجودة) * استخدام غير صحيح لأساليب واجهة برمجة تطبيقات قواعد البيانات **يُثير** | الاستثناء | الشرط | | ------------------------------------------------------ | ------------------------------------------- | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | عندما تتضمن عبارات SQL أو استخدام API أخطاء | **أمثلة** ```pycon >>> # Table not found >>> cursor.execute("SELECT * FROM nonexistent_table") ProgrammingError: Table 'nonexistent_table' doesn't exist ``` ```pycon >>> # SQL syntax error >>> cursor.execute("SELCT * FROM users") ProgrammingError: You have an error in your SQL syntax ``` ```pycon >>> # Wrong parameter count >>> cursor.execute("INSERT INTO users (name, age) VALUES (%s)", ('John',)) ProgrammingError: Column count doesn't match value count ``` ***
#### **الاستثناء** `chdb.dbapi.err.StandardError`
الفئات الأساسية: `Exception` استثناء مرتبط بالعمليات التي تُجرى باستخدام chdb. هذه هي الفئة الأساسية لجميع الاستثناءات المرتبطة بـ chdb. وهي ترث من فئة Exception المضمنة في Python وتمثل الجذر في التسلسل الهرمي لاستثناءات عمليات قاعدة البيانات. تتبع فئة الاستثناء هذه مواصفة Python DB API 2.0 لمعالجة استثناءات قاعدة البيانات. ***
#### **الاستثناء** `chdb.dbapi.err.Warning`
الفئات الأساسية: [`StandardError`](#chdb-dbapi-err-standarderror) استثناء يُثار عند حدوث تحذيرات مهمة، مثل اقتطاع البيانات أثناء الإدراج، وما إلى ذلك. يُثار هذا الاستثناء عندما تكتمل العملية على قاعدة البيانات، ولكن مع تحذيرات مهمة ينبغي تنبيه التطبيق إليها. وتشمل السيناريوهات الشائعة ما يلي: * اقتطاع البيانات أثناء الإدراج * فقدان الدقة في التحويلات الرقمية * تحذيرات تحويل ترميز الأحرف يتوافق هذا مع مواصفة Python DB API 2.0 الخاصة باستثناءات التحذير. ***
### ثوابت الوحدة النمطية
#### `chdb.dbapi.apilevel = '2.0'`
```python str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str ``` أنشئ كائن سلسلة نصية جديدًا من الكائن المُعطى. إذا جرى تحديد encoding أو errors، فيجب أن يوفّر الكائن مخزنًا مؤقتًا للبيانات سيُفك ترميزه باستخدام encoding المحدد ومعالج الأخطاء. وبخلاف ذلك، يُرجِع ناتج `object._\_str_\_()` (إذا كان معرّفًا) أو `repr(object)`. * القيمة الافتراضية لـ encoding هي ‘utf-8’. * القيمة الافتراضية لـ errors هي ‘strict’. ***
#### `chdb.dbapi.threadsafety = 1`
```python int([x]) -> integer int(x, base=10) -> integer ``` حوِّل رقمًا أو سلسلة نصية إلى عدد صحيح، أو أعد 0 إذا لم تُمرَّر أي argument. إذا كان x رقمًا، فأعد x.*_int*_(). بالنسبة إلى الأعداد ذات الفاصلة العائمة، يُقتطع الجزء الكسري باتجاه الصفر. إذا لم يكن x رقمًا أو إذا أُعطيت base، فيجب أن يكون x سلسلة نصية، أو bytes، أو instance من bytearray يمثّل عددًا صحيحًا مكتوبًا بالأساس المحدد. يمكن أن تسبق هذه الصيغة العلامة ‘+’ أو ‘-’، وأن تُحاط بمسافات بيضاء. تكون القيمة الافتراضية لـ base هي 10. الأسس الصالحة هي 0 و2-36. ويعني الأساس 0 أن يُستدل على الأساس من السلسلة نفسها باعتبارها عددًا صحيحًا مكتوبًا. ```python >>> int(‘0b100’, base=0) 4 ``` ***
#### `chdb.dbapi.paramstyle = 'format'`
```python str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str ``` أنشئ كائنًا نصيًا جديدًا من الكائن المعطى. إذا تم تحديد encoding أو errors، فيجب أن يوفّر الكائن مخزنًا مؤقتًا للبيانات يُفك ترميزه باستخدام الترميز المحدد ومعالج الأخطاء المحدد. وإلا، فستُعاد نتيجة object.*_str*_() (إن كانت معرّفة) أو repr(object). القيمة الافتراضية لـ encoding هي ‘utf-8’. القيمة الافتراضية لـ errors هي ‘strict’. ***
### ثوابت الأنواع
#### `chdb.dbapi.STRING = frozenset({247, 253, 254})`
`frozenset موسع` لمقارنة الأنواع في DB-API 2.0. يوسّع هذا الصنف `frozenset` لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح تحقّقًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون `field_type` قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` ***
#### `chdb.dbapi.BINARY = frozenset({249, 250, 251, 252})`
frozenset موسع لمقارنة الأنواع وفقًا لـ DB-API 2.0. يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح التحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وما إلى ذلك لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` ***
#### `chdb.dbapi.NUMBER = frozenset({0, 1, 3, 4, 5, 8, 9, 13})`
`frozenset موسع` لمقارنة الأنواع في DB-API 2.0. يوسّع هذا الصنف `frozenset` لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح إجراء تحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون `field_type` قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` ***
#### `chdb.dbapi.DATE = frozenset({10, 14})`
`frozenset موسع` لمقارنة الأنواع في DB-API 2.0. توسّع هذه الفئة `frozenset` لدعم دلالات مقارنة الأنواع في DB-API 2.0. وتتيح تحقّقًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون `field_type` قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` ***
#### `chdb.dbapi.TIME = frozenset({11})`
frozenset موسّعة لمقارنة الأنواع في DB-API 2.0. يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح تحققًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر المفردة بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` ***
#### `chdb.dbapi.TIMESTAMP = frozenset({7, 12})`
frozenset موسّعة لمقارنة الأنواع في DB-API 2.0. يوسّع هذا الصنف frozenset لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح تحقّقًا مرنًا من الأنواع، بحيث يمكن مقارنة العناصر الفردية بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ```
#### `chdb.dbapi.DATETIME = frozenset({7, 12})`
`frozenset` موسَّعة لمقارنة الأنواع وفق DB-API 2.0. يوسِّع هذا الصنف `frozenset` لدعم دلالات مقارنة الأنواع في DB-API 2.0. ويتيح التحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر المفردة بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون field_type قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` ***
#### `chdb.dbapi.ROWID = frozenset({})`
`frozenset موسع` لمقارنة الأنواع في DB-API 2.0. توسّع هذه الفئة `frozenset` لدعم دلالات مقارنة الأنواع في DB-API 2.0. وتتيح إجراء تحقق من الأنواع بمرونة، بحيث يمكن مقارنة العناصر المفردة بالمجموعة باستخدام معاملي المساواة وعدم المساواة. يُستخدم هذا مع ثوابت الأنواع مثل STRING وBINARY وNUMBER وغيرها لتمكين مقارنات مثل “field_type == STRING”، حيث تكون `field_type` قيمة نوع واحدة. **أمثلة** ```pycon >>> string_types = DBAPISet([FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING]) >>> FIELD_TYPE.STRING == string_types # Returns True >>> FIELD_TYPE.INT != string_types # Returns True >>> FIELD_TYPE.BLOB in string_types # Returns False ``` **أمثلة الاستخدام** مثال لاستعلام أساسي: ```python import chdb.dbapi as dbapi print("chdb driver version: {0}".format(dbapi.get_client_info())) # Create connection and cursor conn = dbapi.connect() cur = conn.cursor() # Execute query cur.execute('SELECT version()') print("description:", cur.description) print("data:", cur.fetchone()) # Clean up cur.close() conn.close() ``` التعامل مع البيانات: ```python import chdb.dbapi as dbapi conn = dbapi.connect() cur = conn.cursor() # Create table cur.execute(""" CREATE TABLE employees ( id UInt32, name String, department String, salary Decimal(10,2) ) ENGINE = Memory """) # Insert data cur.execute(""" INSERT INTO employees VALUES (1, 'Alice', 'Engineering', 75000.00), (2, 'Bob', 'Marketing', 65000.00), (3, 'Charlie', 'Engineering', 80000.00) """) # Query data cur.execute("SELECT * FROM employees WHERE department = 'Engineering'") # Fetch results print("Column names:", [desc[0] for desc in cur.description]) for row in cur.fetchall(): print(row) conn.close() ``` إدارة الاتصالات: ```python import chdb.dbapi as dbapi # Temporary database (default) conn1 = dbapi.connect() # Persistent database file conn2 = dbapi.connect("./my_database.chdb") # Connection with parameters conn3 = dbapi.connect("./my_database.chdb?log-level=debug&verbose") # Read-only connection conn4 = dbapi.connect("./my_database.chdb?mode=ro") # Automatic connection cleanup with dbapi.connect("test.chdb") as conn: cur = conn.cursor() cur.execute("SELECT count() FROM numbers(1000)") result = cur.fetchone() print(f"Count: {result[0]}") cur.close() ``` **أفضل الممارسات** 1. **إدارة الاتصال**: أغلق دائمًا الاتصالات والمؤشرات عند الانتهاء 2. **مديرو السياق**: استخدم تعليمات `with` للتنظيف التلقائي 3. **المعالجة على دفعات**: استخدم `fetchmany()` مع مجموعات النتائج الكبيرة 4. **معالجة الأخطاء**: ضمّن عمليات قاعدة البيانات داخل كتل try-except 5. **ربط المعلمات**: استخدم الاستعلامات المُعلَّمة بالمعلمات متى أمكن 6. **إدارة الذاكرة**: تجنب `fetchall()` مع مجموعات البيانات الكبيرة جدًا * واجهة DB-API 2.0 في chDB متوافقة مع معظم أدوات قواعد بيانات بايثون * توفّر الواجهة أمان خيوط من المستوى 1 (يمكن لخيوط التنفيذ مشاركة الوحدات، ولكن ليس الاتصالات) * تدعم سلاسل الاتصال نفس المعلمات التي تدعمها جلسات chDB * جميع استثناءات DB-API 2.0 القياسية مدعومة **تحذير** * أغلق دائمًا المؤشرات والاتصالات لتجنب تسرّب الموارد * ينبغي معالجة مجموعات النتائج الكبيرة على دفعات * تتبع صياغة ربط المعلمات نمط format: `%s`
## الدوال التي يعرّفها المستخدم في بايثون (UDF)
يدعم chDB دوال UDF أصلية في بايثون تعمل ضمن العملية، مع وسائط محددة الأنواع، واستنتاج تلقائي للأنواع، ومعالجة قابلة للتهيئة لقيم NULL والتعامل مع الاستثناءات. يمكن استدعاء دوال بايثون المسجّلة كدوال UDF مباشرةً من استعلامات SQL. تستخدم الأمثلة أدناه تنسيق إخراج CSV الافتراضي. توضح التعليقات المضمنة قيم النتائج المنطقية؛ بينما يطبع الإخراج الخام `NULL` بالشكل `\N` ويطبّق اقتباس CSV على قيم السلاسل النصية والتواريخ.
### `chdb.create_function`
سجّل دالة بايثون كدالة SQL في chDB. **بنية** ```python chdb.create_function(name, func, arg_types=None, return_type=None, *, on_null=None, on_error=None) ``` **المعلمات** | المعلَمة | النوع | القيمة الافتراضية | الوصف | | ------------- | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | `name` | str | *(مطلوب)* | اسم دالة SQL المراد تسجيلها | | `func` | callable | *(مطلوب)* | دالة بايثون المراد تسجيلها | | `arg_types` | list of ChdbType/str/type, or None | `None` | قائمة بأنواع الوسيطات. إذا كانت `None`، تُستنتج من تعليقات الأنواع | | `return_type` | ChdbType/str/type, or None | `None` | نوع الإرجاع. إذا كانت `None`، يُستنتج من تعليق نوع الإرجاع للدالة؛ ويفشل التسجيل إذا كان هذا التعليق مفقودًا أيضًا | | `on_null` | str or NullHandling | `None` (تخطي) | كيفية التعامل مع مدخلات NULL: `"skip"` أو `"pass"`. للوسيطات المُسمّاة فقط | | `on_error` | str or ExceptionHandling | `None` (تمرير) | كيفية التعامل مع الاستثناءات: `"propagate"` أو `"ignore"`. للوسيطات المُسمّاة فقط | يقبل كل مَعْلَم نوع (عناصر `arg_types` و`return_type`) ما يلي: * ثابت `ChdbType`: ‏`INT64`، ‏`STRING`، ‏`FLOAT64`، إلخ. * سلسلة نوع ClickHouse: ‏`"Int64"`، ‏`"String"`، ‏`"DateTime64(6)"`، ‏`"DateTime('UTC')"`، إلخ. * نوع بايثون: ‏`int`، ‏`float`، ‏`str`، ‏`bool`، ‏`bytes`، ‏`datetime.date`، ‏`datetime.datetime` — يُعيَّن وفق [تعيين الأنواع التلقائي](#udf-automatic-type-mapping) يؤدي تسجيل اسم مسجّل مسبقًا إلى ظهور خطأ — لا تُستبدل UDFs تلقائيًا. استدعِ [`drop_function`](#drop-function) أولًا لإعادة تسجيل دالة. **مثال** ```python from chdb import create_function, drop_function, query from chdb.sqltypes import INT64, STRING create_function("strlen", len, arg_types=[STRING], return_type=INT64) print(query("SELECT strlen('hello')")) # 5 drop_function("strlen") ``` ***
### `chdb.drop_function`
أزِل دالة UDF مسجَّلة سابقًا بلغة بايثون. لا يحدث شيء إذا لم تكن الدالة مسجَّلة، لذا يمكن استدعاؤها بأمان دون شرط. **البنية** ```python chdb.drop_function(name) ``` **المعلمات** | المعلَمة | النوع | الوصف | | -------- | ----- | -------------------------- | | `name` | str | اسم دالة SQL المطلوب حذفها | ***
### المُزيّن `@func`
مُزيّن لتسجيل دالة بايثون كدالة SQL في chDB. تظل الدالة قابلة للاستدعاء كدالة بايثون عادية، وتصبح متاحة في الوقت نفسه ضمن استعلامات SQL باسمها `__name__`. **البنية** ```python from chdb import func @func(arg_types=None, return_type=None, *, on_null=None, on_error=None) def my_function(...): ... ``` **المَعلمات** كما في [`create_function`](#create-function)، باستثناء `name` و`func`، إذ يُستمدّان من الدالة المُزيَّنة. **أمثلة** ```python from chdb import func, query from chdb.sqltypes import INT64, STRING # Explicit types @func([INT64, INT64], INT64) def add(a, b): return a + b # Types inferred from annotations @func() def multiply(a: int, b: int) -> int: return a * b # Explicit return_type, arg_types inferred from annotations @func(return_type=STRING) def greet(name: str): return f"Hello, {name}!" print(query("SELECT add(12, 22)")) # 34 print(query("SELECT multiply(3, 7)")) # 21 print(query("SELECT greet('world')")) # Hello, world! ``` ***
### نظام الأنواع
#### الأنواع المتاحة
استورد الأنواع من `chdb.sqltypes`: ```python from chdb.sqltypes import ( BOOL, INT8, INT16, INT32, INT64, INT128, INT256, UINT8, UINT16, UINT32, UINT64, UINT128, UINT256, FLOAT32, FLOAT64, STRING, DATE, DATE32, DATETIME, DATETIME64, ) ```
#### تعيين الأنواع تلقائيًا
عند استنتاج الأنواع من التعليقات التوضيحية في بايثون، يُستخدم التعيين التالي: | نوع بايثون | نوع ClickHouse | | ------------------- | --------------- | | `bool` | `Bool` | | `int` | `Int64` | | `float` | `Float64` | | `str` | `String` | | `bytes` | `String` | | `bytearray` | `String` | | `datetime.date` | `Date` | | `datetime.datetime` | `DateTime64(6)` |
#### طرق تحديد الأنواع
يمكن تحديد الأنواع بعدة طرق: ```python from chdb import create_function, func from chdb.sqltypes import INT64 # 1. ChdbType constants create_function("f1", lambda x: x, arg_types=[INT64], return_type=INT64) # 2. ClickHouse type strings create_function("f2", lambda x: x, arg_types=["Int64"], return_type="Int64") # 3. Parameterized type strings create_function("f3", lambda x: x, arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')") # 4. Python types — passed directly or used as annotations create_function("f4", lambda x: x, arg_types=[int], return_type=int) @func() def f5(x: int) -> int: return x ``` ***
### التعامل مع NULL
تحكّم في كيفية التعامل مع قيم NULL باستخدام parameter `on_null`. | القيمة | enum | السلوك | | -------- | ------------------- | ----------------------------------------- | | `"skip"` | `NullHandling.SKIP` | إرجاع NULL دون استدعاء الدالة (افتراضيًا) | | `"pass"` | `NullHandling.PASS` | تحويل NULL إلى `None` ثم استدعاء الدالة | ```python from chdb import func, query, NullHandling # Default: NULL in → NULL out, function not called @func(return_type="Int64") def add_one(x: int) -> int: return x + 1 print(query("SELECT add_one(NULL)")) # NULL # Pass NULL as None @func(return_type="Int64", on_null="pass") def null_safe(x): return 0 if x is None else x + 1 print(query("SELECT null_safe(NULL)")) # 0 ``` ***
### التعامل مع الاستثناءات
تحكّم في كيفية التعامل مع الاستثناءات باستخدام المعلمة `on_error`. | القيمة | التعداد | السلوك | | ------------- | ----------------------------- | ----------------------------------- | | `"propagate"` | `ExceptionHandling.PROPAGATE` | ارفع الاستثناء كخطأ SQL (افتراضيًا) | | `"ignore"` | `ExceptionHandling.IGNORE` | التقط الاستثناء وأعد NULL | ```python from chdb import func, query # Default: exception propagates @func(arg_types=["Int64", "Int64"], return_type="Int64") def divide(a, b): return a // b # print(query("SELECT divide(1, 0)")) # Error: division by zero # Ignore: exception → NULL @func(arg_types=["Int64", "Int64"], return_type="Int64", on_error="ignore") def safe_divide(a, b): return a // b print(query("SELECT safe_divide(1, 0)")) # NULL print(query("SELECT safe_divide(10, 2)")) # 5 ``` ***
### دعم DateTime والمناطق الزمنية
تدعم UDFs دعمًا كاملًا الأنواع `Date` و`Date32` و`DateTime` و`DateTime64` مع مراعاة المناطق الزمنية. ```python from chdb import func, query from datetime import datetime, timedelta, date @func(arg_types=["DateTime('UTC')"], return_type="DateTime('UTC')") def add_one_hour(dt): return dt + timedelta(hours=1) @func() def get_year(d: date) -> int: return d.year print(query("SELECT add_one_hour(toDateTime('2024-01-01 12:00:00', 'UTC'))")) # 2024-01-01 13:00:00 print(query("SELECT get_year(toDate('2024-06-15'))")) # 2024 ``` * تُحوَّل قيم `DateTime`/`DateTime64` المُدخلة إلى ClickHouse إلى كائنات `datetime` في بايثون مزودة بمعلومات timezone * تحتفظ كائنات `datetime` في بايثون بمعلومات timezone عند إعادتها إلى ClickHouse * يستخدم النوع `DATETIME64` من `chdb.sqltypes` scale افتراضيًا قدره 6 (ميكروثوانٍ)، وهو ما يعادل `DateTime64(6)` ***
### واجهة برمجة التطبيقات القديمة
**مهمل:** يُعدّ المزيّن `@chdb_udf` آلية UDF القديمة المعتمدة على العمليات الفرعية؛ إذ تشغّل دالتك في عملية بايثون منفصلة وتمرّر جميع الوسائط كسلاسل نصية. لا تزال متاحة، لكن يُوصى باستخدام واجهة برمجة تطبيقات UDF الأصلية في بايثون ([`@func`](#func-decorator) / [`create_function`](#create-function)) — إذ تعمل UDFs الأصلية ضمن العملية نفسها مع وسائط ذات أنواع محددة، ومعالجة NULL، والتحكم في الاستثناءات. راجع [دليل UDF لبايثون](/ar/chdb/guides/python-udf) للاطلاع على شرح شامل.
#### `chdb.udf.chdb_udf`
مُزيِّن لدوال بايثون من نوع UDF (دالة معرّفة من المستخدم) في chDB. **البنية** ```python chdb.udf.chdb_udf(return_type='String') ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------------- | ----- | ---------- | --------------------------------------------------------- | | `return_type` | str | `"String"` | نوع إرجاع الدالة. يجب أن يكون أحد أنواع بيانات ClickHouse | **ملاحظات** 1. يجب أن تكون الدالة عديمة الحالة. يتم دعم UDFs فقط، وليس UDAFs. 2. نوع الإرجاع الافتراضي هو String. ويجب أن يكون نوع الإرجاع أحد أنواع بيانات ClickHouse. 3. يجب أن تستقبل الدالة وسيطات من النوع String. جميع الوسيطات سلاسل نصية. 4. سيتم استدعاء الدالة لكل سطر من الإدخال. 5. يجب أن تكون الدالة مكتوبة باستخدام pure بايثون. استورد جميع الوحدات المستخدمة داخل الدالة. 6. مُفسِّر بايثون المستخدم هو نفسه المستخدم لتشغيل البرنامج النصي. **مثال** ```python @chdb_udf() def sum_udf(lhs, rhs): return int(lhs) + int(rhs) @chdb_udf() def func_use_json(arg): import json # ... use json module ``` ***
#### `chdb.udf.generate_udf`
إنشاء ملفات تهيئة UDF وملفات البرامج النصية التنفيذية. تنشئ هذه الدالة الملفات اللازمة لدالة معرّفة من قبل المستخدم (UDF) في chDB: 1. برنامجًا نصيًا تنفيذيًا بلغة بايثون لمعالجة بيانات الإدخال 2. ملف تهيئة XML لتسجيل UDF في ClickHouse **بنية** ```python chdb.udf.generate_udf(func_name, args, return_type, udf_body) ``` **المعاملات** | Parameter | Type | Description | | ------------- | ---- | ------------------------------------- | | `func_name` | str | اسم دالة UDF | | `args` | list | قائمة بأسماء الوسائط الخاصة بالدالة | | `return_type` | str | نوع الإرجاع في ClickHouse لهذه الدالة | | `udf_body` | str | متن Source Code بلغة بايثون لدالة UDF | تُستدعى هذه الدالة عادةً عبر المُزيِّن @chdb_udf، ولا ينبغي للمستخدمين استدعاؤها مباشرةً. ***
## الأدوات المساعدة
الدوال والأدوات المساعدة لـ chDB. تتضمن هذه الوحدة مجموعة متنوعة من الدوال المساعدة للعمل مع chDB، بما في ذلك استنتاج أنواع البيانات، وأدوات تحويل البيانات، وأدوات تصحيح الأخطاء. ***
### `chdb.utils.convert_to_columnar`
يحوّل قائمة من القواميس إلى تنسيق عمودي. تأخذ هذه الدالة قائمة من القواميس وتحوّلها إلى قاموس حيث يقابل كل مفتاح عمودًا، وتمثل كل قيمة قائمةً من قيم الأعمدة. تُمثَّل القيم المفقودة في القواميس على أنها None. **البنية** ```python chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]] ``` **المعلمات** | المعلمة | النوع | الوصف | | ------- | ---------------------- | -------------------------------- | | `items` | `List[Dict[str, Any]]` | قائمة من القواميس المراد تحويلها | **القيم المعادة** | نوع الإرجاع | الوصف | | ---------------------- | ------------------------------------------------------------------ | | `Dict[str, List[Any]]` | قاموس تكون مفاتيحه أسماء الأعمدة، وتكون قيمه قوائم تضم قيم الأعمدة | **مثال** ```pycon >>> items = [ ... {"name": "Alice", "age": 30, "city": "New York"}, ... {"name": "Bob", "age": 25}, ... {"name": "Charlie", "city": "San Francisco"} ... ] >>> convert_to_columnar(items) { 'name': ['Alice', 'Bob', 'Charlie'], 'age': [30, 25, None], 'city': ['New York', None, 'San Francisco'] } ``` ***
### `chdb.utils.flatten_dict`
يُسطِّح قاموسًا متداخلًا. تأخذ هذه الدالة قاموسًا متداخلًا وتُسطِّحه عبر دمج المفاتيح المتداخلة باستخدام فاصل. وتُحوَّل قوائم القواميس إلى سلاسل JSON. **البنية** ```python chdb.utils.flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '_') → Dict[str, Any] ``` **المعلمات** | المعلمة | النوع | الافتراضي | الوصف | | ------------ | ---------------- | ---------- | --------------------------------------- | | `d` | `Dict[str, Any]` | *required* | القاموس المراد تسطيحه | | `parent_key` | str | `""` | المفتاح الأساسي الذي يُضاف قبل كل مفتاح | | `sep` | str | `"_"` | الفاصل المستخدم بين المفاتيح الموصولة | **القيمة المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ------------- | | `Dict[str, Any]` | قاموس مُسطَّح | **مثال** ```pycon >>> nested_dict = { ... "a": 1, ... "b": { ... "c": 2, ... "d": { ... "e": 3 ... } ... }, ... "f": [4, 5, {"g": 6}], ... "h": [{"i": 7}, {"j": 8}] ... } >>> flatten_dict(nested_dict) { 'a': 1, 'b_c': 2, 'b_d_e': 3, 'f_0': 4, 'f_1': 5, 'f_2_g': 6, 'h': '[{"i": 7}, {"j": 8}]' } ``` ***
### `chdb.utils.infer_data_type`
يستنتج أنسب نوع بيانات لقائمة من القيم. تفحص هذه الدالة قائمة من القيم وتحدد نوع البيانات الأنسب لتمثيل جميع القيم فيها. وهي تأخذ في الاعتبار أنواع الأعداد الصحيحة، والأعداد الصحيحة غير الموقعة، والأنواع العشرية، وأنواع الفاصلة العائمة، وتستخدم “string” افتراضيًا إذا تعذر تمثيل القيم بأي نوع رقمي أو إذا كانت جميع القيم None. **البنية** ```python chdb.utils.infer_data_type(values: List[Any]) → str ``` **المعلمات** | المعلَمة | النوع | الوصف | | -------- | ----------- | -------------------------------------------------------------- | | `values` | `List[Any]` | قائمة بالقيم المراد تحليلها. ويمكن أن تكون هذه القيم من أي نوع | **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `str` | سلسلة نصية تمثل نوع البيانات المُستنتَج. وقيم الإرجاع المحتملة هي: ”int8”، “int16”، “int32”، “int64”، “int128”، “int256”، “uint8”، “uint16”،“uint32”، “uint64”، “uint128”، “uint256”، “decimal128”، “decimal256”، “float32”، “float64”، أو “string”. | * إذا كانت جميع القيم في القائمة هي None، فستُرجِع الدالة “string”. * إذا كانت أي قيمة في القائمة سلسلة نصية، فستُرجِع الدالة “string” فورًا. * تفترض الدالة أن القيم العددية يمكن تمثيلها كأعداد صحيحة، أو أعداد عشرية، أو أعداد فاصلة عائمة استنادًا إلى نطاقها ودقتها. ***
### `chdb.utils.infer_data_types`
يستنتج أنواع البيانات لكل عمود في بنية بيانات عمودية. تحلّل هذه الدالة القيم في كل عمود وتستنتج أكثر أنواع البيانات ملاءمةً له، استنادًا إلى عيّنة من البيانات. **الصيغة** ```python chdb.utils.infer_data_types`(column_data: Dict[str, List[Any]], n_rows: int = 10000) → List[tuple] ``` **المعاملات** | المعامل | النوع | الافتراضي | الوصف | | ------------- | ---------------------- | --------- | ---------------------------------------------------------------- | | `column_data` | `Dict[str, List[Any]]` | *مطلوب* | قاموس تكون فيه المفاتيح أسماء الأعمدة، والقيم قوائم بقيم الأعمدة | | `n_rows` | int | `10000` | عدد الصفوف التي ستُؤخذ كعيّنة من أجل استنتاج النوع | **القيم المعادة** | نوع القيمة المعادة | الوصف | | ------------------ | ----------------------------------------------------------------------------------- | | `List[tuple]` | قائمة من عناصر `tuple`، يحتوي كل عنصر منها على اسم عمود ونوع البيانات المُستنتَج له |
## الفئات الأساسية المجرّدة
### **فئة** `chdb.rwabc.PyReader`(data: Any)`
الفئات الأساسية: `ABC` ```python class chdb.rwabc.PyReader(data: Any) ``` ***
#### **abstractmethod** `read`
اقرأ عددًا محددًا من الصفوف من الأعمدة المحددة، وأعِد قائمة من الكائنات، بحيث يمثّل كل كائن تسلسلاً من القيم لعمود واحد. ```python abstractmethod (col_names: List[str], count: int) → List[Any] ``` **المعلمات** | المعلمة | النوع | الوصف | | ----------- | ----------- | -------------------------------------- | | `col_names` | `List[str]` | قائمة بأسماء الأعمدة المراد قراءتها | | `count` | int | الحد الأقصى لعدد الصفوف المراد قراءتها | **القيمة المعادة** | نوع الإرجاع | الوصف | | ----------- | -------------------------------- | | `List[Any]` | قائمة بالتسلسلات، واحدة لكل عمود |
### **الفئة** `chdb.rwabc.PyWriter`
الفئات الأساسية: `ABC` ```python class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any) ``` ***
#### **abstractmethod** finalize
جمِّع البيانات النهائية من الكتل وأعِدها. يجب أن تُنفِّذها الأصناف الفرعية. ```python abstractmethod finalize() → bytes ``` **القيمة المُعادة** | نوع الإرجاع | الوصف | | ----------- | ----------------------------- | | `bytes` | البيانات النهائية بعد تسلسلها | ***
#### **abstractmethod** `write`
يحفظ أعمدة البيانات في كتل. يجب أن تنفّذه الفئات الفرعية. ```python abstractmethod write(col_names: List[str], columns: List[List[Any]]) → None ``` **المعلمات** | المعلَمة | النوع | الوصف | | ----------- | ----------------- | ---------------------------------------------- | | `col_names` | `List[str]` | قائمة بأسماء الأعمدة قيد الكتابة | | `columns` | `List[List[Any]]` | قائمة ببيانات الأعمدة، ويُمثَّل كل عمود بقائمة |
## التعامل مع الاستثناءات
### **الفئة** `chdb.ChdbError`
الفئات الأساسية: `Exception` فئة الاستثناء الأساسية للأخطاء المرتبطة بـ chDB. يتم رفع هذا الاستثناء عندما يفشل تنفيذ query في chDB أو عند حدوث error. وهو يرث من فئة `Exception` القياسية في Python ويقدّم معلومات عن الخطأ من ClickHouse engine الأساسي. تتضمن رسالة الاستثناء عادةً معلومات تفصيلية عن error من ClickHouse، بما في ذلك أخطاء الصياغة، وعدم تطابق الأنواع، والجداول أو الأعمدة المفقودة، وغيرها من مشكلات تنفيذ query. **المتغيرات** | المتغير | النوع | الوصف | | ------- | ----- | ------------------------------------------------- | | `args` | - | `Tuple` يحتوي على رسالة الخطأ وأي argument إضافية | **أمثلة** ```pycon >>> try: ... result = chdb.query("SELECT * FROM non_existent_table") ... except chdb.ChdbError as e: ... print(f"Query failed: {e}") Query failed: Table 'non_existent_table' doesn't exist ``` ```pycon >>> try: ... result = chdb.query("SELECT invalid_syntax FROM") ... except chdb.ChdbError as e: ... print(f"Syntax error: {e}") Syntax error: Syntax error near 'FROM' ``` يُثار هذا الاستثناء تلقائيًا بواسطة chdb.query() والدوال ذات الصلة عندما يُبلّغ محرك ClickHouse الأساسي عن خطأ. ينبغي التقاط هذا الاستثناء عند التعامل مع الاستعلامات المعرّضة للفشل لتوفير معالجة مناسبة للأخطاء في تطبيقك.
## معلومات الإصدار
### `chdb.chdb_version = ('3', '6', '0')`
تسلسل مضمّن غير قابل للتغيير. إذا لم يتم تمرير أي وسيطة، فسيُعيد المُنشئ tuple فارغًا. وإذا تم تحديد iterable، فستتم تهيئة tuple من عناصره. إذا كانت الوسيطة من النوع tuple، فستكون القيمة المُعادة هي الكائن نفسه. ***
### `chdb.engine_version = '25.5.2.1'`
```python str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str ``` أنشئ كائنًا جديدًا من نوع كائن نصي من الكائن المعطى. إذا تم تحديد `encoding` أو `errors`، فيجب أن يوفّر الكائن مخزن مؤقت للبيانات سيُفك ترميزه باستخدام الترميز المحدد ومعالج الأخطاء المحدد. وإلا، فستُعاد نتيجة object.*_str*_() (إن كانت معرّفة) أو repr(object). * القيمة الافتراضية لـ `encoding` هي ‘utf-8’. * القيمة الافتراضية لـ `errors` هي ‘strict’. ***
### `chdb.__version__ = '3.6.0'`
```python str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str ``` أنشئ كائنًا نصيًا جديدًا من الكائن المعطى. إذا جرى تحديد encoding أو errors، فيجب أن يوفّر الكائن مخزنًا مؤقتًا للبيانات سيُفك ترميزه باستخدام الترميز المحدد ومعالج الأخطاء المحدد. وإلا، فستُعاد نتيجة object.*_str*_() (إذا كانت معرّفة) أو repr(object). * القيمة الافتراضية لـ encoding هي ‘utf-8’. * القيمة الافتراضية لـ errors هي ‘strict’.