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

ADBC هي واجهة برمجة تطبيقات مستقلة عن المورّد لنقل بيانات Arrow بين تطبيق وقاعدة بيانات. يُوزَّع برنامج تشغيل chDB ADBC عبر ADBC Driver Foundry، ويمكن تحميله باستخدام أي مدير لبرامج تشغيل ADBC.

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

ثبّت برنامج التشغيل من مستودع ADBC Driver Foundry باستخدام dbc:

dbc install chdb

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

dbc search -v chdb

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

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

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

pip install adbc-driver-manager pyarrow

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

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())

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

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

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

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

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

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

يستخدم 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 مختلف:

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

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())

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())

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

#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);

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

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

تستند جداول الدعم في هذه الصفحة إلى نتائج عمليات التشغيل هذه. توجد المجموعتان في مستودع chdb-core.