يُعد ClickHouse Connect برنامج تشغيل أساسيًا لقواعد البيانات، ويوفّر التوافق مع مجموعة واسعة من تطبيقات بايثون.
- الواجهة الرئيسية هي الكائن
Client في الحزمة clickhouse_connect.driver. وتتضمن هذه الحزمة الأساسية أيضًا فئات مساعدة متنوعة ودوال خدمية تُستخدم للتواصل مع خادم ClickHouse، بالإضافة إلى تطبيقات “context” لإدارة استعلامات insert و select المتقدمة.
- توفّر الحزمة
clickhouse_connect.datatypes تنفيذًا أساسيًا وفئات فرعية لجميع أنواع بيانات ClickHouse غير التجريبية. وتتمثل وظيفتها الأساسية في تسلسل بيانات ClickHouse وإلغاء تسلسلها إلى التنسيق الثنائي العمودي “Native” الخاص بـ ClickHouse، والمستخدَم لتحقيق أعلى كفاءة ممكنة في نقل البيانات بين ClickHouse وتطبيقات العميل.
- تعمل فئات Cython/C في الحزمة
clickhouse_connect.cdriver على تحسين بعض أكثر عمليات التسلسل وإلغاء التسلسل شيوعًا، ما يوفّر أداءً أفضل بكثير مقارنةً ببايثون الخالص.
- تتوفر لهجة SQLAlchemy في الحزمة
clickhouse_connect.cc_sqlalchemy، وهي مبنية على حزمتَي datatypes و dbi. ويدعم هذا التنفيذ إمكانات SQLAlchemy Core، بما في ذلك استعلامات SELECT مع JOIN (INNER, LEFT OUTER, FULL OUTER, CROSS)، وعبارات WHERE، وORDER BY، وLIMIT/OFFSET، وعمليات DISTINCT، وعبارات DELETE خفيفة الوزن مع شروط WHERE، وانعكاس الجداول، وعمليات DDL الأساسية (CREATE TABLE, CREATE/DROP DATABASE). ورغم أنه لا يدعم ميزات ORM المتقدمة أو ميزات DDL المتقدمة، فإنه يوفّر إمكانات استعلام قوية مناسبة لمعظم أعباء العمل التحليلية على قاعدة بيانات ClickHouse الموجّهة إلى OLAP.
- يُعد برنامج التشغيل الأساسي وتنفيذ ClickHouse Connect SQLAlchemy الطريقة المفضلة لربط ClickHouse بـ Apache Superset. استخدم اتصال قاعدة البيانات
ClickHouse Connect أو سلسلة اتصال لهجة SQLAlchemy clickhousedb.
هذه الوثائق محدَّثة حتى إصدار clickhouse-connect 0.9.2.
يستخدم برنامج تشغيل ClickHouse Connect الرسمي لبايثون بروتوكول HTTP للتواصل مع خادم ClickHouse. يوفّر ذلك دعمًا لموازن تحميل HTTP، ويعمل بكفاءة في بيئات المؤسسات التي تستخدم جدران الحماية والوكلاء، لكنه يقدّم ضغطًا وأداءً أقل قليلًا مقارنةً بالبروتوكول الأصلي المعتمد على TCP، كما لا يدعم بعض الميزات المتقدمة مثل إلغاء الاستعلامات. وفي بعض حالات الاستخدام، قد ترغب في استخدام أحد برامج تشغيل بايثون المجتمعية التي تستخدم البروتوكول الأصلي المعتمد على TCP. | بايثون | | المنصة¹ | | ClickHouse | | SQLAlchemy² | | Apache Superset | | Pandas | | Polars | |
|---|
| 2.x, <3.9 | ❌ | Linux (x86) | ✅ | <25.x³ | 🟡 | <1.4.40 | ❌ | <1.4 | ❌ | ≥1.5 | ✅ | 1.x | ✅ |
| 3.9.x | ✅ | Linux (Aarch64) | ✅ | 25.x³ | 🟡 | ≥1.4.40 | ✅ | 1.4.x | ✅ | 2.x | ✅ | | |
| 3.10.x | ✅ | macOS (x86) | ✅ | 25.3.x (LTS) | ✅ | ≥2.x | ✅ | 1.5.x | ✅ | | | | |
| 3.11.x | ✅ | macOS (ARM) | ✅ | 25.6.x (مستقرة) | ✅ | | | 2.0.x | ✅ | | | | |
| 3.12.x | ✅ | Windows | ✅ | 25.7.x (مستقرة) | ✅ | | | 2.1.x | ✅ | | | | |
| 3.13.x | ✅ | | | 25.8.x (LTS) | ✅ | | | 3.0.x | ✅ | | | | |
| | | | 25.9.x (مستقرة) | ✅ | | | | | | | | |
cibuildwheel الممتاز. وأخيرًا، بما أن ClickHouse Connect يمكنه أيضًا العمل كبرنامج بايثون خالص، فمن المفترض أن يعمل التثبيت من المصدر على أي تثبيت حديث لـ بايثون.
²يقتصر دعم SQLAlchemy على وظائف Core (الاستعلامات وDDL الأساسية). ميزات ORM غير مدعومة. راجع وثائق SQLAlchemy Integration Support لمزيد من التفاصيل.
³يعمل ClickHouse Connect عمومًا بشكل جيد مع الإصدارات الواقعة خارج النطاق المدعوم رسميًا.
ثبّت ClickHouse Connect من PyPI باستخدام pip:
pip install clickhouse-connect
يمكن أيضًا تثبيت ClickHouse Connect من المصدر:
- نفّذ
git clone لـ مستودع GitHub.
- (اختياري) شغّل
pip install cython لبناء تحسينات C/Cython وتمكينها
- انتقل باستخدام
cd إلى الدليل الجذر للمشروع ثم شغّل pip install .
يرجى التحديث إلى أحدث إصدار من ClickHouse Connect قبل الإبلاغ عن أي مشكلات. يجب تقديم المشكلات في مشروع GitHub. ومن المتوقع أن تكون الإصدارات المستقبلية من ClickHouse Connect متوافقة مع إصدارات ClickHouse المدعومة رسميًا وقت الإصدار. ويمكن العثور على الإصدارات المدعومة حاليًا من خادم ClickHouse هنا. إذا لم تكن متأكدًا من إصدار خادم ClickHouse الذي ينبغي استخدامه، فاقرأ هذه المناقشة هنا. وتختبر مصفوفة اختبارات CI لدينا أحدث إصدارين من إصدارات LTS وأحدث ثلاثة إصدارات مستقرة. ومع ذلك، وبسبب بروتوكول HTTP والحد الأدنى من التغييرات غير المتوافقة بين إصدارات ClickHouse، فإن ClickHouse Connect يعمل عمومًا بشكل جيد مع إصدارات الخادم الواقعة خارج النطاق المدعوم رسميًا، مع أن التوافق مع بعض أنواع البيانات المتقدمة قد يختلف.
اجمع بيانات الاتصال الخاصة بك
| المعلمات | الوصف |
|---|
HOST and PORT | عادةً ما يكون المنفذ 8443 عند استخدام TLS، أو 8123 عند عدم استخدام TLS. |
DATABASE NAME | افتراضيًا، توجد قاعدة بيانات باسم default. استخدم اسم قاعدة البيانات التي تريد الاتصال بها. |
USERNAME and PASSWORD | افتراضيًا، يكون اسم المستخدم default. استخدم اسم المستخدم المناسب لحالة الاستخدام لديك. |
curl.
إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيُحدِّد مسؤول ClickHouse لديك تفاصيل الاتصال.
فيما يلي مثالان للاتصال بـ ClickHouse:
- الاتصال بخادم ClickHouse على localhost.
- الاتصال بخدمة ClickHouse Cloud.
استخدم مثيل عميل ClickHouse Connect للاتصال بخادم ClickHouse على localhost:
import clickhouse_connect
client = clickhouse_connect.get_client(host='localhost', username='default', password='password')
استخدم مثيل عميل ClickHouse Connect للاتصال بخدمة ClickHouse Cloud:
استخدم تفاصيل الاتصال التي جُمعت سابقًا. تتطلب خدمات ClickHouse Cloud استخدام TLS، لذا استخدم المنفذ 8443.
import clickhouse_connect
client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')
التفاعل مع قاعدة البيانات
command في client:
client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')
insert في العميل مع مصفوفة ثنائية الأبعاد من الصفوف والقيم:
row1 = [1000, 'String Value 1000', 5.233]
row2 = [2000, 'String Value 2000', -107.04]
data = [row1, row2]
client.insert('new_table', data, column_names=['key', 'value', 'metric'])
query الخاصة بالعميل:
result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# Output: [(2000, -50.9035)]
