Skip to main content
يُعد ClickHouse Connect برنامج تشغيل أساسيًا لقواعد البيانات، ويوفّر توافقًا تشغيليًا مع مجموعة واسعة من تطبيقات بايثون.
  • الواجهات الرئيسية هي Client المتزامن وAsyncClient الأصلي المعتمد على aiohttp ضمن clickhouse_connect.driver. كما توفّر حزمة برنامج التشغيل سياقات الاستعلام والإدراج، ومساعدات البث، ودعم DB-API، وطرق HTTP منخفضة المستوى.
  • تتولى حزمة clickhouse_connect.datatypes تسلسل أنواع ClickHouse وإلغاء تسلسلها باستخدام التنسيق الثنائي العمودي الأصلي لـ ClickHouse.
  • تُسرّع امتدادات Cython الاختيارية في clickhouse_connect.driverc مسارات التسلسل والتحويل والتخزين المؤقت الشائعة. ويظل مسار بايثون خالص متاحًا على المنصات التي يتعذر فيها بناء هذه الامتدادات.
  • تتضمن الحزمة معلومات الأنواع وفق PEP 561، بحيث تتمكن أدوات التحقق من الأنواع اللاحقة من استخدام التعليقات التوضيحية الخاصة بالواجهات العامة لبرنامج التشغيل وDB-API وSQLAlchemy.
  • تدعم لهجة SQLAlchemy في clickhouse_connect.cc_sqlalchemy واجهة SQLAlchemy Core، وانعكاس المخطط، وبنود الاستعلام ومحركات الجداول الخاصة بـ ClickHouse، وعمليات ترحيل Alembic. تعمل عمليات قراءة ORM الأساسية وعمليات الإدراج، لكن هذه اللهجة مصممة لأعباء العمل التحليلية لا لسلوك ORM الكامل القائم على وحدة العمل.
  • يُعد برنامج التشغيل الأساسي وتنفيذ ClickHouse Connect SQLAlchemy الطريقة المفضلة لربط ClickHouse مع Apache Superset. استخدم اتصال قاعدة البيانات ClickHouse Connect أو سلسلة اتصال لهجة SQLAlchemy ‏clickhousedb.
هذه الوثائق محدثة حتى الإصدار clickhouse-connect 1.6.0. إذا كنت تُجري ترقية من 0.15.x أو إصدار أقدم، فراجع دليل الترحيل 1.0.
تستخدم برامج ClickHouse Connect العميلة القياسية واجهة HTTP. ويدعم ذلك موازنات تحميل HTTP والوكيلات وضوابط الشبكات المؤسسية الشائعة. كما يوفّر ClickHouse Connect أيضًا واجهة خلفية chDB تجريبية تعمل داخل العملية.

المتطلبات والتوافق

تتضمن الحزمة حزم wheel مُصرَّفة حيثما كانت متاحة، وتلجأ إلى تنفيذ ببايثون خالص عندما يتعذر بناء امتدادات Cython. ‏PyArrow مدعوم على بايثون من 3.10 إلى 3.14. يتطلب بايثون 3.14 إصدار PyArrow 22 أو أحدث.

التثبيت

ثبّت ClickHouse Connect من PyPI عبر pip:
تُثبَّت عمليات التكامل الاختيارية عبر الحزم الإضافية:
يمكن أيضًا تثبيت ClickHouse Connect من المصدر:
  • نفّذ git clone لـ مستودع GitHub.
  • انتقل إلى جذر المشروع وشغّل pip install .. يثبّت نظام البناء Cython تلقائيًا لتجميع امتدادات C الاختيارية.
يمكن الوصول إلى الإصدار المثبّت عبر clickhouse_connect.__version__.

سياسة الدعم

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

الاستخدام الأساسي

اجمع بيانات الاتصال الخاصة بك

للاتصال بـ ClickHouse باستخدام HTTP(S)، تحتاج إلى المعلومات التالية: تتوفر تفاصيل خدمة ClickHouse Cloud الخاصة بك في ClickHouse Cloud console. حدِّد خدمة ثم انقر على Connect:
زر Connect لخدمة ClickHouse Cloud
اختر HTTPS. ستظهر تفاصيل الاتصال في مثال لأمر curl.
تفاصيل اتصال HTTPS لخدمة ClickHouse Cloud
إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيُحدِّد مسؤول ClickHouse لديك تفاصيل الاتصال.

إنشاء اتصال

فيما يلي مثالان للاتصال بـ ClickHouse:
  • الاتصال بخادم ClickHouse على localhost.
  • الاتصال بخدمة ClickHouse Cloud.

استخدم مثيل عميل ClickHouse Connect للاتصال بخادم ClickHouse على localhost:

استخدم مثيل عميل ClickHouse Connect للاتصال بخدمة ClickHouse Cloud:

استخدم تفاصيل الاتصال التي جُمعت سابقًا. تتطلب خدمات ClickHouse Cloud استخدام TLS، لذا استخدم المنفذ 8443.

التفاعل مع قاعدة البيانات

لتنفيذ أمر في ClickHouse SQL، استخدم طريقة ‏command الخاصة بالعميل:
لإدراج البيانات على دفعات، استخدم الطريقة insert الخاصة بالعميل مع مصفوفة ثنائية الأبعاد من الصفوف والقيم:
لاسترداد البيانات باستخدام ClickHouse SQL، استخدم الطريقة query الخاصة بالعميل:

الواجهة الخلفية المضمّنة لـ chDB

تُشغِّل الواجهة الخلفية التجريبية لـ chDB استعلامات ClickHouse داخل عملية بايثون من دون خادم HTTP. ثبّت الإضافة chdb، ثم اختر الواجهة الخلفية باستخدام interface="chdb" أو عبر chdb:// DSN:
قاعدة البيانات الافتراضية تكون في الذاكرة. مرِّر path="/data/my_chdb" أو استخدم dsn="chdb:///data/my_chdb" للتخزين الدائم. يتيح chDB مسار engine واحدًا لكل عملية. ولا يدعم العميل غير المتزامن أو البيانات الخارجية.
آخر تعديل في ١٤ أغسطس ٢٠٢٦