Skip to main content
يوفر برنامج تشغيل ClickHouse ODBC واجهة متوافقة مع المعايير لربط التطبيقات المتوافقة مع ODBC بـ ClickHouse. وهو يطبق واجهة برمجة تطبيقات ODBC، ويتيح للتطبيقات وأدوات ذكاء الأعمال وبيئات البرمجة النصية تنفيذ استعلامات SQL واسترداد النتائج والتفاعل مع ClickHouse بآليات مألوفة. يتواصل برنامج التشغيل مع خادم ClickHouse باستخدام بروتوكول HTTP، وهو البروتوكول الرئيسي المدعوم في جميع عمليات نشر ClickHouse. يتيح ذلك لبرنامج التشغيل العمل بصورة متسقة في بيئات متنوعة، بما في ذلك التثبيتات المحلية والخدمات السحابية المُدارة والبيئات التي لا يتوفر فيها سوى الوصول المستند إلى HTTP. تتوفر شيفرة مصدر برنامج التشغيل في مستودع ClickHouse-ODBC على GitHub.
لتحسين التوافق، نوصي بشدة بتحديث خادم ClickHouse إلى الإصدار 24.11 أو إصدار أحدث.
برنامج التشغيل هذا قيد التطوير النشط. قد لا تكون بعض ميزات ODBC مطبقة بالكامل بعد. يركز الإصدار الحالي على توفير الاتصال الأساسي والوظائف الأساسية لـ ODBC، مع التخطيط لإضافة ميزات أخرى في الإصدارات المستقبلية.ملاحظاتك قيّمة للغاية وتساعد في تحديد أولويات الميزات والتحسينات الجديدة. إذا واجهت قيوداً أو وظائف مفقودة أو سلوكاً غير متوقع، فيرجى مشاركة ملاحظاتك أو طلبات الميزات عبر متتبع المشكلات على https://github.com/ClickHouse/clickhouse-odbc/issues

التثبيت على Windows

يمكنك العثور على أحدث إصدار من برنامج التشغيل على https://github.com/ClickHouse/clickhouse-odbc/releases/latest. ومن هناك، يمكنك تنزيل مُثبّت MSI وتشغيله، ثم اتباع خطوات التثبيت البسيطة.

الاختبار

يمكنك اختبار برنامج التشغيل بتشغيل برنامج PowerShell النصي البسيط هذا. انسخ النص أدناه، واضبط URL واسم المستخدم وكلمة المرور، ثم الصقه في موجّه أوامر PowerShell — بعد تشغيل $reader.GetValue(0)، ينبغي أن يظهر إصدار خادم ClickHouse لديك.

معلمات التكوين

تمثل المعلمات التالية الإعدادات الأكثر شيوعًا لإنشاء اتصال ببرنامج تشغيل ClickHouse ODBC. وهي تغطي خيارات المصادقة الأساسية وسلوك الاتصال ومعالجة البيانات. تتوفر قائمة كاملة بالمعلمات المدعومة في صفحة GitHub الخاصة بالمشروع https://github.com/ClickHouse/clickhouse-odbc.
  • Url: تحدد نقطة نهاية HTTP(S) الكاملة لخادم ClickHouse، بما في ذلك البروتوكول والمضيف والمنفذ والمسار الاختياري.
  • Username: اسم المستخدم المستخدَم للمصادقة لدى خادم ClickHouse.
  • Password: كلمة المرور المرتبطة باسم المستخدم المحدد. إذا لم تُوفَّر، يتصل برنامج التشغيل دون مصادقة بكلمة مرور.
  • Database: قاعدة البيانات الافتراضية التي تُستخدم للاتصال.
  • Timeout: المدة القصوى (بالثواني) التي ينتظر فيها برنامج التشغيل استجابة الخادم قبل إلغاء الطلب.
  • ClientName: معرّف مخصص يُرسل إلى خادم ClickHouse ضمن البيانات الوصفية للعميل. وهو مفيد للتتبع أو لتمييز حركة المرور الواردة من تطبيقات مختلفة. ستكون هذه المعلمة جزءًا من ترويسة User-Agent في طلبات HTTP التي ينشئها برنامج التشغيل.
  • Compression: يفعّل أو يعطّل ضغط HTTP لحمولات الطلبات والاستجابات. وعند تفعيله، يمكنه تقليل استخدام النطاق الترددي وتحسين الأداء لمجموعات النتائج الكبيرة.
  • SqlCompatibilitySettings: يفعّل إعدادات استعلام تجعل ClickHouse يتصرف بصورة أقرب إلى قاعدة بيانات علائقية تقليدية. يفيد ذلك عندما تُنشأ الاستعلامات تلقائيًا بواسطة أدوات خارجية، مثل Power BI. فعادةً لا تكون هذه الأدوات على دراية ببعض السلوكيات الخاصة بـ ClickHouse، وقد تُنتج استعلامات تؤدي إلى أخطاء أو نتائج غير متوقعة. راجع إعدادات ClickHouse المستخدمة بواسطة معلمة التكوين SqlCompatibilitySettings لمزيد من التفاصيل.
فيما يلي بعض الأمثلة على سلسلة الاتصال الكاملة التي تُمرَّر إلى برنامج التشغيل لإعداد اتصال.
  • خادم ClickHouse مثبّت محليًا على مثيل WSL
  • مثيل من ClickHouse Cloud.

تكامل Microsoft Power BI

يمكنك استخدام برنامج تشغيل ODBC لتوصيل Microsoft Power BI بخادم ClickHouse. يوفر Power BI خياري اتصال: موصل ODBC العام وموصل ClickHouse، وكلاهما متاح ضمن تثبيتات Power BI القياسية. يعتمد كلا الموصلين داخليًا على ODBC، إلا أنهما يختلفان في الإمكانات:
  • موصل ClickHouse (موصى به) يستخدم ODBC في الخلفية، لكنه يدعم وضع DirectQuery. في هذا الوضع، يُنشئ Power BI استعلامات SQL تلقائيًا ولا يسترجع سوى البيانات اللازمة لكل عملية تصور أو تصفية.
  • موصل ODBC لا يدعم إلا وضع Import. ينفذ Power BI الاستعلام الذي يحدده المستخدم (أو يختار الجدول بالكامل) ويستورد مجموعة النتائج كاملةً إلى Power BI. وتعمد عمليات التحديث اللاحقة إلى إعادة استيراد مجموعة البيانات بالكامل.
اختر الموصل وفقًا لحالة الاستخدام. يناسب DirectQuery لوحات المعلومات التفاعلية ذات مجموعات البيانات الكبيرة. اختر وضع Import عندما تحتاج إلى نسخ محلية كاملة من البيانات. لمزيد من المعلومات حول تكامل Microsoft Power BI مع ClickHouse، راجع صفحة وثائق ClickHouse حول تكامل Power BI.

إعدادات توافق SQL

لدى ClickHouse لهجة SQL فريدة خاصة به، وقد يختلف سلوكه في بعض الحالات عن قواعد البيانات الأخرى، مثل MS SQL Server أو MySQL أو PostgreSQL. وغالبًا ما تمثل هذه الاختلافات ميزة، إذ توفر بنية محسّنة تسهّل استخدام ميزات ClickHouse. ومع ذلك، يُستخدم برنامج تشغيل ODBC غالبًا في بيئات تُنشأ فيها الاستعلامات بواسطة أدوات خارجية، مثل Power BI، بدلًا من أن يكتبها المستخدمون. وتعتمد هذه الاستعلامات عادةً على مجموعة فرعية محدودة من معيار SQL. في مثل هذه الحالات، قد لا تعمل اختلافات ClickHouse عن معيار SQL كما هو متوقع، وقد تؤدي إلى نتائج أو أخطاء غير متوقعة. يوفر برنامج تشغيل ODBC معلمة تكوين إضافية، SqlCompatibilitySettings، تتيح ضبط إعدادات محددة للاستعلامات بما يجعل سلوك ClickHouse أقرب إلى SQL القياسية.

إعدادات ClickHouse التي تفعّلها معلمة التكوين SqlCompatibilitySettings

يوضح هذا القسم الإعدادات التي يعدّلها برنامج تشغيل ODBC وأسباب ذلك. cast_keep_nullable افتراضيًا، لا يسمح ClickHouse بتحويل الأنواع القابلة لـ NULL إلى أنواع غير قابلة لـ NULL. ومع ذلك، لا تميّز العديد من أدوات ذكاء الأعمال بين الأنواع القابلة لـ NULL وغير القابلة لـ NULL عند إجراء تحويلات الأنواع. لذلك، ليس من غير المألوف رؤية استعلامات مثل الآتي تنشئها أدوات ذكاء الأعمال:
افتراضيًا، إذا كان العمود value قابلاً للقيم الفارغة، فسيفشل هذا الاستعلام بالرسالة التالية:
يغيّر تمكين cast_keep_nullable سلوك CAST بحيث يحافظ على قابلية القيم الوسيطة لأن تكون NULL. وهذا يجعل سلوك ClickHouse أقرب إلى سلوك قواعد البيانات الأخرى ومعيار SQL في هذا النوع من التحويل. prefer_column_name_to_alias يتيح ClickHouse الإشارة إلى التعبيرات في قائمة SELECT نفسها باستخدام أسمائها المستعارة. على سبيل المثال، يتجنب هذا الاستعلام التكرار ويسهل كتابته:
تُستخدم هذه الميزة على نطاق واسع، لكن قواعد البيانات الأخرى لا تحلّ الأسماء المستعارة بهذه الطريقة عادةً في قائمة SELECT نفسها، ولذلك ستؤدي مثل هذه الاستعلامات إلى خطأ. وتظهر المشكلات بوضوح أكبر عندما يكون للاسم المستعار الاسم نفسه لعمود. على سبيل المثال:
أيّ value ينبغي أن تُجمِّعه avg(value)؟ افتراضيًا، يفضّل ClickHouse الاسم المستعار، ما يحوّل ذلك فعليًا إلى تجميع متداخل، وهو ما لا تتوقعه معظم الأدوات. نادراً ما يشكّل ذلك مشكلة بحد ذاته، لكن بعض أدوات ذكاء الأعمال تنشئ استعلامات تتضمن استعلامات فرعية تعيد استخدام الأسماء المستعارة للأعمدة. على سبيل المثال، غالبًا ما ينشئ Power BI استعلامات مشابهة لما يلي:
قد يؤدي استخدام C1 إلى ظهور الخطأ التالي:
لا تحلّ قواعد البيانات الأخرى عادةً الأسماء المستعارة في المستوى نفسه بهذه الطريقة، بل تتعامل مع C1 على أنه عمود من الاستعلام الفرعي. وللمحافظة على سلوك مماثل في ClickHouse والسماح بتشغيل هذه الاستعلامات دون أخطاء، يفعّل برنامج التشغيل ODBC الإعداد prefer_column_name_to_alias. في معظم الحالات، لا ينبغي أن يسبب تفعيل هذه الإعدادات مشكلة. لكن المستخدمين الذين ضُبط لديهم إعداد readonly على 1 لا يمكنهم تغيير أي إعدادات، حتى في استعلامات SELECT. وبالنسبة إلى هؤلاء المستخدمين، سيؤدي تفعيل SqlCompatibilitySettings إلى خطأ. يوضح القسم التالي كيفية جعل معلمة التكوين هذه تعمل للمستخدمين ذوي صلاحية القراءة فقط.

تفعيل إعدادات توافق SQL للمستخدمين ذوي صلاحية القراءة فقط

عند الاتصال بـ ClickHouse عبر برنامج تشغيل ODBC مع تمكين المعلمة SqlCompatibilitySettings، سيواجه المستخدم الذي ضُبط إعداد readonly لديه على 1 خطأً لأن برنامج التشغيل يحاول تعديل إعدادات الاستعلام:
يحدث ذلك لأن المستخدمين في وضع القراءة فقط لا يُسمح لهم بتغيير الإعدادات، حتى في استعلامات SELECT الفردية. هناك عدة طرق لمعالجة ذلك. الخيار 1: ضبط readonly على 2 هذا هو الخيار الأبسط. يتيح ضبط readonly على 2 تغيير الإعدادات مع إبقاء المستخدم في وضع القراءة فقط.
في معظم الحالات، يُعد ضبط readonly على 2 أسهل طريقة موصى بها لحل هذه المشكلة. إذا لم ينجح ذلك، فاستخدم الخيار الثاني. الخيار 2. تغيير إعدادات المستخدم لتتوافق مع الإعدادات التي يعيّنها برنامج تشغيل ODBC. هذا الخيار بسيط أيضًا: حدّث إعدادات المستخدم لتتوافق مسبقًا مع ما يحاول برنامج تشغيل ODBC تعيينه.
مع هذا التغيير، يظل بإمكان برنامج تشغيل ODBC محاولة تطبيق الإعدادات، ولكن بما أن القيم متطابقة بالفعل، فلا يُجرى أي تغيير فعلي ويُتجنب الخطأ. هذا الخيار بسيط أيضًا، لكنه يتطلب صيانة: فقد تغيّر إصدارات برنامج التشغيل الأحدث قائمة الإعدادات أو تضيف إعدادات جديدة للتوافق. إذا عيّنت هذه الإعدادات صراحةً لمستخدم ODBC، فقد تحتاج إلى تحديثها كلما بدأ برنامج تشغيل ODBC بتطبيق إعدادات إضافية.
آخر تعديل في ١٨ أغسطس ٢٠٢٦