> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse gRPC 接口文档

# gRPC 接口

<div id="grpc-interface-introduction">
  ## 简介
</div>

ClickHouse 支持 [gRPC](https://grpc.io/) 接口。gRPC 是一个基于 HTTP/2 和 [Protocol Buffers](https://en.wikipedia.org/wiki/Protocol_Buffers) 的开源远程过程调用系统。ClickHouse 中的 gRPC 实现支持：

* SSL；
* 身份验证；
* 会话；
* 压缩；
* 通过同一通道并行执行查询；
* 取消查询；
* 获取 Progress 和日志；
* 外部表。

该接口的规范可参见 [clickhouse\_grpc.proto](https://github.com/ClickHouse/ClickHouse/blob/master/src/Server/grpc_protos/clickhouse_grpc.proto)。

<div id="grpc-interface-configuration">
  ## gRPC 配置
</div>

如需使用 gRPC 接口，请在主[服务器配置](/zh/concepts/features/configuration/server-config/configuration-files)中设置 `grpc_port`。其他配置选项请参见下面的示例：

```xml theme={null}
<grpc_port>9100</grpc_port>
    <grpc>
        <enable_ssl>false</enable_ssl>

        <!-- 以下两个文件仅在启用 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>
```

<div id="grpc-client">
  ## 内置客户端
</div>

你可以根据提供的[规范](https://github.com/ClickHouse/ClickHouse/blob/master/src/Server/grpc_protos/clickhouse_grpc.proto)，使用任何 gRPC 支持的编程语言编写客户端。
或者，也可以使用内置的 Python 客户端。它位于仓库中的 [utils/grpc-client/clickhouse-grpc-client.py](https://github.com/ClickHouse/ClickHouse/blob/master/utils/grpc-client/clickhouse-grpc-client.py)。内置客户端需要 [grpcio 和 grpcio-tools](https://grpc.io/docs/languages/python/quickstart) 这两个 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` – 结果输出[格式](/zh/reference/formats)。交互模式下的默认值为：`PrettyCompact`。
* `--debug` – 启用调试信息显示。

要以交互模式运行客户端，请在调用时不要传入 `--query` 参数。

在批次模式下，可通过 `stdin` 传入查询数据。

**客户端使用示例**

在下面的示例中，将创建一个表，并从 CSV 文件中加载数据。随后会查询该表的内容。

```bash title="Query" theme={null}
./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;"
```

```text title="Response" theme={null}
┌─id─┬─text──────────────────┐
│  0 │ Input data for        │
│  1 │ gRPC protocol example │
└────┴───────────────────────┘
```