واجهة gRPC

وثائق واجهة gRPC في ClickHouse

​

مقدمة

يدعم ClickHouse واجهة gRPC. وهي نظام مفتوح المصدر لاستدعاء الإجراءات عن بُعد يستخدم HTTP/2 وProtocol Buffers. ويدعم تطبيق gRPC في ClickHouse ما يلي:

• SSL;
• المصادقة;
• الجلسات;
• الضغط;
• الاستعلامات المتوازية عبر القناة نفسها;
• إلغاء الاستعلامات;
• الحصول على معلومات التقدّم والسجلات;
• الجداول الخارجية.

ترد مواصفات الواجهة في clickhouse_grpc.proto.

​

تهيئة gRPC

لاستخدام واجهة gRPC، اضبط grpc_port في إعدادات الخادم الرئيسية. اطّلع على خيارات التهيئة الأخرى في المثال التالي:

<grpc_port>9100</grpc_port>
    <grpc>
        <enable_ssl>false</enable_ssl>

        <!-- The following two files are used only if SSL is enabled -->
        <ssl_cert_file>/path/to/ssl_cert_file</ssl_cert_file>
        <ssl_key_file>/path/to/ssl_key_file</ssl_key_file>

        <!-- Whether server requests client for a certificate -->
        <ssl_require_client_auth>false</ssl_require_client_auth>

        <!-- The following file is used only if ssl_require_client_auth=true -->
        <ssl_ca_cert_file>/path/to/ssl_ca_cert_file</ssl_ca_cert_file>

        <!-- Default compression algorithm (applied if client doesn't specify another algorithm, see result_compression in QueryInfo).
             Supported algorithms: none, deflate, gzip, stream_gzip -->
        <compression>deflate</compression>

        <!-- Default compression level (applied if client doesn't specify another level, see result_compression in QueryInfo).
             Supported levels: none, low, medium, high -->
        <compression_level>medium</compression_level>

        <!-- Send/receive message size limits in bytes. -1 means unlimited -->
        <max_send_message_size>-1</max_send_message_size>
        <max_receive_message_size>-1</max_receive_message_size>

        <!-- Enable if you want to get detailed logs -->
        <verbose_logs>false</verbose_logs>
    </grpc>

​

العميل المضمّن

يمكنك كتابة عميل بأي لغة برمجة من اللغات التي يدعمها gRPC باستخدام المواصفة المتاحة. أو يمكنك استخدام عميل بايثون مضمّن. وهو موجود في utils/grpc-client/clickhouse-grpc-client.py في المستودع. ويتطلب العميل المضمّن وحدات بايثون grpcio and grpcio-tools.

يدعم العميل الوسائط التالية:

• --help – يعرض رسالة المساعدة ثم ينهي التشغيل.
• --host HOST, -h HOST – اسم خادم. القيمة الافتراضية: localhost. ويمكنك أيضًا استخدام عناوين IPv4 أو IPv6.
• --port PORT – منفذ للاتصال. يجب أن يكون هذا المنفذ مفعّلًا في إعدادات خادم ClickHouse (راجع grpc_port). القيمة الافتراضية: 9100.
• --user USER_NAME, -u USER_NAME – اسم مستخدم. القيمة الافتراضية: default.
• --password PASSWORD – كلمة مرور. القيمة الافتراضية: سلسلة فارغة.
• --query QUERY, -q QUERY – استعلام تجري معالجته عند استخدام الوضع غير التفاعلي.
• --database DATABASE, -d DATABASE – قاعدة بيانات افتراضية. إذا لم يتم تحديدها، فستُستخدم قاعدة البيانات الحالية المحددة في إعدادات الخادم (وتكون default افتراضيًا).
• --format OUTPUT_FORMAT, -f OUTPUT_FORMAT – تنسيق إخراج النتيجة. القيمة الافتراضية للوضع التفاعلي: PrettyCompact.
• --debug – يفعّل عرض معلومات التصحيح.

لتشغيل العميل في الوضع التفاعلي، استدعه بدون الوسيطة --query.

في وضع الدُفعات، يمكن تمرير بيانات الاستعلام عبر stdin.

مثال على استخدام العميل

في المثال التالي، يتم إنشاء جدول وتحميله ببيانات من ملف CSV. ثم يُستعلَم عن محتوى الجدول.

Query

./clickhouse-grpc-client.py -q "CREATE TABLE grpc_example_table (id UInt32, text String) ENGINE = MergeTree() ORDER BY id;"
echo -e "0,Input data for\n1,gRPC protocol example" > a.csv
cat a.csv | ./clickhouse-grpc-client.py -q "INSERT INTO grpc_example_table FORMAT CSV"

./clickhouse-grpc-client.py --format PrettyCompact -q "SELECT * FROM grpc_example_table;"

Response

┌─id─┬─text──────────────────┐
│  0 │ Input data for        │
│  1 │ gRPC protocol example │
└────┴───────────────────────┘