> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> وثائق برنامج تشغيل ClickHouse ODBC

# برنامج تشغيل ODBC

يوفر برنامج تشغيل ClickHouse ODBC واجهة متوافقة مع المعايير لربط التطبيقات المتوافقة مع ODBC بـ
ClickHouse. وهو يطبق واجهة برمجة تطبيقات ODBC، ويتيح للتطبيقات وأدوات ذكاء الأعمال وبيئات البرمجة النصية تنفيذ استعلامات SQL
واسترداد النتائج والتفاعل مع ClickHouse بآليات مألوفة.

يتواصل برنامج التشغيل مع خادم ClickHouse باستخدام [بروتوكول HTTP](/ar/concepts/features/interfaces/http)، وهو البروتوكول
الرئيسي المدعوم في جميع عمليات نشر ClickHouse. يتيح ذلك لبرنامج التشغيل العمل بصورة متسقة في بيئات متنوعة،
بما في ذلك التثبيتات المحلية والخدمات السحابية المُدارة والبيئات التي لا يتوفر فيها سوى الوصول المستند إلى HTTP.

تتوفر شيفرة مصدر برنامج التشغيل في
[مستودع ClickHouse-ODBC على GitHub](https://github.com/ClickHouse/clickhouse-odbc).

<Tip>
  لتحسين التوافق، نوصي بشدة بتحديث خادم ClickHouse إلى الإصدار 24.11 أو إصدار أحدث.
</Tip>

<Note>
  برنامج التشغيل هذا قيد التطوير النشط. قد لا تكون بعض ميزات ODBC مطبقة بالكامل بعد. يركز الإصدار الحالي
  على توفير الاتصال الأساسي والوظائف الأساسية لـ ODBC، مع التخطيط لإضافة ميزات أخرى في
  الإصدارات المستقبلية.

  ملاحظاتك قيّمة للغاية وتساعد في تحديد أولويات الميزات والتحسينات الجديدة. إذا واجهت
  قيوداً أو وظائف مفقودة أو سلوكاً غير متوقع، فيرجى مشاركة ملاحظاتك أو طلبات الميزات عبر
  متتبع المشكلات على
  [https://github.com/ClickHouse/clickhouse-odbc/issues](https://github.com/ClickHouse/clickhouse-odbc/issues)
</Note>

<div id="installation-on-windows">
  ## التثبيت على Windows
</div>

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

<div id="testing">
  ## الاختبار
</div>

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

```powershell theme={null}
$url = "http://127.0.0.1:8123/"
$username = "default"
$password = ""
$conn = New-Object System.Data.Odbc.OdbcConnection("`
    Driver={ClickHouse ODBC Driver (Unicode)};`
    Url=$url;`
    Username=$username;`
    Password=$password")
$conn.Open()
$cmd = $conn.CreateCommand()
$cmd.CommandText = "select version()"
$reader = $cmd.ExecuteReader()
$reader.Read()
$reader.GetValue(0)
$reader.Close()
$conn.Close()
```

<div id="configuration-parameters">
  ## معلمات التكوين
</div>

تمثل المعلمات التالية الإعدادات الأكثر شيوعًا لإنشاء اتصال ببرنامج تشغيل ClickHouse ODBC.
وهي تغطي خيارات المصادقة الأساسية وسلوك الاتصال ومعالجة البيانات. تتوفر قائمة كاملة بالمعلمات المدعومة
في صفحة GitHub الخاصة بالمشروع
[https://github.com/ClickHouse/clickhouse-odbc](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
  ](#sql-compatibility-settings) لمزيد من التفاصيل.

فيما يلي بعض الأمثلة على سلسلة الاتصال الكاملة التي تُمرَّر إلى برنامج التشغيل لإعداد اتصال.

* خادم ClickHouse مثبّت محليًا على مثيل WSL

```plaintext theme={null}
Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123/;Username=default
```

* مثيل من ClickHouse Cloud.

```plaintext theme={null}
Driver={ClickHouse ODBC Driver (Unicode)};Url=https://you-instance-url.gcp.clickhouse.cloud:8443/;Username=default;Password=your-password
```

<div id="powerbi-integration">
  ## تكامل Microsoft Power BI
</div>

يمكنك استخدام برنامج تشغيل 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](/ar/integrations/connectors/data-visualization/powerbi-and-clickhouse).

<div id="sql-compatibility-settings">
  ## إعدادات توافق SQL
</div>

لدى ClickHouse لهجة SQL فريدة خاصة به، وقد يختلف سلوكه في بعض الحالات عن قواعد البيانات الأخرى، مثل MS SQL
Server أو MySQL أو PostgreSQL. وغالبًا ما تمثل هذه الاختلافات ميزة، إذ توفر بنية محسّنة تسهّل استخدام ميزات ClickHouse.

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

<div id="sql-compatibility-settings-list">
  ### إعدادات ClickHouse التي تفعّلها معلمة التكوين SqlCompatibilitySettings
</div>

يوضح هذا القسم الإعدادات التي يعدّلها برنامج تشغيل ODBC وأسباب ذلك.

**[cast\_keep\_nullable](/ar/reference/settings/session-settings/cast#cast_keep_nullable)**

افتراضيًا، لا يسمح ClickHouse بتحويل الأنواع القابلة لـ NULL إلى أنواع غير قابلة لـ NULL. ومع ذلك، لا تميّز العديد من أدوات ذكاء الأعمال بين الأنواع القابلة لـ NULL وغير القابلة لـ NULL عند إجراء تحويلات الأنواع. لذلك، ليس من غير المألوف رؤية استعلامات مثل الآتي تنشئها أدوات ذكاء الأعمال:

```sql theme={null}
SELECT sum(CAST(value, 'Int32'))
FROM values
```

افتراضيًا، إذا كان العمود `value` قابلاً للقيم الفارغة، فسيفشل هذا الاستعلام بالرسالة التالية:

```plaintext theme={null}
DB::Exception: Cannot convert NULL value to non-Nullable type: while executing 'FUNCTION CAST(__table1.value :: 2,
'Int32'_String :: 1) -> CAST(__table1.value, 'Int32'_String) Int32 : 0'. (CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN)
```

يغيّر تمكين `cast_keep_nullable` سلوك `CAST` بحيث يحافظ على قابلية القيم الوسيطة لأن تكون NULL. وهذا
يجعل سلوك ClickHouse أقرب إلى سلوك قواعد البيانات الأخرى ومعيار SQL في هذا النوع من التحويل.

**[prefer\_column\_name\_to\_alias](/ar/reference/settings/session-settings/prefer#prefer_column_name_to_alias)**

يتيح ClickHouse الإشارة إلى التعبيرات في قائمة `SELECT` نفسها باستخدام أسمائها المستعارة. على سبيل المثال، يتجنب هذا الاستعلام
التكرار ويسهل كتابته:

```sql theme={null}
SELECT
    sum(value) AS S,
    count() AS C,
    S / C
FROM test
```

تُستخدم هذه الميزة على نطاق واسع، لكن قواعد البيانات الأخرى لا تحلّ الأسماء المستعارة بهذه الطريقة عادةً في قائمة `SELECT` نفسها،
ولذلك ستؤدي مثل هذه الاستعلامات إلى خطأ. وتظهر المشكلات بوضوح أكبر عندما يكون للاسم المستعار الاسم نفسه لعمود. على سبيل المثال:

```sql theme={null}
SELECT
    sum(value) AS value,
    avg(value)
FROM test
```

أيّ `value` ينبغي أن تُجمِّعه `avg(value)`؟ افتراضيًا، يفضّل ClickHouse الاسم المستعار، ما يحوّل ذلك فعليًا إلى
تجميع متداخل، وهو ما لا تتوقعه معظم الأدوات.

نادراً ما يشكّل ذلك مشكلة بحد ذاته، لكن بعض أدوات ذكاء الأعمال تنشئ استعلامات تتضمن استعلامات فرعية تعيد استخدام الأسماء المستعارة للأعمدة. على
سبيل المثال، غالبًا ما ينشئ Power BI استعلامات مشابهة لما يلي:

```sql theme={null}
SELECT
    sum(C1) AS C1,
    count(C1) AS C2
FROM
(
    SELECT sum(value) AS C1
    FROM test
    GROUP BY group_index
) AS TBL
```

قد يؤدي استخدام `C1` إلى ظهور الخطأ التالي:

```plaintext theme={null}
Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function sum(C1) AS C1 is found
inside another aggregate function in query. (ILLEGAL_AGGREGATION)
```

لا تحلّ قواعد البيانات الأخرى عادةً الأسماء المستعارة في المستوى نفسه بهذه الطريقة، بل تتعامل مع `C1` على أنه عمود من
الاستعلام الفرعي. وللمحافظة على سلوك مماثل في ClickHouse والسماح بتشغيل هذه الاستعلامات دون أخطاء، يفعّل برنامج التشغيل ODBC
الإعداد `prefer_column_name_to_alias`.

في معظم الحالات، لا ينبغي أن يسبب تفعيل هذه الإعدادات مشكلة. لكن المستخدمين الذين ضُبط لديهم إعداد readonly على `1`
لا يمكنهم تغيير أي إعدادات، حتى في استعلامات `SELECT`. وبالنسبة إلى هؤلاء المستخدمين، سيؤدي تفعيل `SqlCompatibilitySettings` إلى
خطأ. يوضح القسم التالي كيفية جعل معلمة التكوين هذه تعمل للمستخدمين ذوي صلاحية القراءة فقط.

<div id="readonly-users">
  ## تفعيل إعدادات توافق SQL للمستخدمين ذوي صلاحية القراءة فقط
</div>

عند الاتصال بـ ClickHouse عبر برنامج تشغيل ODBC مع تمكين المعلمة `SqlCompatibilitySettings`، سيواجه المستخدم الذي
ضُبط إعداد readonly لديه على `1` خطأً لأن برنامج التشغيل يحاول تعديل إعدادات الاستعلام:

```plaintext theme={null}
Code: 164. DB::Exception: Cannot modify 'cast_keep_nullable' setting in readonly mode. (READONLY)
Code: 164. DB::Exception: Cannot modify 'prefer_column_name_to_alias' setting in readonly mode. (READONLY)
```

يحدث ذلك لأن المستخدمين في وضع القراءة فقط لا يُسمح لهم بتغيير الإعدادات، حتى في استعلامات `SELECT` الفردية.
هناك عدة طرق لمعالجة ذلك.

**الخيار 1: ضبط `readonly` على `2`**

هذا هو الخيار الأبسط. يتيح ضبط `readonly` على `2` تغيير الإعدادات مع إبقاء المستخدم في وضع القراءة فقط.

```sql theme={null}
ALTER USER your_odbc_user MODIFY SETTING
    readonly = 2
```

في معظم الحالات، يُعد ضبط `readonly` على 2 أسهل طريقة موصى بها لحل هذه المشكلة. إذا
لم ينجح ذلك، فاستخدم الخيار الثاني.

**الخيار 2. تغيير إعدادات المستخدم لتتوافق مع الإعدادات التي يعيّنها برنامج تشغيل ODBC.**

هذا الخيار بسيط أيضًا: حدّث إعدادات المستخدم لتتوافق مسبقًا مع ما يحاول برنامج تشغيل ODBC تعيينه.

```sql theme={null}
ALTER USER your_odbc_user MODIFY SETTING
    cast_keep_nullable = 1,
    prefer_column_name_to_alias = 1
```

مع هذا التغيير، يظل بإمكان برنامج تشغيل ODBC محاولة تطبيق الإعدادات، ولكن بما أن القيم متطابقة بالفعل، فلا
يُجرى أي تغيير فعلي ويُتجنب الخطأ.

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