gRPC インターフェイス

ClickHouse の gRPC インターフェイスのドキュメント

​

はじめに

ClickHouse は gRPC インターフェイスをサポートしています。gRPC は、HTTP/2 と Protocol Buffers を使用するオープンソースのリモートプロシージャコールシステムです。ClickHouse の gRPC 実装では、以下をサポートしています。

• SSL;
• 認証;
• セッション;
• 圧縮;
• 同一チャネル経由での並列クエリ;
• クエリのキャンセル;
• Progress とログの取得;
• 外部テーブル。

このインターフェイスの仕様は clickhouse_grpc.proto に記載されています。

​

gRPC 設定

gRPC インターフェイスを使用するには、メインのサーバー設定で grpc_port を設定します。その他の設定オプションについては、次の例を参照してください。

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

        <!-- 以下の2つのファイルはSSLが有効な場合にのみ使用されます -->
        <ssl_cert_file>/path/to/ssl_cert_file</ssl_cert_file>
        <ssl_key_file>/path/to/ssl_key_file</ssl_key_file>

        <!-- サーバーがクライアントに証明書を要求するかどうか -->
        <ssl_require_client_auth>false</ssl_require_client_auth>

        <!-- 以下のファイルはssl_require_client_auth=trueの場合にのみ使用されます -->
        <ssl_ca_cert_file>/path/to/ssl_ca_cert_file</ssl_ca_cert_file>

        <!-- デフォルトの圧縮アルゴリズム（クライアントが別のアルゴリズムを指定しない場合に適用されます。QueryInfoのresult_compressionを参照）。
             サポートされているアルゴリズム: none, deflate, gzip, stream_gzip -->
        <compression>deflate</compression>

        <!-- デフォルトの圧縮レベル（クライアントが別のレベルを指定しない場合に適用されます。QueryInfoのresult_compressionを参照）。
             サポートされているレベル: none, low, medium, high -->
        <compression_level>medium</compression_level>

        <!-- 送受信メッセージサイズの上限（バイト単位）。-1は無制限を意味します -->
        <max_send_message_size>-1</max_send_message_size>
        <max_receive_message_size>-1</max_receive_message_size>

        <!-- 詳細ログを取得する場合は有効にしてください -->
        <verbose_logs>false</verbose_logs>
    </grpc>

​

組み込みクライアント

提供されている仕様を使用して、gRPC がサポートする任意のプログラミング言語でクライアントを作成できます。 また、組み込みの Python クライアントを使用することもできます。これはリポジトリ内の utils/grpc-client/clickhouse-grpc-client.py にあります。組み込みクライアントには、Python モジュールの grpcio and grpcio-tools が必要です。

このクライアントは次の引数をサポートしています。

• --help – ヘルプメッセージを表示して終了します。
• --host HOST, -h HOST – サーバー名です。デフォルト値: localhost。IPv4 アドレスまたは IPv6 アドレスも使用できます。
• --port PORT – 接続先のポートです。このポートはサーバー設定で有効になっている必要があります (grpc_port を参照) 。デフォルト値: 9100。
• --user USER_NAME, -u USER_NAME – ユーザー名です。デフォルト値: default。
• --password PASSWORD – パスワードです。デフォルト値: 空文字列。
• --query QUERY, -q QUERY – 非対話型モードで処理するクエリです。
• --database DATABASE, -d DATABASE – デフォルトのデータベースです。指定しない場合は、server settings で設定された現在のデータベースが使用されます (デフォルトでは 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 │
└────┴───────────────────────┘