gRPC

ClickHouse exposes a gRPC API for service-to-service integration. Default port: 9100. Implementation: src/Server/GRPCServer.cpp. Schema: src/Server/grpc_protos/clickhouse_grpc.proto.

Service shape

service ClickHouse {
  rpc ExecuteQuery(QueryInfo) returns (Result);
  rpc ExecuteQueryWithStreamInput(stream QueryInfo) returns (Result);
  rpc ExecuteQueryWithStreamOutput(QueryInfo) returns (stream Result);
  rpc ExecuteQueryWithStreamIO(stream QueryInfo) returns (stream Result);
}

The four RPC variants combine streaming on either side:

• Unary — full request, full response. Bounded queries.
• Streaming input — multiple QueryInfo messages stream INSERT data.
• Streaming output — receive results in Result chunks (large SELECTs).
• Bidirectional — typical for INSERT ... SELECT over arbitrary data sources.

QueryInfo highlights

• query — the SQL text.
• query_id — externally supplied id.
• database, user_name, password.
• settings — map of per-query settings.
• external_tables — temporary tables the query can reference.
• input_data — bytes for streaming INSERT.
• input_data_format — Native, JSONEachRow, …
• output_format — picked format for the response.
• query_parameters — for parameterised queries.
• cancel — set on a follow-up message to cancel an in-flight query.

Result highlights

• output — bytes in the chosen format.
• totals / extremes — when the query asks for them.
• progress — rows/bytes processed.
• stats — final counters.
• logs — stream of server log entries (in their structured form).
• exception — populated on error.

Auth

• TLS at the transport level.
• Per-call credentials passed in QueryInfo (user_name / password).
• Bearer tokens via gRPC metadata (when configured server-side).

Reference clients

• utils/grpc-client/ — a Python reference client that wraps the generated stubs.
• The proto file is published for any language with a gRPC code generator.

When to choose gRPC

• You are building a service that talks to ClickHouse from a strongly-typed language and want a versioned contract.
• You need bidirectional streaming for INSERT ... FROM client_data.
• You want to multiplex many concurrent queries on a single HTTP/2 connection.

For one-shot scripts, prefer HTTP. For maximum performance, prefer native TCP.

Related pages

• Server protocols
• HTTP interface
• Native TCP