Skip to main content

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:

Authentication

A query is authenticated with the user_name and password fields of QueryInfo (the quota field sets the quota key). The user_name field is optional: when it is empty, the query is authenticated as the user named by the default_session_user server setting (default unless configured otherwise) with the supplied, possibly empty, password, exactly like an HTTP request without the user parameter. The empty user name is only an alias for that user: its password, networks and other access checks apply as usual, so whether a query without credentials is accepted is decided by the configuration of that user. If default_session_user is set to an empty string, queries without a user_name are rejected, and, when the session_log section is enabled in the server configuration, the reject is recorded in system.session_log as a LoginFailure event with an empty user.

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.
Query
Response