跳转到主要内容

​
前置条件

要运行本文中的示例，你需要：
  • 有一个正在运行的 ClickHouse server 实例
  • 已安装 curl。在 Ubuntu 或 Debian 上，运行 sudo apt install curl，或参阅此文档了解安装说明。

​
概述

HTTP 接口 允许你以 REST API 的形式，在任何平台上通过任何编程语言使用 ClickHouse。HTTP 接口 的功能比 native interface 更受限，但语言支持更好。 默认情况下，clickhouse-server 监听以下端口：
  • 8123 端口用于 HTTP
  • 可启用 8443 端口用于 HTTPS
如果发起不带任何参数的 GET / 请求，则会返回 200 响应码以及字符串 “Ok.”：
“Ok.” 是 http_server_default_response 中定义的默认值，可按需更改。 另请参见：HTTP 响应代码注意事项。

​
Web 用户界面

ClickHouse 提供了一个 Web 用户界面，可通过以下地址访问：
web UI 支持在查询运行期间显示进度、取消查询以及流式传输结果。 它还提供了一项用于显示查询管道图表和图形的隐藏功能。 查询成功执行后，会出现一个下载按钮，允许您以多种格式下载查询结果，包括 CSV、TSV、JSON、JSONLines、Parquet、Markdown，以及 ClickHouse 支持的任何自定义格式。下载功能使用查询缓存高效获取结果，而无需重新执行查询。即使 UI 只显示了多页结果中的一页，它也会下载完整结果集。 web UI 专为像您这样的专业用户而设计。 在健康检查脚本中，请使用 GET /ping 请求。此处理程序始终返回 “Ok.” (末尾带有一个换行符) 。自 18.12.13 版本起可用。另请参阅 /replicas_status 以检查副本延迟。

​
通过 HTTP/HTTPS 查询

通过 HTTP/HTTPS 查询有三种方式：
  • 将请求作为 URL 的 ‘query’ 参数发送
  • 使用 POST 方法。
  • 在 ‘query’ 参数中发送查询的开头部分，其余部分通过 POST 发送
默认情况下，URL 大小限制为 1 MiB，可通过 http_max_uri_size 设置修改。
如果成功，你会收到 200 响应码，结果位于响应体中。 如果发生错误，你会收到 500 响应码，响应体中会包含错误描述文本。 使用 GET 的请求是 ‘readonly’。这意味着，对于会修改数据的查询，只能使用 POST 方法。 你可以将查询语句放在 POST 请求体中发送，也可以通过 URL 参数发送。下面来看一些示例。 在下面的示例中，使用 curl 发送查询 SELECT 1。请注意，空格需要进行 URL 编码：%20。
command
Response
在此示例中，使用 wget 的 -nv (非冗长) 和 -O- 参数将结果输出到终端。 在这种情况下，无需对空格进行 URL 编码：
command
在此示例中，我们通过管道将原始 HTTP 请求发送到 netcat：
command
response
如你所见，curl 命令用起来有些不方便，因为空格必须进行 URL 转义。 虽然 wget 会自行转义所有内容，但我们不建议使用它，因为在使用 keep-alive 和 Transfer-Encoding: chunked 时，它通过 HTTP 1.1 的表现并不好。
如果查询的一部分通过参数传递，另一部分通过 POST 传递，那么这两个数据部分之间会插入一个换行符。 例如，下面这样是行不通的：
默认情况下，数据会以 TabSeparated 格式返回。 可在查询中使用 FORMAT 子句来指定其他任意格式。例如：
command
Response
您可以使用 default_format URL 参数或 X-ClickHouse-Format 请求头，将默认格式指定为 TabSeparated 以外的格式。
您可以使用 POST 方法执行参数化查询。参数通过花括号指定，并包含参数名称和类型，例如 {name:Type}。参数值通过 param_name 传入：

​
通过 HTTP/HTTPS 执行插入查询

执行 INSERT 查询时，必须使用 POST 方法传输数据。在这种情况下，你可以将查询开头部分写在 URL 参数中，再通过 POST 传递要插入的数据。要插入的数据例如可以是从 MySQL 导出的制表符分隔转储文件。这样，INSERT 查询就相当于替代了 MySQL 中的 LOAD DATA LOCAL INFILE。

​
示例

创建表：
如需使用常见的 INSERT 查询插入数据：
若要将数据与查询分开发送：
可以指定任何数据格式。例如，可以指定 ‘Values’ 格式，它与在编写 INSERT INTO t VALUES 时使用的格式相同：
要从以制表符分隔的转储中插入数据，请指定相应的格式：
要查看表内容：
由于查询处理是并行进行的，数据会按随机顺序输出
要删除该表：
对于未返回数据表的成功请求，响应体为空。

​
压缩

压缩可用于在传输大量数据时减少网络流量，也可用于创建压缩后的转储文件。 传输数据时，您可以使用 ClickHouse 的内部压缩格式。压缩后的数据采用非标准格式，因此需要使用 clickhouse-compressor 程序来处理。该程序默认随 clickhouse-client 软件包一起安装。 为提高数据插入效率，请使用 http_native_compression_disable_checksumming_on_decompress 设置禁用服务器端的校验和验证。 如果您在 URL 中指定 compress=1，服务器会压缩发送给您的数据。如果您在 URL 中指定 decompress=1，服务器会解压您通过 POST 方法传入的数据。 您也可以选择使用 HTTP 压缩。ClickHouse 支持以下压缩方法：
  • gzip
  • br
  • deflate
  • xz
  • zstd
  • lz4
  • bz2
  • snappy
要发送压缩的 POST 请求，请附加请求头 Content-Encoding: compression_method。 要让 ClickHouse 压缩响应，请在请求中附加 Accept-Encoding: compression_method 请求头。 您可以使用 http_zlib_compression_level 设置，为所有压缩方法配置数据压缩级别。
某些 HTTP 客户端可能默认会解压来自服务器的数据 (如 gzip 和 deflate) ，因此即使您正确使用了压缩设置，也可能收到解压后的数据。

​
示例

要将压缩数据发送到服务器：
要从服务器接收压缩数据归档文件：
要接收来自服务器的压缩数据，可使用 gunzip 获取解压后的数据：

​
默认数据库

你可以使用 URL 参数 database 或 X-ClickHouse-Database 请求头来指定默认数据库。
默认情况下，服务器设置中注册的数据库会被用作默认数据库。开箱即用时，该数据库名为 default。或者，你也可以始终在表名前加上点号来指定数据库。

​
身份验证

可以通过以下三种方式之一提供用户名和密码：
  1. 使用 HTTP Basic 身份验证。
例如：
  1. 在 user 和 password URL 参数中
我们不建议使用这种方法，因为这些参数可能会被 Web 代理记录，并缓存在浏览器中
例如：
  1. 使用 ‘X-ClickHouse-User’ 和 ‘X-ClickHouse-Key’ 请求头
例如：
如果未指定用户名，则使用 default。如果未指定密码，则使用空密码。 你还可以使用 URL 参数，为处理单个查询指定任意设置，或指定整个 profile 的设置。 例如：
更多信息，请参阅：

​
在 HTTP 协议中使用 ClickHouse 会话

你也可以在 HTTP 协议中使用 ClickHouse 会话。为此，需要在请求中添加 session_id GET 参数。你可以使用任意字符串作为会话 ID。 默认情况下，会话在 60 秒无活动后终止。要更改此超时 (以秒为单位) ，请修改服务器配置中的 default_session_timeout 设置，或在请求中添加 session_timeout GET 参数。 要检查会话状态，请使用 session_check=1 参数。单个会话中一次只能执行一个查询。 你可以在 X-ClickHouse-Progress 响应请求头中获取有关查询进度的信息。为此，请启用 send_progress_in_http_headers。 下面是一个请求头序列示例：
可能的请求头字段如下： 如果 HTTP 连接丢失，正在运行的请求不会自动停止。解析和数据格式化都在服务器端完成，因此通过网络传输可能效率较低。 以下可选参数可用： HTTP 接口支持传递外部数据 (外部临时表) 用于查询。更多信息，请参阅”External data for query processing”。

​
响应缓冲

服务端可以启用响应缓冲。为此提供了以下 URL 参数：
  • buffer_size
  • wait_end_of_query
也可以使用以下设置： buffer_size 用于指定在服务器内存中为结果缓冲的字节数。如果结果体大于该阈值，缓冲区中的内容会写入 HTTP 通道，其余数据将直接发送到 HTTP 通道。 要确保整个响应都被缓冲，请设置 wait_end_of_query=1。在这种情况下，未存储在内存中的数据会缓冲到服务器上的临时文件中。 例如：
使用缓冲可避免这样一种情况：在响应状态码和 HTTP 请求头已发送给客户端之后，才发生查询处理错误。在这种情况下，错误信息会写在响应体末尾，而客户端只能在解析阶段检测到该错误。

​
使用查询参数设置角色

此功能已在 ClickHouse 24.4 中引入。 在某些特定场景下，可能需要先设置已授予的角色，再执行语句本身。 但是，无法将 SET ROLE 与该语句一并发送，因为不允许使用多语句：
上述命令会报错：
为解决这一限制，请改用 role 查询参数：
这等同于在该语句前执行 SET ROLE my_role。 此外，还可以指定多个 role 查询参数：
在这种情况下，?role=my_role&role=my_other_role 的效果类似于在执行该语句之前先执行 SET ROLE my_role, my_other_role。

​
HTTP 响应状态码注意事项

由于 HTTP 协议本身的限制，HTTP 200 响应码并不保证查询已成功。 例如：
出现这种行为的原因在于 HTTP 协议本身的特性。HTTP 请求头会先以 200 HTTP 状态码发送，随后发送 HTTP body，而错误则会以纯文本形式插入到 body 中。 这种行为与所使用的格式无关，无论是 Native、TSV 还是 JSON；错误消息总是会出现在响应流的中间。 你可以通过启用 wait_end_of_query=1 (响应缓冲) 来缓解这个问题。在这种情况下，HTTP 请求头会延迟到整个查询处理完成后才发送。不过，这并不能彻底解决问题，因为结果仍然必须能够容纳在 http_response_buffer_size 中，而且像 send_progress_in_http_headers 这样的其他设置也可能会影响请求头的延迟发送。
要捕获所有错误，唯一的方法是在按所需格式解析 HTTP body 之前先对其进行分析。
当 http_write_exception_in_output_format=0 (默认值) 时，ClickHouse 中这类异常都会采用如下所示的一致格式，而与所使用的格式无关 (例如 Native、TSV、JSON 等) 。这使得客户端更容易解析并提取错误消息。
其中，<TAG> 是一个 16 字节的随机标签，与响应请求头 X-ClickHouse-Exception-Tag 中返回的标签相同。 <error message> 是实际的异常消息 (其精确长度可在 <message_length> 中找到) 。上述整个异常块最大可达 16 KiB。 下面是一个 JSON 格式的示例
下面是一个类似的示例，不过采用的是 CSV 格式

​
带参数的查询

您可以创建带参数的查询，并通过相应的 HTTP 请求参数传入参数值。更多信息，请参见CLI 中的带参数查询。

​
示例

​
URL 参数中的制表符

查询参数按 “escaped” 格式解析。这样做有一些好处，例如可以将 null 明确解析为 \N。这意味着制表符应编码为 \t (或 \ 后跟一个制表符) 。例如，下面的内容在 abc 和 123 之间包含一个实际的制表符，因此输入字符串会被拆分为两个值：
不过，如果你尝试在 URL 参数中用 %09 对实际的制表符进行编码，就无法被正确解析：
如果使用 URL 参数，则需要将 \t 编码为 %5C%09。例如：

​
预定义 HTTP 接口

ClickHouse 支持通过 HTTP 接口执行特定查询。例如，您可以按如下方式将数据写入表中：
ClickHouse 还支持预定义 HTTP 接口，可帮助您更轻松地与 Prometheus exporter 等第三方工具集成。下面来看一个示例。 首先，将以下部分添加到您的服务器配置文件中。 http_handlers 配置为包含多条 rule。ClickHouse 会将收到的 HTTP 请求与 rule 中预定义的类型进行匹配，首个匹配成功的规则会运行相应的处理程序。随后，如果匹配成功，ClickHouse 将执行对应的预定义查询。
config.xml
现在，你可以直接通过该 URL 请求 Prometheus 格式的数据：
http_handlers 的配置选项如下所示。 rule 可配置以下参数：
  • method
  • headers
  • url
  • full_url
  • handler
下面将分别介绍这些参数：
  • method 负责匹配 HTTP 请求中的方法部分。method 完全符合 HTTP protocol 中 [method] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) 的定义。这是一个可选配置。如果在 配置文件中未定义，则不会匹配 HTTP 请求的方法部分。
  • url 负责匹配 HTTP 请求中的 URL 部分 (path 和 query string) 。 如果 url 带有 regex: 前缀，则使用 RE2 的正则表达式。 这是一个可选配置。如果在配置文件中未定义，则不会匹配 HTTP 请求的 URL 部分。
  • full_url 与 url 相同，但包含完整 URL，即 schema://host:port/path?query_string。 注意，ClickHouse 不支持“virtual hosts”，因此 host 是 IP 地址 (而不是 Host 请求头的值) 。
  • empty_query_string - 确保请求中没有 query string (?query_string)
  • headers 负责匹配 HTTP 请求的请求头部分。它兼容 RE2 的正则表达式。这是一个可选 配置。如果在配置文件中未定义，则不会匹配 HTTP 请求的请求头部分。
  • handler 包含主要处理逻辑。 它可以具有以下 type： 以及以下参数：
    • query — 与 predefined_query_handler 类型一起使用，在调用处理程序时执行查询。
    • query_param_name — 与 dynamic_query_handler 类型一起使用，提取并执行 HTTP 请求参数中参数名为 query_param_name 的值。
    • status — 与 static 类型一起使用，表示响应状态码。
    • content_type — 可与任何类型一起使用，表示响应的 content-type。
    • http_response_headers — 可与任何类型一起使用，表示响应请求头映射。也可用于设置 content type。
    • response_content — 与 static 类型一起使用，表示发送给客户端的响应内容；当使用前缀 ‘file://’ 或 ‘config://’ 时，会从文件或配置中查找内容并发送给客户端。
    • user - 用于执行查询的用户 (默认用户为 default) 。 注意，无需为该用户指定密码。
接下来将讨论不同 type 的配置方法。

​
predefined_query_handler

predefined_query_handler 支持设置 Settings 和 query_params 的值。你可以在 predefined_query_handler 类型中配置 query。 query 的值是 predefined_query_handler 的预定义查询；当 HTTP 请求匹配时，ClickHouse 会执行该查询并返回查询结果。这是必填配置项。 以下示例定义了 max_threads 和 max_final_threads 这两个设置的值，然后查询系统表，以检查这些设置是否已成功生效。
要保留默认的 handlers，例如 query、play、ping，请添加 <defaults/> 规则。
例如：

​
虚拟参数 _request_body

除了 URL 参数、请求头和查询参数外，predefined_query_handler 还支持一个特殊的虚拟参数 _request_body。 它以字符串形式包含原始 HTTP 请求体。 这样，你就可以创建灵活的 REST API，接受任意数据格式，并在查询中进行处理。 例如，你可以使用 _request_body 实现一个 REST 端点，在 POST 请求中接收 JSON 数据并将其插入表中：
随后，您可以将数据发送到此端点：
在一个 predefined_query_handler 中，只支持一个 查询。

​
dynamic_query_handler

在 dynamic_query_handler 中，查询以 HTTP 请求参数的形式传入。不同的是，在 predefined_query_handler 中，查询写在配置文件里。dynamic_query_handler 中可以配置 query_param_name。 ClickHouse 会从 HTTP 请求的 URL 中提取与 query_param_name 对应的值并执行。query_param_name 的默认值为 /query。这是一个可选配置；如果配置文件中未定义，就不会传递该参数。 要试用此功能，下面的示例定义了 max_threads 和 max_final_threads 的值，并查询这些设置是否已成功生效。 示例：

​
static

static 可返回 content_type、status 和 response_content。其中，response_content 用于返回指定的内容。 例如，要返回一条消息 “Say Hi!”：
可使用 http_response_headers 设置内容类型，而无需使用 content_type。
查找配置发送给客户端的内容。
要查看从文件发送给客户端的内容：

​
redirect

redirect 会将请求以 302 重定向到 location 例如，下面展示了如何为 ClickHouse play 自动向 play 添加 set user：

​
HTTP 响应头

ClickHouse 允许你配置自定义 HTTP 响应头，并将其应用于任何可配置的处理程序。这些响应头可通过 http_response_headers 设置，该设置接受表示请求头名称及其值的键值对。此功能特别适合在整个 ClickHouse HTTP 接口中实现自定义安全响应头、CORS 策略或任何其他 HTTP 请求头要求。 例如，你可以为以下对象配置响应头：
  • 常规查询端点
  • Web UI
  • 健康检查。
还可以指定 common_http_response_headers。这些响应头将应用于配置中定义的所有 HTTP 处理程序。 这些响应头会包含在每个已配置处理程序的 HTTP 响应中。 在下面的示例中，每个服务器响应都将包含两个自定义响应头：X-My-Common-Header 和 X-My-Custom-Header。

​
HTTP 流式传输期间发生异常时的有效 JSON/XML 响应

通过 HTTP 执行查询时，如果部分数据已经发送，可能会发生异常。通常，异常会以纯文本形式发送给客户端。 即使数据输出时使用了特定格式，输出结果也可能因此不再是符合该格式的有效数据。 为避免这种情况，你可以使用设置 http_write_exception_in_output_format (默认禁用) ，该设置会指示 ClickHouse 以指定格式写出异常 (当前支持 XML 和 JSON* 格式) 。 示例：
最后修改于 2026年7月3日