メインコンテンツまでスキップ
メインコンテンツまでスキップ

gRPC インターフェース

概要​

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

  • SSL;
  • 認証;
  • セッション;
  • 圧縮;
  • 同じチャネルを通じた並列クエリ;
  • クエリのキャンセル;
  • 進捗とログの取得;
  • 外部テーブル。

インターフェースの仕様は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に配置されています。組み込みクライアントはggrpcioとgrpcio-toolsのPythonモジュールを必要とします。

クライアントは以下の引数をサポートしています：

  • --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ファイルからデータがロードされます。その後、テーブルの内容がクエリされます。

./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;"

結果：

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