メインコンテンツへスキップ
メインコンテンツへスキップ

gRPC インターフェイス

はじめに​

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

  • 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 がサポートする任意のプログラミング言語でクライアントを実装できます。 または、組み込みの Python クライアントを使用することもできます。これはリポジトリ内の utils/grpc-client/clickhouse-grpc-client.py に含まれています。組み込みクライアントの利用には、grpcio と 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 │
└────┴───────────────────────┘