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

> وثائق مكتبة عميل ClickHouse بلغة C++ والتكامل مع إطار العمل u-server

# مكتبة عميل C++

`clickhouse-cpp` هي مكتبة العميل الرسمية لـ ClickHouse بلغة C++، وتوفّر
واجهة سريعة ومأمونة الأنواع لـ ClickHouse باستخدام بروتوكوله الثنائي الأصلي.

تعليمات البناء، وأمثلة الاستخدام، ووثائق إضافية متاحة في
مستودع GitHub الخاص بالمشروع: [https://github.com/ClickHouse/clickhouse-cpp](https://github.com/ClickHouse/clickhouse-cpp).

<Note>
  المكتبة قيد التطوير النشط. وعلى الرغم من أنها تدعم بالفعل الإمكانات الأساسية في ClickHouse،
  فإن بعض الميزات وأنواع البيانات قد لا تكون مطبّقة بالكامل أو مدعومة بعد.

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

<div id="including-library-into-project">
  ## تضمين المكتبة في مشروعك
</div>

أبسط طريقة لإدراج المكتبة في مشروعك هي استخدام وحدة
`FetchContent` الخاصة بـ CMake. يتيح لك هذا النهج تثبيت إصدار محدد بدقة من المكتبة وبناؤها كجزء من
سير عمل CMake المعتاد.

```cmake theme={null}
include(FetchContent)

set(WITH_OPENSSL YES CACHE BOOL "Enable OpenSSL in clickhouse-cpp" FORCE)
FetchContent_Declare(
    clickhouse-cpp
    GIT_REPOSITORY https://github.com/ClickHouse/clickhouse-cpp.git
    GIT_TAG v2.6.0   # can also be `master` or other banch
)
FetchContent_MakeAvailable(clickhouse-cpp)
```

يتيح الخيار `WITH_OPENSSL` دعم TLS في المكتبة، وهو مطلوب عند الاتصال بـ
ClickHouse Cloud أو بعمليات نشر ClickHouse الأخرى المفعّل فيها SSL. ورغم أنه يمكن الاستغناء عنه في
الاتصالات غير المعتمدة على TLS، فإن تمكينه يُوصى به عمومًا.

يتطلب البناء مع دعم SSL تثبيت حزم تطوير OpenSSL. ثبّت
`libssl-dev` على Debian وUbuntu أو مشتقاتهما؛ و`openssl-devel` على Fedora وRed Hat؛ أو
`openssl` على macOS باستخدام homebrew.

بعد توفير التبعية، اربط هدفك بهدف المكتبة المُصدَّر:

```cmake theme={null}
target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)
```

<div id="examples">
  ## أمثلة
</div>

<div id="example-setup-client">
  ### إعداد كائن Client
</div>

أنشئ مثيلًا من `Client` لإقامة اتصال مع ClickHouse. يوضّح المثال التالي
كيفية الاتصال بمثيل ClickHouse محلي، حيث لا تكون كلمة المرور مطلوبة ولا يكون SSL
مفعّلًا.

```cpp theme={null}
#include <clickhouse/client.h>

clickhouse::Client client{clickhouse::ClientOptions().SetHost("localhost")};
```

في عمليات الإعداد الأكثر تقدّمًا، يلزم إجراء إعدادات إضافية. يوضّح المثال التالي
كيفية الاتصال بمثيل ClickHouse Cloud باستخدام عدة معلمات إضافية:

```cpp theme={null}
#include <clickhouse/client.h>

clickhouse::Client client{
    clickhouse::ClientOptions{}
      .SetHost("your.instance.clickhouse.cloud")
      .SetUser("default")
      .SetPassword("your-password")
      .SetSSLOptions({})   // Enable SSL
      .SetPort(9440)       // for connections over SSL ClickHouse Cloud uses port 9440
    };
```

<div id="example-create-table">
  ### إنشاء الجداول وتنفيذ استعلامات دون بيانات
</div>

لتنفيذ استعلام لا يعيد أي بيانات، مثل إنشاء الجداول، استخدم الطريقة `Execute`.
وينطبق الأسلوب نفسه على تعليمات أخرى مثل `ALTER TABLE` و`DROP` وغيرها.

```cpp theme={null}
client.Execute(R"(
    CREATE TABLE IF NOT EXISTS greetings (
        id UInt64,
        message String,
        language String) 
    ENGINE = MergeTree ORDER BY id)");
```

<div id="example-insert-data">
  ### إدراج البيانات
</div>

لإدراج البيانات في جدول، أنشئ `Block` واملأه بكائنات الأعمدة المطابقة
لمخطط الجدول. تُضاف البيانات عمودًا تلو الآخر، ثم تُدرج بعملية واحدة باستخدام
الطريقة `Insert`، وهي مُحسّنة لتنفيذ عمليات كتابة دفعية بكفاءة.

```cpp theme={null}
auto id = std::make_shared<clickhouse::ColumnUInt64>();
auto message = std::make_shared<clickhouse::ColumnString>();
auto language = std::make_shared<clickhouse::ColumnString>();

id->Append(1);
message->Append("Hello, World!");
language->Append("English");

id->Append(2);
message->Append("¡Hola, Mundo!");
language->Append("Spanish");

id->Append(3);
message->Append("Hallo wereld!");
language->Append("Dutch");

clickhouse::Block block{};
block.AppendColumn("id", id);
block.AppendColumn("message", message);
block.AppendColumn("language", language);

client.Insert("greetings", block);
```

<div id="example-select">
  ### اختيار البيانات
</div>

لتنفيذ استعلام يُرجع بيانات، استخدم الطريقة `Select` ومرّر دالة ردّ نداء لمعالجة
النتيجة. تُعاد نتائج الاستعلام على هيئة كائنات `Block`، بما يعكس تمثيل البيانات الأصلي
المعتمد على الأعمدة في ClickHouse.

```cpp theme={null}
client.Select(
    "SELECT id, message, language FROM greetings",
    [](const clickhouse::Block & block){
        for (size_t i = 0; i < block.GetRowCount(); ++i) {
            auto id = block[0]->AsStrict<clickhouse::ColumnUInt64>()->At(i);
            auto message = block[1]->AsStrict<clickhouse::ColumnString>()->At(i);
            auto language = block[2]->AsStrict<clickhouse::ColumnString>()->At(i);
            std::cout << id << "\t" << message << "\t" << language << "\n";
        }
    });
```

<div id="supported-data-types">
  ## أنواع البيانات المدعومة
</div>

* `UInt8`, `UInt16`, `UInt32`, `UInt64`, `Int8`, `Int16`, `Int32`, `Int64`
* `UInt128`, `Int128`
* `Decimal32`, `Decimal64`, `Decimal128`
* `Float32`, `Float64`
* `Date`
* `DateTime`, `DateTime64`
* `DateTime([timezone])`, `DateTime64(N, [timezone])`
* `UUID`
* `Enum8`, `Enum16`
* `String`
* `FixedString(N)`
* `LowCardinality(String)` و `LowCardinality(FixedString(N))`
* `Nullable(T)`
* `Array(T)`
* `Tuple`
* `Map`
* `IPv4`, `IPv6`
* `Point`, `Ring`, `Polygon`, `MultiPolygon`