HTTP 接口
HTTP 接口允许您通过 REST API 以任何编程语言在任何平台上使用 ClickHouse。HTTP 接口比本地接口更有限，但对语言的支持更好。
默认情况下，clickhouse-server 在端口 8123 上监听 HTTP（可以在配置中更改）。HTTPS 默认可以在端口 8443 上启用。
如果您发送一个无参数的 GET / 请求，它将返回 200 响应代码和在 http_server_default_response 中定义的字符串默认值 "Ok."（末尾带换行符）
另请参见: HTTP 响应代码注意事项。
有时，用户操作系统上可能没有 curl 命令。在 Ubuntu 或 Debian 上，运行 sudo apt install curl。请参阅此 文档 在运行示例之前安装它。
Web UI 可以在这里访问: http://localhost:8123/play。
Web UI 支持在查询运行时显示进度、查询取消和流式结果。 它还具有显示查询管道图表和图形的秘密功能。
Web UI 旨在为像您这样的专业人士设计。
在健康检查脚本中使用 GET /ping 请求。此处理程序始终返回 "Ok."（末尾带换行符）。可用版本 18.12.13。另请参见 /replicas_status 检查副本的延迟。
将请求作为 URL 的 'query' 参数发送，或作为 POST 发送。或者将查询的开头放在 'query' 参数中，其余部分放在 POST 中（稍后我们将解释为什么需要这样）。默认情况下，URL 的大小限制为 1 MiB，可以通过 http_max_uri_size 设置进行更改。
如果成功，您将收到 200 响应代码和响应体中的结果。 如果发生错误，您将收到 500 响应代码和响应体中的错误描述文本。
使用 GET 方法时，设定为 'readonly'。换句话说，对于修改数据的查询，您只能使用 POST 方法。您可以在 POST 身体中或 URL 参数中发送查询本身。
示例:
如您所见，curl 在空格需要 URL 转义时有些不便。
虽然 wget 自行转义所有内容，但我们不建议使用它，因为它在使用 HTTP 1.1 时对保持连接和 Transfer-Encoding: chunked 的支持不好。
如果查询的一部分在参数中发送，另一部分在 POST 中，则在这两个数据部分之间插入换行符。 示例（这将不起作用）:
默认情况下，数据以 TabSeparated 格式返回。
您可以使用查询的 FORMAT 子句请求任何其他格式。
此外，您可以使用 'default_format' URL 参数或 'X-ClickHouse-Format' 头指定不同于 TabSeparated 的默认格式。
POST 方法的数据传输对于 INSERT 查询是必要的。在这种情况下，您可以在 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 支持以下 压缩方法:
gzipbrdeflatexzzstdlz4bz2snappy
要发送压缩的 POST 请求，请附加请求头 Content-Encoding: compression_method。
为了让 ClickHouse 压缩响应，启用 enable_http_compression 设置，并将 Accept-Encoding: compression_method 头附加到请求中。您可以在 http_zlib_compression_level 设置中配置所有压缩方法的数据压缩级别。
某些 HTTP 客户端可能默认就会解压缩来自服务器的数据（使用 gzip 和 deflate），即使您正确使用压缩设置，也可能会收到解压缩的数据。
示例
默认数据库
您可以使用 'database' URL 参数或 'X-ClickHouse-Database' 头来指定默认数据库。
默认情况下，默认数据库是注册在服务器设置中的数据库。默认情况下，这个数据库叫做 'default'。另外，您也可以始终在表名之前使用点来指定数据库。
用户名和密码可以通过三种方式之一指出：
- 使用 HTTP 基本认证。示例:
- 在 'user' 和 'password' URL 参数中 (我们不建议使用这种方法，因为参数可能会被 Web 代理记录并缓存到浏览器）。示例:
- 使用 'X-ClickHouse-User' 和 'X-ClickHouse-Key' 头。示例:
如果未指定用户名，则使用 default 名称。如果未指定密码，则使用空密码。
您还可以使用 URL 参数指定单个查询或整个设置配置文件的任何设置。示例: http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1
有关更多信息，请参见 设置 部分。
有关其他参数的信息，请参见“SET”部分。
在 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。头部序列示例:
可能的头字段:
read_rows— 读取的行数。read_bytes— 读取的数据量（以字节为单位）。total_rows_to_read— 要读取的总行数。written_rows— 写入的行数。written_bytes— 写入的数据量（以字节为单位）。
如果 HTTP 连接丢失，正在运行的请求不会自动停止。解析和数据格式化在服务器端进行，使用网络可能效率不高。 可选的 'query_id' 参数可以作为查询 ID 发送（任何字符串）。有关更多信息，请参见“设置，替换正在运行的查询”部分。
可选的 'quota_key' 参数可以作为配额键发送（任何字符串）。有关更多信息，请参见“配额”部分。
HTTP 接口允许传递外部数据（外部临时表）进行查询。有关更多信息，请参见“查询处理的外部数据”部分。
响应缓冲
您可以在服务器端启用响应缓冲。为此提供了 buffer_size 和 wait_end_of_query URL 参数。
还可以使用设置 http_response_buffer_size 和 http_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 头首先发送，带有 HTTP 200 代码，随后是 HTTP 主体，然后错误以纯文本形式注入到正文中。
这种行为与使用的格式无关，无论是 Native、TSV 还是 JSON；错误消息始终会在响应流的中间。
您可以通过启用 wait_end_of_query=1（响应缓冲）来缓解此问题。在这种情况下，将延迟发送 HTTP 头，直到整个查询解决为止。
然而，这并不能完全解决问题，因为结果仍然必须适合 http_response_buffer_size，而其他设置如 send_progress_in_http_headers 可能会干扰头的延迟。
捕获所有错误的唯一方法是分析 HTTP 正文，然后再使用所需的格式进行解析。
带参数的查询
您可以创建一个带参数的查询，并通过相应的 HTTP 请求参数传递值。有关更多信息，请参见 CLI 的带参数查询。
示例
URL 参数中的制表符
查询参数是从“转义”格式解析的。这有一些好处，例如可以明确无误地将 null 解析为 \N。这意味着制表符字符应该编码为 \t（或者 \ 和制表符）。例如，以下内容在 abc 和 123 之间包含一个实际的制表符，并且输入字符串被拆分为两个值:
然而，如果您尝试在 URL 参数中使用 %09 编码实际的制表符，则不会正确解析:
如果您使用 URL 参数，您需要将 \t 编码为 %5C%09。例如:
预定义 HTTP 接口
ClickHouse 通过 HTTP 接口支持特定查询。例如，您可以如下将数据写入表:
ClickHouse 还支持预定义 HTTP 接口，可以帮助您更轻松地与第三方工具集成，例如 Prometheus exporter。
示例:
- 首先，将此部分添加到服务器配置文件:
- 您现在可以直接请求 URL 以获取 Prometheus 格式的数据:
正如示例所示，如果在 config.xml 文件中配置了 http_handlers，并且 http_handlers 可以包含多个 rules。ClickHouse 将匹配接收到的 HTTP 请求到 rule 中的预定义类型，并运行第一个匹配的处理程序。然后，ClickHouse 会在匹配成功时执行相应的预定义查询。
现在 rule 可以配置 method、headers、url 和 handler:
-
method负责匹配 HTTP 请求的方法部分。method完全符合 HTTP 协议中 method 的定义。这是一个可选配置。如果在配置文件中未定义，则不会匹配 HTTP 请求的方法部分。 -
url负责匹配 HTTP 请求的 URL 部分。它与 RE2 的正则表达式兼容。这是一个可选配置。如果在配置文件中未定义，则不会匹配 HTTP 请求的 URL 部分。 -
headers负责匹配 HTTP 请求的头部。这也与 RE2 的正则表达式兼容。这是一个可选配置。如果在配置文件中未定义，则不会匹配 HTTP 请求的头部部分。 -
handler包含主要处理部分。现在handler可以配置type、status、content_type、http_response_headers、response_content、query和query_param_name。type目前支持三种类型: predefined_query_handler、dynamic_query_handler、static。-
query— 与predefined_query_handler类型一起使用，处理程序被调用时执行查询。 -
query_param_name— 与dynamic_query_handler类型一起使用，提取并执行与 HTTP 请求参数中的query_param_name值相对应的值。 -
status— 与static类型一起使用，响应状态代码。 -
content_type— 与任意类型一起使用，响应 content-type。 -
http_response_headers— 与任意类型一起使用，响应头映射。可用于设置内容类型。 -
response_content— 与static类型一起使用，发送到客户端的响应内容，当使用前缀 'file://' 或 'config://' 时，从文件或配置中查找内容并发送到客户端。
-
接下来是不同 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/> 规则。
示例:
在一个 predefined_query_handler 中只支持一个 query。
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 可以返回指定的内容。
示例：
返回一条消息。
http_response_headers 可以用于设置内容类型，而不是 content_type。
从配置中找到发送给客户端的内容。
从文件中找到发送给客户端的内容。
有效的 JSON/XML 响应于 HTTP 流中的异常
在 HTTP 运行查询时，如果数据的一部分已经被发送，则可能会发生异常。通常即使在输出数据时使用了某种特定的数据格式，异常也会以纯文本形式发送给客户端，并且输出可能在指定的数据格式方面变得无效。为了防止这种情况，您可以使用设置 http_write_exception_in_output_format（默认启用），这将告诉 ClickHouse 在指定格式中写入异常（当前支持 XML 和 JSON* 格式）。
示例：