Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

تضمين المكتبة في مشروعك

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

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.

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

target_link_libraries(your-target PRIVATE clickhouse-cpp-lib)

أمثلة

إعداد كائن Client

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

#include <clickhouse/client.h>

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

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

#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
    };

إنشاء الجداول وتنفيذ الاستعلامات من دون بيانات

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

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

إدراج البيانات

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

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);

اختيار البيانات

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

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";
        }
    });

أنواع البيانات المدعومة

  • 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
Navigation