> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# مرجع واجهة برمجة تطبيقات Python لـ chDB
> المرجع الكامل لواجهة برمجة تطبيقات Python الخاصة بـ chDB
## دوال الاستعلام الأساسية
### `chdb.query`
تنفيذ استعلام SQL باستخدام محرك chDB.
هذه هي دالة الاستعلام الرئيسية التي تنفّذ عبارات SQL باستخدام محرك
ClickHouse المضمّن. وهي تدعم تنسيقات إخراج متعددة، ويمكنها العمل مع قواعد
البيانات داخل الذاكرة أو المستندة إلى الملفات.
**البنية**
```python theme={null}
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 | `""` | مسار دليل دوال معرّفة من قبل المستخدم |
**القيم المعادة**
يعيد نتيجة الاستعلام بالتنسيق المحدد:
| نوع القيمة المعادة | الحالة |
| ------------------ | ------------------------------------------------------------------- |
| `str` | للتنسيقات النصية مثل CSV وJSON |
| `pd.DataFrame` | عندما تكون قيمة `output_format` هي `"DataFrame"` أو `"dataframe"` |
| `pa.Table` | عندما تكون قيمة `output_format` هي `"ArrowTable"` أو `"arrowtable"` |
| chdb result object | للتنسيقات الأخرى |
**الاستثناءات**
| الاستثناء | الحالة |
| ------------- | -------------------------------------------------------------- |
| `ChdbError` | إذا فشل تنفيذ استعلام SQL |
| `ImportError` | إذا كانت التبعيات المطلوبة لتنسيقات DataFrame/Arrow غير متوفرة |
**أمثلة**
```pycon theme={null}
>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"
```
```pycon theme={null}
>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
id msg
0 1 hello
```
```pycon theme={null}
>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")
```
```pycon theme={null}
>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
```
***
### `chdb.sql`
تنفيذ استعلام SQL باستخدام محرك chDB.
هذه هي دالة الاستعلام الرئيسية التي تنفّذ عبارات SQL باستخدام محرك
ClickHouse المضمّن. وهي تدعم تنسيقات إخراج متعددة، ويمكنها العمل مع قواعد بيانات
داخل الذاكرة أو مستندة إلى الملفات.
**البنية**
```python theme={null}
chdb.sql(sql, output_format='CSV', path='', udf_path='')
```
**المعلمات**
| Parameter | 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 | `""` | المسار إلى دليل الدوال المعرفة من قبل المستخدم |
**القيم المعادة**
تعيد نتيجة الاستعلام بالتنسيق المحدد:
| Return Type | Condition |
| ------------------ | ------------------------------------------------------------------- |
| `str` | للتنسيقات النصية مثل CSV وJSON |
| `pd.DataFrame` | عندما تكون قيمة `output_format` هي `"DataFrame"` أو `"dataframe"` |
| `pa.Table` | عندما تكون قيمة `output_format` هي `"ArrowTable"` أو `"arrowtable"` |
| chdb result object | للتنسيقات الأخرى |
**الاستثناءات**
| Exception | Condition |
| ------------------------- | ---------------------------------------------------------- |
| [`ChdbError`](#chdberror) | إذا فشل تنفيذ استعلام SQL |
| `ImportError` | إذا كانت التبعيات المطلوبة لتنسيقات DataFrame/Arrow مفقودة |
**أمثلة**
```pycon theme={null}
>>> # Basic CSV query
>>> result = chdb.query("SELECT 1, 'hello'")
>>> print(result)
"1,hello"
```
```pycon theme={null}
>>> # Query with DataFrame output
>>> df = chdb.query("SELECT 1 as id, 'hello' as msg", "DataFrame")
>>> print(df)
id msg
0 1 hello
```
```pycon theme={null}
>>> # Query with file-based database
>>> result = chdb.query("CREATE TABLE test (id INT) ENGINE = Memory", path="mydb.chdb")
```
```pycon theme={null}
>>> # Query with UDF
>>> result = chdb.query("SELECT my_udf('test')", udf_path="/path/to/udfs")
```
***
### `chdb.to_arrowTable`
حوّل نتيجة استعلام إلى PyArrow Table.
يحوّل نتيجة استعلام chdb إلى PyArrow Table لمعالجة البيانات العمودية بكفاءة.
ويُرجِع جدولًا فارغًا إذا كانت النتيجة فارغة.
**البنية**
```python theme={null}
chdb.to_arrowTable(res)
```
**المعلمات**
| المعلمة | الوصف |
| ------- | ------------------------------------------------------ |
| `res` | كائن نتيجة query في chDB يحتوي على بيانات Arrow ثنائية |
**القيمة المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ---------------------------------- |
| `pa.Table` | جدول PyArrow يحتوي على نتائج query |
**الأخطاء المرفوعة**
| نوع الخطأ | الوصف |
| ------------- | ------------------------------------- |
| `ImportError` | إذا لم يكن pyarrow أو pandas مثبّتَين |
**مثال**
```pycon theme={null}
>>> 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 theme={null}
chdb.to_df(r)
```
**المعلمات**
| المعلمة | الوصف |
| ------- | ---------------------------------------------------------- |
| `r` | كائن نتيجة استعلام في chDB يحتوي على بيانات Arrow الثنائية |
**القيمة المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | -------------------------------------------- |
| `pd.DataFrame` | إطار بيانات pandas يحتوي على نتائج الاستعلام |
**الاستثناءات**
| الاستثناء | الحالة |
| ------------- | ------------------------------------- |
| `ImportError` | إذا لم يكن pyarrow أو pandas مثبّتَين |
**مثال**
```pycon theme={null}
>>> 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 theme={null}
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` | إذا فشل الاتصال بقاعدة البيانات |
لا يُدعم سوى اتصال واحد لكل عملية.
سيؤدي إنشاء اتصال جديد إلى إغلاق أي اتصال موجود.
**أمثلة**
```pycon theme={null}
>>> # In-memory 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، فسيُنشئ دليلًا مؤقتًا ويستخدمه كمسار لقاعدة البيانات،
وسيُزال الدليل المؤقت عند إغلاق الجلسة.
يمكنك أيضًا تمرير مسار لإنشاء قاعدة بيانات في ذلك المسار للاحتفاظ ببياناتك.
يمكنك أيضًا استخدام سلسلة اتصال لتمرير المسار ومعلمات أخرى.
```python theme={null}
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\¶m2=value2](file:test.db?param1=value1\¶m2=value2)”
سيتم تمرير “param1=value1” إلى محرك ClickHouse كوسائط بدء التشغيل.
لمزيد من التفاصيل، راجع `clickhouse local –help –verbose`
طريقة معالجة بعض الوسائط الخاصة:
* تتحول “mode=ro” إلى “–readonly=1” في clickhouse (وضع القراءة فقط)
**مهم**
* لا يمكن أن توجد إلا جلسة واحدة في كل مرة. إذا أردت إنشاء جلسة جديدة، فعليك إغلاق الجلسة الحالية.
* سيؤدي إنشاء جلسة جديدة إلى إغلاق الجلسة الحالية.
***
#### `cleanup`
نظِّف موارد الجلسة مع معالجة الاستثناءات.
تحاول هذه الطريقة إغلاق الجلسة مع تجاهل أي استثناءات
قد تحدث أثناء عملية التنظيف. وهي مفيدة بشكل خاص في
سيناريوهات معالجة الأخطاء أو عندما تحتاج إلى ضمان تنفيذ التنظيف بغضّ النظر
عن حالة الجلسة.
**البنية**
```python theme={null}
cleanup()
```
لن تتسبب هذه الطريقة مطلقًا في ظهور أي استثناء، مما يجعل استدعاءها آمنًا داخل
كتل finally أو في الدوال المدمِّرة.
**أمثلة**
```pycon theme={null}
>>> session = Session("test.db")
>>> try:
... session.query("INVALID SQL")
... finally:
... session.cleanup() # Safe cleanup regardless of errors
```
**انظر أيضًا**
* [`close()`](#chdb-session-session-close) - للإغلاق الصريح للجلسة مع تمرير الأخطاء
***
#### `close`
أغلق الجلسة وحرّر الموارد.
تُغلق هذه الدالة الاتصال الأساسي وتعيد تعيين حالة الجلسة العامة.
بعد استدعاء هذه الدالة، تصبح الجلسة غير صالحة ولا يمكن استخدامها لإجراء
مزيد من الاستعلامات.
**البنية**
```python theme={null}
close()
```
تُستدعى هذه الطريقة تلقائيًا عند استخدام الجلسة كمدير سياق
أو عند حذف كائن الجلسة.
**مهم**
ستؤدي أي محاولة لاستخدام الجلسة بعد استدعاء `close()` إلى حدوث خطأ.
**أمثلة**
```pycon theme={null}
>>> session = Session("test.db")
>>> session.query("SELECT 1")
>>> session.close() # Explicitly close the session
```
***
#### `query`
نفِّذ استعلام SQL وأعِد النتائج.
تُنفِّذ هذه الطريقة استعلام SQL على قاعدة بيانات الجلسة وتُعيد
النتائج بالتنسيق المحدد. وتدعم هذه الطريقة تنسيقات إخراج متعددة،
كما تحافظ على حالة الجلسة بين الاستعلامات.
**البنية**
```python theme={null}
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 من تهيئة الجلسة |
**القيم المعادة**
يعيد نتائج الاستعلام بالتنسيق المحدد.
ويعتمد نوع القيمة المعادة الفعلي على معلمة التنسيق:
* تنسيقات السلاسل النصية (CSV وJSON وما إلى ذلك) تعيد `str`
* التنسيقات الثنائية (Arrow وParquet) تعيد `bytes`
**الاستثناءات**
| الاستثناء | الحالة |
| -------------- | ------------------------------------- |
| `RuntimeError` | إذا كانت الجلسة مغلقة أو غير صالحة |
| `ValueError` | إذا كان استعلام SQL به خطأ في الصياغة |
تنسيق “Debug” غير مدعوم، وسيُحوَّل تلقائيًا
إلى “CSV” مع عرض تحذير.
ولأغراض تصحيح الأخطاء، استخدم معلمات سلسلة الاتصال بدلًا من ذلك.
**تحذير**
تنفّذ هذه الطريقة الاستعلام بشكل متزامن وتحمّل جميع النتائج إلى
الذاكرة. بالنسبة إلى مجموعات النتائج الكبيرة، فكّر في استخدام [`send_query()`](#chdb-session-session-send_query) للحصول على
نتائج متدفقة.
**أمثلة**
```pycon theme={null}
>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1
```
```pycon theme={null}
>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}
```
```pycon theme={null}
>>> # 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 theme={null}
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 theme={null}
>>> 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 theme={null}
>>> # 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 theme={null}
sql(sql, fmt='CSV', udf_path='')
```
**المعلمات**
| المعلمة | النوع | القيمة الافتراضية | الوصف |
| ---------- | ----- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sql` | str | *required* | سلسلة استعلام SQL المطلوب تنفيذه |
| `fmt` | str | `"CSV"` | تنسيق الإخراج للنتائج. التنسيقات المتاحة:
• `"CSV"` - قيم مفصولة بفواصل
• `"JSON"` - تنسيق JSON
• `"TabSeparated"` - قيم مفصولة بعلامات تبويب
• `"Pretty"` - تنسيق جدول Pretty منسّق
• `"JSONCompact"` - تنسيق JSON مضغوط
• `"Arrow"` - تنسيق Apache Arrow
• `"Parquet"` - تنسيق Parquet |
| `udf_path` | str | `""` | مسار الدوال المعرّفة من قبل المستخدم. إذا لم يتم تحديده، فسيُستخدم مسار UDF من تهيئة الجلسة |
**القيم المعادة**
تُعيد نتائج الاستعلام بالتنسيق المحدد.
ويعتمد نوع القيمة المعادة الفعلي على معلمة التنسيق:
* تُعيد تنسيقات String (مثل CSV وJSON وغيرها) قيمة من النوع `str`
* تُعيد التنسيقات الثنائية (Arrow وParquet) قيمة من النوع `bytes`
**الاستثناءات:**
| الاستثناء | الحالة |
| -------------- | ------------------------------------ |
| `RuntimeError` | إذا كانت الجلسة مغلقة أو غير صالحة |
| `ValueError` | إذا كان استعلام SQL غير صحيح الصياغة |
تنسيق “Debug” غير مدعوم، وسيُحوَّل تلقائيًا إلى “CSV” مع عرض
تحذير. لتصحيح الأخطاء، استخدم معلمات سلسلة الاتصال
بدلًا من ذلك.
**تحذير**
تنفّذ هذه الطريقة الاستعلام بشكل متزامن وتحمّل جميع النتائج إلى
الذاكرة.
بالنسبة إلى مجموعات النتائج الكبيرة، يُرجى التفكير في استخدام [`send_query()`](#chdb-session-session-send_query) للحصول على نتائج متدفقة.
**أمثلة**
```pycon theme={null}
>>> session = Session("test.db")
>>>
>>> # Basic query with default CSV format
>>> result = session.query("SELECT 1 as number")
>>> print(result)
number
1
```
```pycon theme={null}
>>> # Query with JSON format
>>> result = session.query("SELECT 1 as number", fmt="JSON")
>>> print(result)
{"number": "1"}
```
```pycon theme={null}
>>> # 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 theme={null}
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` | إذا فشل الاتصال بقاعدة البيانات |
**تحذير**
لا يُدعم سوى اتصال واحد لكل عملية.
سيؤدي إنشاء اتصال جديد إلى إغلاق أي اتصال موجود.
**أمثلة**
```pycon theme={null}
>>> # In-memory 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 theme={null}
class chdb.state.sqlitelike.Connection(connection_string: str)
```
***
#### `close`
أغلق الاتصال ونظّف الموارد.
تُغلق هذه الطريقة اتصال قاعدة البيانات وتُنظّف أي موارد مرتبطة به، بما في ذلك المؤشرات النشطة. بعد استدعاء هذه الطريقة، يصبح الاتصال غير صالح ولا يمكن استخدامه في أي عمليات لاحقة.
**الصياغة**
```python theme={null}
close() → None
```
تسترجع هذه الطريقة النتيجة نفسها عند استدعائها أكثر من مرة، لذا فإن استدعاءها عدة مرات آمن.
**تحذير**
سيتم إلغاء أي استعلامات متدفقة جارية عند إغلاق الاتصال.
تأكد من معالجة جميع البيانات المهمة قبل إغلاق الاتصال.
**أمثلة**
```pycon theme={null}
>>> conn = connect("test.db")
>>> # Use connection for queries
>>> conn.query("CREATE TABLE test (id INT) ENGINE = Memory")
>>> # Close when done
>>> conn.close()
```
```pycon theme={null}
>>> # 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 theme={null}
cursor() → Cursor
```
**يعيد**
| نوع القيمة المعادة | الوصف |
| ------------------ | ---------------------------------- |
| `Cursor` | كائن Cursor لعمليات قاعدة البيانات |
سيؤدي إنشاء مؤشر جديد إلى استبدال أي مؤشر موجود مرتبط
بهذا الاتصال. لا يُدعَم إلا مؤشر واحد لكل اتصال.
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
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 theme={null}
>>> conn = connect(":memory:")
>>>
>>> # Basic CSV query
>>> result = conn.query("SELECT 1 as num, 'hello' as text")
>>> print(result)
num,text
1,hello
```
```pycon theme={null}
>>> # 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 theme={null}
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 theme={null}
>>> 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 theme={null}
>>> # 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 theme={null}
>>> # 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 theme={null}
class chdb.state.sqlitelike.StreamingResult
```
***
#### `fetch`
اجلب الجزء التالي من نتائج الاستعلام المتدفقة.
تسترجع هذه الطريقة الجزء التالي المتاح من البيانات من نتيجة الاستعلام المتدفق.
ويعتمد تنسيق البيانات المُعادة على التنسيق المحدد
عند بدء الاستعلام المتدفق.
**الصياغة**
```python theme={null}
fetch() → Any
```
**القيم المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ----------------------------------- |
| `str` | للتنسيقات النصية (CSV، JSON) |
| `bytes` | للتنسيقات الثنائية (Arrow، Parquet) |
| `None` | عند استنفاد دفق النتائج |
**أمثلة**
```pycon theme={null}
>>> stream = conn.send_query("SELECT * FROM large_table")
>>> chunk = stream.fetch()
>>> while chunk is not None:
... process_data(chunk)
... chunk = stream.fetch()
```
***
#### `cancel`
ألغِ الاستعلام المتدفق وحرِّر الموارد.
تلغي هذه الطريقة أي استعلام متدفق جارٍ وتحرِّر الموارد المرتبطة به.
ويجب استدعاؤها عندما تريد إيقاف معالجة النتائج
قبل انتهاء التدفق.
**الصياغة**
```python theme={null}
cancel() → None
```
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
close() → None
```
***
#### `record_batch`
أنشئ `PyArrow RecordBatchReader` لمعالجة الدُفعات بكفاءة.
تُنشئ هذه الطريقة كائن `PyArrow RecordBatchReader` يتيح
التكرار بكفاءة عبر نتائج الاستعلام بتنسيق Arrow. وهذه هي
الطريقة الأكثر كفاءة لمعالجة مجموعات النتائج الكبيرة عند استخدام `PyArrow`.
**الصياغة**
```python theme={null}
record_batch(rows_per_batch: int = 1000000) → pa.RecordBatchReader
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ---------------- | ----- | --------- | --------------------- |
| `rows_per_batch` | int | `1000000` | عدد الصفوف في كل دفعة |
**القيم المعادة**
| نوع القيمة المعادة | الوصف |
| ---------------------- | ------------------------------------------------------ |
| `pa.RecordBatchReader` | قارئ RecordBatchReader من PyArrow للتكرار على الدُفعات |
لا تتوفر هذه الطريقة إلا إذا بدأ الاستعلام المتدفق
باستخدام `format="Arrow"`. وسيؤدي استخدامها مع تنسيقات أخرى إلى حدوث خطأ.
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
>>> stream = conn.send_query("SELECT number FROM numbers(1000000)")
>>> for chunk in stream:
... print(f"Chunk size: {len(chunk)} bytes")
```
***
#### بروتوكول مدير السياق
يدعم StreamingResult بروتوكول مدير السياق للتنظيف
التلقائي للموارد:
```pycon theme={null}
>>> with conn.send_query("SELECT * FROM data") as stream:
... for chunk in stream:
... process(chunk)
>>> # Stream automatically closed
```
***
### **الصنف** `chdb.state.sqlitelike.Cursor`
الصنف الأساسي: `object`
```python theme={null}
class chdb.state.sqlitelike.Cursor(connection)
```
***
#### `close`
أغلِق المؤشر ونظِّف الموارد.
تُغلق هذه الطريقة المؤشر وتُنظِّف أي موارد مرتبطة به.
بعد استدعاء هذه الطريقة، يصبح المؤشر غير صالح ولا يمكن
استخدامه في عمليات لاحقة.
**الصيغة**
```python theme={null}
close() → None
```
هذه الطريقة مكررة الأثر — لذا من الآمن استدعاؤها عدة مرات.
ويُغلَق المؤشر تلقائيًا أيضًا عند إغلاق الاتصال.
**أمثلة**
```pycon theme={null}
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchone()
>>> cursor.close() # Cleanup cursor resources
```
***
#### `column_names`
أعِد قائمة بأسماء الأعمدة من آخر استعلام نُفِّذ.
تُرجِع هذه الطريقة أسماء الأعمدة من أحدث استعلام SELECT تم تنفيذه.
وتُرجَع الأسماء بالترتيب نفسه الذي تظهر به
في مجموعة النتائج.
**الصيغة**
```python theme={null}
column_names() → list
```
**القيمة المُعادة**
| نوع القيمة المُعادة | الوصف |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `list` | قائمة بسلاسل نصية تمثل أسماء الأعمدة، أو قائمة فارغة إذا لم يُنفَّذ أي استعلام أو لم يُرجِع الاستعلام أي أعمدة |
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
column_types() → list
```
**القيم المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `list` | قائمة بسلاسل نصية لأسماء الأنواع في ClickHouse، أو قائمة فارغة إذا لم يُنفَّذ أي استعلام أو إذا لم يُرجِع الاستعلام أي أعمدة |
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
commit() → None
```
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
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 theme={null}
>>> 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 theme={null}
fetchall() → tuple
```
**القيمة المعادة:**
| Return Type | Description |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| `tuple` | Tuple تحتوي على جميع صفوف Tuple المتبقية في مجموعة النتائج. وتُرجع Tuple فارغة إذا لم تكن هناك صفوف متاحة |
**تحذير**
تُحمّل هذه الطريقة جميع الصفوف المتبقية إلى الذاكرة دفعة واحدة. بالنسبة إلى
مجموعات النتائج الكبيرة، فكّر في استخدام [`fetchmany()`](#chdb-state-sqlitelike-cursor-fetchmany) لمعالجة النتائج
على دفعات.
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
fetchmany(size: int = 1) → tuple
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ------- | ----- | --------- | ------------------------------------- |
| `size` | int | `1` | الحد الأقصى لعدد الصفوف المطلوب جلبها |
**القيم المعادة**
| نوع الإرجاع | الوصف |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `tuple` | قيمة `Tuple` تحتوي على ما يصل إلى 'size' من الصفوف في هيئة tuples. وقد تحتوي على عدد أقل من الصفوف إذا استُنفدت مجموعة النتائج |
تتبع هذه الطريقة مواصفات DB-API 2.0. وستُرجع عددًا أقل
من 'size' صفوف إذا استُنفدت مجموعة النتائج.
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
fetchone() → tuple | None
```
**يعيد:**
| نوع الإرجاع | الوصف |
| ----------------- | ---------------------------------------------------------------------------- |
| `Optional[tuple]` | الصف التالي على شكل tuple من قيم الأعمدة، أو None إذا لم تعد هناك صفوف متاحة |
تتبع هذه method مواصفات DB-API 2.0. وتُحوَّل قيم الأعمدة
تلقائيًا إلى أنواع Python المناسبة استنادًا إلى
أنواع أعمدة ClickHouse.
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
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 theme={null}
>>> 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 theme={null}
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 theme={null}
>>> 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 theme={null}
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 theme={null}
chdb.dbapi.connect(*args, **kwargs)
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ------- | ----- | --------- | ----------------------------------------------------------- |
| `path` | str | `None` | مسار ملف قاعدة البيانات. تكون None لقاعدة بيانات في الذاكرة |
**الاستثناءات**
| الاستثناء | الشرط |
| ------------------------------------ | ---------------------- |
| [`err.Error`](#chdb-dbapi-err-error) | إذا تعذر إنشاء الاتصال |
***
#### `chdb.dbapi.get_client_info()`
يسترجع معلومات إصدار العميل.
يعيد إصدار عميل chDB كسلسلة نصية للتوافق مع MySQLdb.
**الصيغة**
```python theme={null}
chdb.dbapi.get_client_info()
```
**القيم المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | --------------------------------------- |
| `str` | سلسلة الإصدار بصيغة 'major.minor.patch' |
***
### مُنشئات الأنواع
#### `chdb.dbapi.Binary(x)`
إرجاع x كنوع ثنائي.
تُحوِّل هذه الدالة المُدخل إلى النوع bytes لاستخدامه مع الحقول الثنائية في قاعدة البيانات،
وذلك وفقًا لمواصفة DB-API 2.0.
**الصيغة**
```python theme={null}
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 theme={null}
class chdb.dbapi.connections.Connection(path=None)
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ------- | ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path` | str | `None` | مسار ملف قاعدة البيانات. إذا كانت القيمة None، تُستخدم قاعدة بيانات في الذاكرة. يمكن أن يكون مسار ملف مثل 'database.db'، أو None لاستخدام ':memory:' |
**المتغيرات**
| المتغير | النوع | الوصف |
| ---------- | ----- | -------------------------------------------------------------- |
| `encoding` | str | ترميز الأحرف للاستعلامات، والقيمة الافتراضية هي 'utf8' |
| `open` | bool | تكون قيمته True إذا كان الاتصال مفتوحًا، وFalse إذا كان مغلقًا |
**أمثلة**
```pycon theme={null}
>>> # In-memory database
>>> conn = Connection()
>>> cursor = conn.cursor()
>>> cursor.execute("SELECT 1")
>>> result = cursor.fetchall()
>>> conn.close()
```
```pycon theme={null}
>>> # 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 theme={null}
>>> # Context manager usage
>>> with Connection() as cur:
... cur.execute("SELECT version()")
... version = cur.fetchone()
```
لا يدعم ClickHouse المعاملات التقليدية، لذا فإن العمليتين commit() و rollback()
لا تُحدثان أي تأثير، لكنهما متاحتان للامتثال لمعيار DB-API.
***
#### `close`
أغلق اتصال قاعدة البيانات.
يُغلق اتصال chDB الأساسي ويضع علامة على هذا الاتصال باعتباره مغلقًا.
وأي عمليات لاحقة على هذا الاتصال ستؤدي إلى ظهور خطأ.
**الصيغة**
```python theme={null}
close()
```
**الاستثناءات التي قد تُرفع**
| الاستثناء | الحالة |
| ------------------------------------ | ----------------------------- |
| [`err.Error`](#chdb-dbapi-err-error) | إذا كان الاتصال مغلقًا بالفعل |
***
#### `commit`
اعتمد المعاملة الحالية.
**الصيغة**
```python theme={null}
commit()
```
هذا الإجراء بلا تأثير في chDB/ClickHouse لأنه لا يدعم
المعاملات التقليدية. وهو متاح للامتثال لمعيار DB-API 2.0.
***
#### `cursor`
أنشئ مؤشرًا جديدًا لتنفيذ الاستعلامات.
**الصيغة**
```python theme={null}
cursor(cursor=None)
```
**المعلمات**
| المعلمة | النوع | الوصف |
| -------- | ----- | ------------------------- |
| `cursor` | - | يُتجاهل، ويُوفَّر للتوافق |
**العوائد**
| نوع الإرجاع | الوصف |
| ----------- | --------------------------- |
| `Cursor` | كائن مؤشر جديد لهذا الاتصال |
**الاستثناءات**
| الاستثناء | الشرط |
| ------------------------------------ | ----------------- |
| [`err.Error`](#chdb-dbapi-err-error) | إذا أُغلق الاتصال |
**مثال**
```pycon theme={null}
>>> conn = Connection()
>>> cur = conn.cursor()
>>> cur.execute("SELECT 1")
>>> result = cur.fetchone()
```
***
#### `escape`
أفلِت قيمة بحيث يمكن تضمينها بأمان في استعلامات SQL.
**الصيغة**
```python theme={null}
escape(obj, mapping=None)
```
**المعاملات**
| المعامل | النوع | الوصف |
| --------- | ----- | ---------------------------------------------------- |
| `obj` | - | القيمة المراد إفلاتها (سلسلة نصية، بايتات، رقم، إلخ) |
| `mapping` | - | تعيين اختياري للمحارف لعملية الإفلات |
**القيمة المعادة**
| نوع الإرجاع | الوصف |
| ----------- | ---------------------------------------------- |
| - | نسخة مُفلَتة من المُدخل ومناسبة لاستعلامات SQL |
**مثال**
```pycon theme={null}
>>> conn = Connection()
>>> safe_value = conn.escape("O'Reilly")
>>> query = f"SELECT * FROM users WHERE name = {safe_value}"
```
***
#### `escape_string`
قم بإفلات قيمة نصية لاستعلامات SQL.
**الصيغة**
```python theme={null}
escape_string(s)
```
**المعلمات**
| المعلمة | النوع | الوصف |
| ------- | ----- | ------------------------ |
| `s` | str | سلسلة نصية مطلوب تهريبها |
**القيمة المعادة**
| نوع الإرجاع | الوصف |
| ----------- | ---------------------------------------- |
| `str` | سلسلة نصية مُهرَّبة وآمنة للتضمين في SQL |
***
#### `property open`
تحقّق مما إذا كان الاتصال مفتوحًا.
**القيمة المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ------------------------------------------------- |
| `bool` | صحيح إذا كان الاتصال مفتوحًا، وخطأ إذا كان مغلقًا |
***
#### `query`
نفّذ استعلام SQL مباشرةً وأعِد النتائج الأولية.
تتجاوز هذه الطريقة واجهة المؤشر وتنفّذ الاستعلامات مباشرةً.
لاستخدام DB-API القياسي، يُفضَّل استخدام الطريقة cursor().
**الصيغة**
```python theme={null}
query(sql, fmt='CSV')
```
**المعلمات:**
| المعلمة | النوع | الافتراضي | الوصف |
| ------- | ------------ | --------- | -------------------------------------------------------------------------------- |
| `sql` | str or bytes | *مطلوب* | استعلام SQL المطلوب تنفيذه |
| `fmt` | str | `"CSV"` | تنسيق الإخراج. تشمل التنسيقات المدعومة "CSV" و"JSON" و"Arrow" و"Parquet" وغيرها. |
**القيمة المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ------------------------------- |
| - | نتيجة الاستعلام بالتنسيق المحدد |
**الاستثناءات**
| الاستثناء | الشرط |
| ------------------------------------------------------ | --------------------------------------- |
| [`err.InterfaceError`](#chdb-dbapi-err-interfaceerror) | إذا كان الاتصال مغلقًا أو فشل الاستعلام |
**مثال**
```pycon theme={null}
>>> conn = Connection()
>>> result = conn.query("SELECT 1, 'hello'", "CSV")
>>> print(result)
"1,hello\n"
```
***
#### `property resp`
يعرض آخر استجابة للاستعلام.
**القيمة المُعادة**
| نوع القيمة المُعادة | الوصف |
| ------------------- | ----------------------------------------- |
| - | الاستجابة الخام من آخر استدعاء لـ query() |
تُحدَّث هذه الخاصية في كل مرة يُستدعى فيها query() مباشرةً.
ولا تعكس الاستعلامات التي تُنفَّذ عبر المؤشرات.
***
#### `rollback`
التراجع عن المعاملة الحالية.
**البنية**
```python theme={null}
rollback()
```
هذه عملية بلا تأثير في chDB/ClickHouse لأنه لا يدعم
المعاملات التقليدية. وهي مُتاحة للامتثال لـ DB-API 2.0.
***
### فئة المؤشر
#### **فئة** `chdb.dbapi.cursors.Cursor`
يرث من: `object`
مؤشر DB-API 2.0 لتنفيذ الاستعلامات وجلب النتائج.
يوفّر المؤشر أساليب لتنفيذ عبارات SQL، وإدارة نتائج الاستعلام،
والتنقّل عبر مجموعات النتائج. كما يدعم ربط المعلمات والعمليات المجمّعة،
ويلتزم بمواصفات DB-API 2.0.
لا تُنشئ مثيلات مؤشر مباشرةً. استخدم `Connection.cursor()` بدلًا من ذلك.
```python theme={null}
class chdb.dbapi.cursors.Cursor(connection)
```
| المتغير | النوع | الوصف |
| ----------------- | ----- | ---------------------------------------------------------------- |
| `description` | tuple | البيانات الوصفية لأعمدة نتيجة آخر استعلام |
| `rowcount` | int | عدد الصفوف المتأثرة بآخر استعلام (-1 إذا كان غير معروف) |
| `arraysize` | int | العدد الافتراضي للصفوف التي يتم جلبها دفعةً واحدة (الافتراضي: 1) |
| `lastrowid` | - | معرّف آخر صف أُدرج (إن أمكن) |
| `max_stmt_length` | int | الحد الأقصى لحجم التعليمة لـ executemany() (الافتراضي: 1024000) |
**أمثلة**
```pycon theme={null}
>>> 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 theme={null}
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 theme={null}
close()
```
***
#### `execute`
نفّذ استعلام SQL مع ربط اختياري للمعلمات.
تُنفِّذ هذه الطريقة تعليمة SQL واحدة مع استبدال اختياري للمعلمات.
وتدعم عدة أنماط لعناصر نائبة للمعلمات لمزيد من المرونة.
**البنية**
```python theme={null}
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 theme={null}
>>> # 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 theme={null}
executemany(query, args)
```
**المعلمات**
| المعلمة | النوع | الوصف |
| ------- | ----- | ----------------------------------------------------------- |
| `query` | str | استعلام SQL يُنفَّذ عدة مرات |
| `args` | تسلسل | تسلسل من tuples/dicts/lists للمعلمات الخاصة بكل عملية تنفيذ |
**القيم المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ----------------------------------------------------- |
| `int` | العدد الإجمالي للصفوف المتأثرة في جميع عمليات التنفيذ |
**أمثلة**
```pycon theme={null}
>>> # 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 theme={null}
fetchall()
```
**يعيد**
| نوع القيمة المعادة | الوصف |
| ------------------ | -------------------------------------------- |
| `list` | قائمة من قيم Tuple تمثل جميع الصفوف المتبقية |
**يثير**
| الاستثناء | الشرط |
| ------------------------------------------------------ | ---------------------------------- |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا لم يتم استدعاء execute() أولاً |
**تحذير**
قد تستهلك هذه الطريقة كميات كبيرة من الذاكرة عند التعامل مع مجموعات نتائج كبيرة.
فكّر في استخدام `fetchmany()` مع مجموعات النتائج الكبيرة.
**مثال**
```pycon theme={null}
>>> cursor.execute("SELECT id, name FROM users")
>>> all_rows = cursor.fetchall()
>>> print(len(all_rows)) # Number of total rows
```
***
#### `fetchmany`
يجلب عدة صفوف من نتيجة الاستعلام.
**البنية**
```python theme={null}
fetchmany(size=1)
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ------- | ----- | --------- | ----------------------------------------------------------------------------- |
| `size` | int | `1` | عدد الصفوف المراد جلبها. إذا لم يتم تحديده، فستُستخدم القيمة cursor.arraysize |
**القيم المعادة**
| نوع القيمة المعادة | الوصف |
| ------------------ | ----------------------------------------- |
| `list` | قائمة من tuples تمثل الصفوف التي تم جلبها |
**الاستثناءات**
| الاستثناء | الشرط |
| ------------------------------------------------------ | ---------------------------------- |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا لم يتم استدعاء execute() أولًا |
**مثال**
```pycon theme={null}
>>> cursor.execute("SELECT id, name FROM users")
>>> rows = cursor.fetchmany(3)
>>> print(rows) # [(1, 'Alice'), (2, 'Bob'), (3, 'Charlie')]
```
***
#### `fetchone`
يجلب الصف التالي من نتيجة الاستعلام.
**الصياغة**
```python theme={null}
fetchone()
```
**القيم المعادة**
| نوع الإرجاع | الوصف |
| --------------- | -------------------------------------------------------------- |
| `tuple or None` | الصف التالي على هيئة tuple، أو None إذا لم تعد هناك صفوف متاحة |
**الاستثناءات**
| الاستثناء | الشرط |
| ------------------------------------------------------ | ------------------------------------ |
| [`ProgrammingError`](#chdb-dbapi-err-programmingerror) | إذا لم يتم استدعاء `execute()` أولًا |
**مثال**
```pycon theme={null}
>>> 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 theme={null}
mogrify(query, args=None)
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ------- | --------------- | --------- | -------------------------------------- |
| `query` | str | *مطلوب* | استعلام SQL يتضمن عناصر نائبة للمعلمات |
| `args` | tuple/list/dict | `None` | المعلمات المراد إحلالها |
**القيم المعادة**
| نوع الإرجاع | الوصف |
| ----------- | -------------------------------------------------- |
| `str` | سلسلة استعلام SQL النهائية بعد إحلال المعلمات فيها |
**مثال**
```pycon theme={null}
>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"
```
تتبع هذه الطريقة الامتداد الخاص بـ DB-API 2.0 كما يستخدمه Psycopg.
***
#### `nextset`
انتقل إلى مجموعة النتائج التالية (غير مدعوم).
**الصيغة**
```python theme={null}
nextset()
```
**يعيد**
| نوع الإرجاع | الوصف |
| ----------- | ---------------------------------------------------------- |
| `None` | يعيد `None` دائمًا لأن مجموعات النتائج المتعددة غير مدعومة |
لا يدعم chDB/ClickHouse إرجاع مجموعات نتائج متعددة من استعلام واحد.
تُوفَّر هذه الطريقة للامتثال لـ DB-API 2.0، لكنها تعيد `None` دائمًا.
***
#### `setinputsizes`
يضبط أحجام الإدخال للمعلمات (تنفيذ شكلي لا يؤدي أي إجراء).
**البنية**
```python theme={null}
setinputsizes(*args)
```
**المعلمات**
| المعلمة | النوع | الوصف |
| ------- | ----- | ---------------------------------- |
| `*args` | - | مواصفات حجم المعلمات (يتم تجاهلها) |
لا تقوم هذه الطريقة بأي شيء، لكنها مطلوبة وفقًا لمواصفة DB-API 2.0.
يتولى chDB تلقائيًا معالجة تحديد حجم المعلمات داخليًا.
***
#### `setoutputsizes`
ضبط أحجام أعمدة الإخراج (تنفيذ شكلي بلا تأثير فعلي).
**الصيغة**
```python theme={null}
setoutputsizes(*args)
```
**المعلمات**
| المعلمة | النوع | الوصف |
| ------- | ----- | -------------------------------- |
| `*args` | - | مواصفات حجم العمود (يتم تجاهلها) |
لا تقوم هذه الطريقة بأي شيء، لكنها مطلوبة وفقًا لمواصفة DB-API 2.0.
يتولى chDB تلقائيًا معالجة تحديد حجم المخرجات داخليًا.
***
### فئات الأخطاء
فئات الاستثناءات لعمليات قاعدة البيانات في chdb.
توفّر هذه الوحدة تسلسلاً هرمياً كاملاً لفئات الاستثناءات للتعامل مع
الأخطاء المرتبطة بقاعدة البيانات في chdb، وذلك وفقاً لمواصفة Python Database API الإصدار 2.0.
يأتي التسلسل الهرمي للاستثناءات على النحو التالي:
```default theme={null}
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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> # Division by zero in SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero
```
```pycon theme={null}
>>> # 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 theme={null}
>>> # 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 theme={null}
>>> # 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 theme={null}
>>> # Transaction rollback on non-transactional connection
>>> connection.rollback()
NotSupportedError: Transactions are not supported
```
```pycon theme={null}
>>> # 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 theme={null}
>>> # Table not found
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist
```
```pycon theme={null}
>>> # SQL syntax error
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax
```
```pycon theme={null}
>>> # 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 theme={null}
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 theme={null}
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 theme={null}
>>> int(‘0b100’, base=0)
4
```
***
#### `chdb.dbapi.paramstyle = 'format'`
```python theme={null}
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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
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 theme={null}
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 theme={null}
import chdb.dbapi as dbapi
# In-memory 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 متوافقة مع معظم أدوات قواعد بيانات Python
* توفّر الواجهة أمان خيوط من المستوى 1 (يمكن لخيوط التنفيذ مشاركة الوحدات، ولكن ليس الاتصالات)
* تدعم سلاسل الاتصال نفس المعلمات التي تدعمها جلسات chDB
* جميع استثناءات DB-API 2.0 القياسية مدعومة
**تحذير**
* أغلق دائمًا المؤشرات والاتصالات لتجنب تسرّب الموارد
* ينبغي معالجة مجموعات النتائج الكبيرة على دفعات
* تتبع صياغة ربط المعلمات نمط format: `%s`
## الدوال المعرّفة من قبل المستخدم (UDF)
وحدة الدوال المعرّفة من قبل المستخدم في chDB.
توفّر هذه الوحدة إمكانات إنشاء الدوال المعرّفة من قبل المستخدم (UDFs) وإدارتها
في chDB. كما تتيح لك توسيع إمكانات chDB من خلال كتابة دوال Python مخصّصة
يمكن استدعاؤها من استعلامات SQL.
### `chdb.udf.chdb_udf`
مُزيِّن لدوال Python من نوع UDF (دالة معرّفة من المستخدم) في chDB.
**البنية**
```python theme={null}
chdb.udf.chdb_udf(return_type='String')
```
**المعلمات**
| المعلمة | النوع | الافتراضي | الوصف |
| ------------- | ----- | ---------- | --------------------------------------------------------- |
| `return_type` | str | `"String"` | نوع إرجاع الدالة. يجب أن يكون أحد أنواع بيانات ClickHouse |
**ملاحظات**
1. يجب أن تكون الدالة عديمة الحالة. يتم دعم UDFs فقط، وليس UDAFs.
2. نوع الإرجاع الافتراضي هو String. ويجب أن يكون نوع الإرجاع أحد أنواع بيانات ClickHouse.
3. يجب أن تستقبل الدالة وسيطات من النوع String. جميع الوسيطات سلاسل نصية.
4. سيتم استدعاء الدالة لكل سطر من الإدخال.
5. يجب أن تكون الدالة مكتوبة باستخدام pure Python. استورد جميع الوحدات المستخدمة داخل الدالة.
6. مُفسِّر Python المستخدم هو نفسه المستخدم لتشغيل البرنامج النصي.
**مثال**
```python theme={null}
@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. برنامجًا نصيًا تنفيذيًا بلغة Python لمعالجة بيانات الإدخال
2. ملف تهيئة XML لتسجيل UDF في ClickHouse
**الصيغة**
```python theme={null}
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 بلغة Python لدالة UDF |
تُستدعى هذه الدالة عادةً عبر المُزيِّن @chdb\_udf، ولا ينبغي
للمستخدمين استدعاؤها مباشرةً.
***
## الأدوات المساعدة
الدوال والأدوات المساعدة لـ chDB.
تتضمن هذه الوحدة مجموعة متنوعة من الدوال المساعدة للعمل مع chDB، بما في ذلك
استنتاج أنواع البيانات، وأدوات تحويل البيانات، وأدوات تصحيح الأخطاء.
***
### `chdb.utils.convert_to_columnar`
يحوّل قائمة من القواميس إلى تنسيق عمودي.
تأخذ هذه الدالة قائمة من القواميس وتحوّلها إلى قاموس
حيث يقابل كل مفتاح عمودًا، وتمثل كل قيمة قائمةً من قيم الأعمدة.
تُمثَّل القيم المفقودة في القواميس على أنها None.
**البنية**
```python theme={null}
chdb.utils.convert_to_columnar(items: List[Dict[str, Any]]) → Dict[str, List[Any]]
```
**المعلمات**
| المعلمة | النوع | الوصف |
| ------- | ---------------------- | -------------------------------- |
| `items` | `List[Dict[str, Any]]` | قائمة من القواميس المراد تحويلها |
**القيم المعادة**
| نوع الإرجاع | الوصف |
| ---------------------- | ------------------------------------------------------------------ |
| `Dict[str, List[Any]]` | قاموس تكون مفاتيحه أسماء الأعمدة، وتكون قيمه قوائم تضم قيم الأعمدة |
**مثال**
```pycon theme={null}
>>> 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 theme={null}
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 theme={null}
>>> 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 theme={null}
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 theme={null}
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 theme={null}
class chdb.rwabc.PyReader(data: Any)
```
***
#### **abstractmethod** `read`
اقرأ عددًا محددًا من الصفوف من الأعمدة المحددة، وأعِد قائمة من الكائنات،
بحيث يمثّل كل كائن تسلسلاً من القيم لعمود واحد.
```python theme={null}
abstractmethod (col_names: List[str], count: int) → List[Any]
```
**المعلمات**
| المعلمة | النوع | الوصف |
| ----------- | ----------- | -------------------------------------- |
| `col_names` | `List[str]` | قائمة بأسماء الأعمدة المراد قراءتها |
| `count` | int | الحد الأقصى لعدد الصفوف المراد قراءتها |
**القيمة المعادة**
| نوع الإرجاع | الوصف |
| ----------- | -------------------------------- |
| `List[Any]` | قائمة بالتسلسلات، واحدة لكل عمود |
### **الفئة** `chdb.rwabc.PyWriter`
الفئات الأساسية: `ABC`
```python theme={null}
class chdb.rwabc.PyWriter(col_names: List[str], types: List[type], data: Any)
```
***
#### **abstractmethod** finalize
جمِّع البيانات النهائية من الكتل وأعِدها. يجب أن تُنفِّذها الأصناف الفرعية.
```python theme={null}
abstractmethod finalize() → bytes
```
**القيمة المُعادة**
| نوع الإرجاع | الوصف |
| ----------- | ----------------------------- |
| `bytes` | البيانات النهائية بعد تسلسلها |
***
#### **abstractmethod** `write`
يحفظ أعمدة البيانات في كتل. يجب أن تنفّذه الفئات الفرعية.
```python theme={null}
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 theme={null}
>>> 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 theme={null}
>>> 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 theme={null}
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 theme={null}
str(object=’’) -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
```
أنشئ كائنًا نصيًا جديدًا من الكائن المعطى. إذا جرى تحديد encoding أو
errors، فيجب أن يوفّر الكائن مخزنًا مؤقتًا للبيانات
سيُفك ترميزه باستخدام الترميز المحدد ومعالج الأخطاء المحدد.
وإلا، فستُعاد نتيجة object.*\_str*\_() (إذا كانت معرّفة)
أو repr(object).
* القيمة الافتراضية لـ encoding هي ‘utf-8’.
* القيمة الافتراضية لـ errors هي ‘strict’.