> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# chDB كبرنامج تشغيل ADBC

> كيفية استخدام chDB عبر Arrow Database Connectivity ‏(ADBC)

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            ميزة تجريبية
        </a>;
};

<ExperimentalBadge />

<Warning>
  برنامج تشغيل ADBC تجريبي. قد يتغير سلوكه وخياراته بين الإصدارات.
</Warning>

[ADBC](https://arrow.apache.org/adbc/) هي واجهة برمجة تطبيقات مستقلة عن المورّد لنقل بيانات Arrow بين تطبيق وقاعدة بيانات. يُوزَّع برنامج تشغيل chDB ADBC عبر ADBC Driver Foundry، ويمكن تحميله باستخدام أي مدير لبرامج تشغيل ADBC.

تتجاوز النتائج الحدود على هيئة دفعات سجلات Arrow، من دون تحويل صفًا بصف. ويمكن للتطبيقات استخدام برنامج التشغيل نفسه من بايثون أو أي لغة أخرى تتوفر فيها إدارة برامج تشغيل ADBC.

<div id="installation">
  ## التثبيت
</div>

ثبّت برنامج التشغيل من مستودع ADBC Driver Foundry باستخدام [`dbc`](https://docs.columnar.tech/dbc/):

```bash theme={null}
dbc install chdb
```

أول إصدار منشور من حزمة `dbc` لـ chDB هو 26.7.0. للتحقق من الإصدارات المتاحة، شغّل:

```bash theme={null}
dbc search -v chdb
```

يمكن تحميل برنامج التشغيل المثبّت باسم `chdb` من خلال مدير برامج تشغيل ADBC.

يتوفر الدعم لنظامَي Linux وmacOS على معماريتَي x86-64 وarm64.

<div id="connecting-from-python">
  ## الاتصال من بايثون
</div>

ثبّت مدير برامج تشغيل ADBC لبايثون:

```bash theme={null}
pip install adbc-driver-manager pyarrow
```

ثم حمّل برنامج تشغيل chDB المثبّت عبر `dbc` بالاسم:

```python theme={null}
from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(3)")
        print(cur.fetch_arrow_table())
```

| `uri`                   | قاعدة البيانات                      |
| ----------------------- | ----------------------------------- |
| `chdb://`               | في الذاكرة                          |
| `chdb:///absolute/path` | على القرص، وتُحفَظ في الدليل المحدد |

<div id="connection-lifecycle">
  ## دورة حياة الاتصال
</div>

يشغّل chDB محركًا مضمنًا واحدًا في كل عملية ما دامت الاتصالات مفتوحة. ضع القواعد التالية في الاعتبار:

* يجب أن تشير جميع اتصالات ADBC المفتوحة في الوقت نفسه ضمن العملية نفسها إلى مسار التخزين نفسه.
* يدعم النظام اتصالات متعددة بهذا المسار، بما في ذلك الاتصالات المستخدمة بالتزامن من سلاسل تنفيذ مختلفة. للاستعلامات المتزامنة، خصص لكل عامل اتصالًا خاصًا به بدلًا من تنفيذ عمليات متزامنة على اتصال واحد.
* يؤدي إغلاق آخر اتصال إلى إيقاف المحرك المضمن. ويمكن لاتصال لاحق تشغيله مجددًا، بما في ذلك باستخدام مسار تخزين مختلف، لكن تكرار الإيقاف والتشغيل يستهلك الوقت والذاكرة. أبقِ اتصالًا واحدًا على الأقل مفتوحًا للأعمال المتكررة.
* لا يمكن إلا لعملية واحدة في نظام التشغيل فتح دليل معيّن على القرص في الوقت نفسه. خصص لكل عملية دليلًا خاصًا بها، أو استخدم قاعدة بيانات داخل الذاكرة.

<div id="using-python-chdb-package">
  ### استخدام ADBC مع حزمة chDB لبايثون
</div>

تثبّت حزمة `dbc` برنامج تشغيل ADBC أصليًا مستقلاً. وهو منفصل عن المكتبة الأصلية التي تحمّلها حزمة `chdb` لبايثون.

ضمن عملية بايثون واحدة، لا تتوقع أن تشترك وصلة ADBC التي حمّلها `dbc` ووصلة `chdb` العادية في الجداول الموجودة في الذاكرة أو حالة المحرك. بالنسبة إلى مسار قاعدة بيانات معيّن، استخدم إما برنامج تشغيل ADBC أو واجهة برمجة تطبيقات `chdb` لبايثون في الوقت نفسه؛ ولا تُبقِ كليهما مفتوحين على المسار نفسه على القرص. لنقل البيانات بين واجهتي برمجة التطبيقات، أغلق جميع الوصلات من أحد الجانبين قبل فتح الجانب الآخر، أو مرّر البيانات صراحةً عبر Arrow أو الملفات.

<div id="implemented-functionality">
  ## الوظائف المُنفَّذة
</div>

تشير `ليس بعد` إلى قدرة في برنامج تشغيل ADBC يمكن إضافتها لاحقًا. وتشير `غير منطبق` إلى ميزة لا تتوافق مع نموذج التنفيذ الحالي في chDB أو ClickHouse.

<div id="database">
  ### قاعدة البيانات
</div>

| الدالة                                 | الحالة | ملاحظات                               |
| -------------------------------------- | ------ | ------------------------------------- |
| `AdbcDatabaseNew` / `Init` / `Release` | مدعومة |                                       |
| `AdbcDatabaseSetOption`                | مدعومة | خيارات المحرك `uri` و`path` و`chdb.*` |

<div id="connection">
  ### الاتصال
</div>

| الدالة                                   | الحالة    | ملاحظات                                                                                        |
| ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------------- |
| `AdbcConnectionNew` / `Init` / `Release` | مدعوم     |                                                                                                |
| `AdbcConnectionGetInfo`                  | مدعوم     |                                                                                                |
| `AdbcConnectionGetObjects`               | مدعوم     | جميع المستويات                                                                                 |
| `AdbcConnectionGetTableSchema`           | مدعوم     |                                                                                                |
| `AdbcConnectionGetTableTypes`            | مدعوم     |                                                                                                |
| `AdbcConnectionGetOption`                | مدعوم     | يتضمن قيمة `db_schema` الحالية                                                                 |
| `AdbcConnectionSetOption`                | جزئي      | يجب أن يظل الالتزام التلقائي مفعّلًا؛ ولا يمكن تغيير `db_schema`                               |
| `AdbcConnectionCommit` / `Rollback`      | غير منطبق | تُنفَّذ عبارات ClickHouse بالالتزام التلقائي؛ ولا توجد معاملة تقليدية لتأكيدها أو التراجع عنها |
| `AdbcConnectionGetStatistics`            | ليس بعد   | لا يتيح برنامج التشغيل إحصاءات الجداول                                                         |
| `AdbcConnectionReadPartition`            | غير منطبق | لا يُنتج برنامج التشغيل أقسام نتائج موزعة                                                      |
| `AdbcConnectionCancel`                   | ليس بعد   | لم يُتح بعد إلغاء استعلامات chDB عبر ADBC                                                      |

<div id="statement">
  ### عبارة SQL
</div>

| الدالة                             | الحالة    | ملاحظات                                           |
| ---------------------------------- | --------- | ------------------------------------------------- |
| `AdbcStatementNew` / `Release`     | مدعوم     |                                                   |
| `AdbcStatementSetSqlQuery`         | مدعوم     | ClickHouse SQL                                    |
| `AdbcStatementPrepare`             | مدعوم     |                                                   |
| `AdbcStatementBind` / `BindStream` | مدعوم     | معلمات موضعية `?`                                 |
| `AdbcStatementGetParameterSchema`  | مدعوم     |                                                   |
| `AdbcStatementExecuteQuery`        | مدعوم     | يبث دفعات سجلات Arrow                             |
| `AdbcStatementSetOption`           | مدعوم     | استيعاب مجمّع للبيانات، انظر أدناه                |
| `AdbcStatementExecuteSchema`       | ليس بعد   | مخطط النتيجة متاح حاليًا بعد التنفيذ              |
| `AdbcStatementExecutePartitions`   | غير منطبق | تُعاد النتائج كتدفق Arrow داخل العملية            |
| `AdbcStatementSetSubstraitPlan`    | غير منطبق | يقبل chDB ‏ClickHouse SQL، وليس خطط Substrait     |
| `AdbcStatementCancel`              | ليس بعد   | لم تُتح إمكانية إلغاء استعلامات chDB عبر ADBC بعد |

يدعم الاستيعاب المجمّع للبيانات أوضاع `create` و`append` و`create_append` و`replace`، في قاعدة البيانات الافتراضية أو قاعدة بيانات مُسمّاة.

<div id="clickhouse-sql-and-type-behavior">
  ## ClickHouse SQL وسلوك الأنواع
</div>

يستخدم chDB ‏ClickHouse SQL ونظام الأنواع الخاص به. تنطبق أيضًا دلالات ClickHouse التالية عند الوصول إلى chDB عبر ADBC:

* لا تقبل الأعمدة القيمة NULL ما لم يُصرَّح عنها باستخدام `Nullable(...)`. وتُخزَّن قيمة NULL محددة النوع والمربوطة بعمود `String` عادي كسلسلة فارغة، وليس كـ NULL.
* استخدم اقتباس المعرّفات في ClickHouse؛ وتستخدم الأمثلة علامات الاقتباس الخلفية.
* تقابل قواعد بيانات ClickHouse ‏`db_schema` في ADBC. ولا توجد طبقة catalog فوقها، لذا لا تنطبق العمليات ضمن نطاق catalog.
* لا يقبل `Decimal` مقاييس سالبة، ويغطي `Date32` الفترة من 1900-01-01 إلى 2299-12-31.
* يُفسَّر `DateTime64` الذي لا يتضمن منطقة زمنية وفق المنطقة الزمنية للمحرك.
* لا يمثّل إخراج Arrow الحالي من ClickHouse النوع `Time`، لذا لا يمكن قراءته مجددًا عبر ADBC.

تحافظ بعض أنواع Arrow على قيمها، لكنها تُقرأ مجددًا كنوع Arrow مختلف:

| نوع Arrow                                       | يُخزَّن كـ       | يُقرأ مجددًا كـ     |
| ----------------------------------------------- | ---------------- | ------------------- |
| `binary`, `large_binary`, `binary_view`         | `String`         | `string`            |
| `fixed_size_binary` (إدخال مجمّع إلى جدول جديد) | `FixedString(n)` | `fixed_size_binary` |
| `large_string`, `string_view`                   | `String`         | `string`            |
| `float16`                                       | `Float32`        | `float`             |
| `time32` / `time64` / `timestamp`               | `DateTime64(n)`  | `timestamp`         |

تُخزَّن البيانات الثنائية كـ `String` وتُقرأ مجددًا بصيغة UTF-8. لذلك، لا تُدعم الحمولات غير الصالحة بترميز UTF-8 كقيم `binary` يمكن استرجاعها دون فقدان بيانات.

<div id="examples">
  ## أمثلة
</div>

<div id="bulk-ingestion">
  ### الاستيعاب المجمّع من Arrow
</div>

```python theme={null}
import pyarrow as pa
from adbc_driver_manager import dbapi

table = pa.table({"id": [1, 2, 3], "name": ["a", "b", "c"]})

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.adbc_ingest("events", table, mode="create")
        cur.execute("SELECT count() FROM events")
        print(cur.fetchone())
```

<div id="parameters">
  ### المَعلمات
</div>

```python theme={null}
from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(10) WHERE number > ?", (7,))
        print(cur.fetch_arrow_table())
```

<div id="c-example">
  ### C
</div>

بعد تنفيذ `dbc install chdb`، يستطيع مدير برامج التشغيل في C العثور على برنامج التشغيل بالاسم:

```c theme={null}
#include <arrow-adbc/adbc.h>
#include <arrow-adbc/adbc_driver_manager.h>

struct AdbcDatabase database = {0};
struct AdbcError error = {0};

AdbcDatabaseNew(&database, &error);
AdbcDatabaseSetOption(&database, "driver", "chdb", &error);
AdbcDatabaseSetOption(&database, "uri", "chdb://", &error);
AdbcDatabaseInit(&database, &error);
```

<div id="verification">
  ## كيفية التحقق من برنامج التشغيل
</div>

تشغّل إصدارات chDB ADBC مجموعتين خارجيتين لاختبار برنامج التشغيل الأصلي على Linux x86-64 وarm64، وعلى macOS x86-64 وarm64:

* مجموعة اختبار التوافق Apache Arrow ADBC، التي تتحقق من عقد C
* مجموعة التحقق ADBC Driver Foundry، التي تتحقق من السلوك على مستوى SQL، وتحويلات الأنواع ذهابًا وإيابًا، والبيانات الوصفية، والاستيعاب المجمّع

تستند جداول الدعم في هذه الصفحة إلى نتائج عمليات التشغيل هذه. توجد المجموعتان في [مستودع chdb-core](https://github.com/chdb-io/chdb-core/tree/main/programs/local/adbc/validation).