Skip to main content

gRPC Interface

Introduction​

ClickHouse supports gRPC interface. It is an open source remote procedure call system that uses HTTP/2 and Protocol Buffers. The implementation of gRPC in ClickHouse supports:

  • SSL;
  • authentication;
  • sessions;
  • compression;
  • parallel queries through the same channel;
  • cancellation of queries;
  • getting progress and logs;
  • external tables.

The specification of the interface is described in clickhouse_grpc.proto.

gRPC Configuration​

To use the gRPC interface set grpc_port in the main server configuration. Other configuration options see in the following example:

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

Built-in Client​

You can write a client in any of the programming languages supported by gRPC using the provided specification. Or you can use a built-in Python client. It is placed in utils/grpc-client/clickhouse-grpc-client.py in the repository. The built-in client requires grpcio and grpcio-tools Python modules.

The client supports the following arguments:

  • --help – Shows a help message and exits.
  • --host HOST, -h HOST – A server name. Default value: localhost. You can use IPv4 or IPv6 addresses also.
  • --port PORT – A port to connect to. This port should be enabled in the ClickHouse server configuration (see grpc_port). Default value: 9100.
  • --user USER_NAME, -u USER_NAME – A user name. Default value: default.
  • --password PASSWORD – A password. Default value: empty string.
  • --query QUERY, -q QUERY – A query to process when using non-interactive mode.
  • --database DATABASE, -d DATABASE – A default database. If not specified, the current database set in the server settings is used (default by default).
  • --format OUTPUT_FORMAT, -f OUTPUT_FORMAT – A result output format. Default value for interactive mode: PrettyCompact.
  • --debug – Enables showing debug information.

To run the client in an interactive mode call it without --query argument.

In a batch mode query data can be passed via stdin.

Client Usage Example

In the following example a table is created and loaded with data from a CSV file. Then the content of the table is queried.

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

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

Result:

β”Œβ”€id─┬─text──────────────────┐
β”‚ 0 β”‚ Input data for β”‚
β”‚ 1 β”‚ gRPC protocol example β”‚
β””β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜