HTTP客户端

HTTP接口允许您在任何编程语言的任何平台上使用ClickHouse。我们使用它在Java和Perl以及shell脚本中工作。在其他部门中，HTTP接口用于Perl、Python和Go。HTTP接口比原生接口受到更多的限制，但它具有更好的兼容性。

默认情况下，clickhouse-server会在8123端口上监控HTTP请求（这可以在配置中修改）。

如果你发送了一个未携带任何参数的GET /请求，它会返回一个字符串 «Ok.»（结尾有换行）。可以将它用在健康检查脚本中。

如果你发送了一个未携带任何参数的GET /请求，它返回响应码200和OK字符串定义，可在Http服务响应配置定义(在末尾添加换行)

Web UI 可以通过这个地址访问: http://localhost:8123/play. 在运行状况检查脚本中，使用GET /ping请求。这个处理方法总是返回 "Ok"。(以换行结尾)。可从18.12.13版获得。请参见' /replicas_status '检查复制集的延迟。

通过URL中的 query 参数来发送请求，或者发送POST请求，或者将查询的开头部分放在URL的query参数中，其他部分放在POST中（我们会在后面解释为什么这样做是有必要的）。URL的大小会限制在16KB，所以发送大型查询时要时刻记住这点。

如果请求成功，将会收到200的响应状态码和响应主体中的结果。 如果发生了某个异常，将会收到500的响应状态码和响应主体中的异常描述信息。

当使用GET方法请求时，readonly会被设置。换句话说，若要作修改数据的查询，只能发送POST方法的请求。可以将查询通过POST主体发送，也可以通过URL参数发送。

示例:

可以看到，curl 命令由于空格需要 URL 转义，所以不是很方便。尽管 wget 命令对url做了 URL 转义，但我们并不推荐使用他，因为在 HTTP 1.1 协议下使用 keep-alive 和 Transfer-Encoding: chunked 头部设置它并不能很好的工作。

如您所见，curl有些不方便，因为空格必须进行URL转义。 尽管wget本身会对所有内容进行转义，但我们不推荐使用它，因为在使用keepalive和传输编码chunked时，它在HTTP 1.1上不能很好地工作。

如果部分查询是在参数中发送的，部分是在POST中发送的，则在这两个数据部分之间插入换行。

错误示例：

默认情况下，返回的数据是TabSeparated格式的，更多信息，见Formats部分。

您可以使用查询的FORMAT子句来设置其他格式。

另外，还可以使用default_formatURL参数或X-ClickHouse-Format头来指定TabSeparated之外的默认格式。

INSERT必须通过POST方法来插入数据。在这种情况下，您可以在URL参数中编写查询的开始部分，并使用POST传递要插入的数据。例如，要插入的数据可以是来自MySQL的一个以tab分隔的存储。通过这种方式，INSERT查询替换了从MySQL查询的LOAD DATA LOCAL INFILE。

示例: 创建一个表:

使用类似INSERT的查询来插入数据：

数据可以从查询中单独发送：

您可以指定任何数据格式。Values格式与将INSERT写入t值时使用的格式相同:

若要插入tab分割的数据，需要指定对应的格式：

从表中读取内容。由于查询处理是并行的，数据以随机顺序输出。

删除表：

成功请求后并不会返回数据，返回一个空的响应体。

在传输数据时，可以使用ClickHouse内部压缩格式。压缩的数据具有非标准格式，您需要使用特殊的clickhouse-compressor程序来处理它(它是与clickhouse-client包一起安装的)。为了提高数据插入的效率，您可以通过使用http_native_compression_disable_checksumming_on_decompress设置禁用服务器端校验。

如果在URL中指定了compress=1，服务会返回压缩的数据。 如果在URL中指定了decompress=1，服务会解压通过POST方法发送的数据。

您也可以选择使用HTTP compression。发送一个压缩的POST请求，附加请求头Content-Encoding: compression_method。为了使ClickHouse响应，您必须附加Accept-Encoding: compression_method。ClickHouse支持gzip，br和deflate compression methods。要启用HTTP压缩，必须使用ClickHouse启用Http压缩配置。您可以在Http zlib压缩级别设置中为所有压缩方法配置数据压缩级别。

您可以使用它在传输大量数据时减少网络流量，或者创建立即压缩的转储。

通过压缩发送数据的例子:

Danger

一些HTTP客户端可能会在默认情况下从服务器解压数据(使用gzip和deflate)，即使您未正确地使用了压缩设置，您也可能会得到解压数据。

您可以使用databaseURL参数或X-ClickHouse-Database头来指定默认数据库。

默认情况下，在服务器设置中注册的数据库被用作默认数据库。默认情况下，它是名为default的数据库。或者，您可以始终在表名之前使用点来指定数据库。

用户名和密码可以通过以下三种方式指定：

1. 通过HTTP Basic Authentication。示例：

1. 通过URL参数中的user和password。示例：

1. 使用X-ClickHouse-User或X-ClickHouse-Key头指定，示例:

如果未指定用户名，则使用default。如果未指定密码，则使用空密码。 您还可以使用URL参数来指定处理单个查询或整个设置配置文件的任何设置。例子:http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1

更多信息，详见设置部分。

有关其他参数的信息，请参考SET一节。

类似地，您可以在HTTP协议中使用ClickHouse会话。为此，需要向请求添加session_idGET参数。您可以使用任何字符串作为会话ID。默认情况下，会话在60秒不活动后终止。要更改此超时配置，请修改服务器配置中的default_session_timeout设置，或向请求添加session_timeoutGET参数。要检查会话状态，使用session_check=1参数。一次只能在单个会话中执行一个查询。

您可以在X-ClickHouse-Progress响应头中收到查询进度的信息。为此，启用Http Header携带进度。示例：

显示字段信息:

• read_rows — 读取的行数。
• read_bytes — 读取的数据字节数。
• total_rows_to_read — 读取的数据总行数。
• written_rows — 写入数据行数。
• written_bytes — 写入数据字节数。

如果HTTP连接丢失，运行的请求不会自动停止。解析和数据格式化是在服务器端执行的，使用Http连接可能无效。

可选的query_id参数可能当做query ID传入（或者任何字符串）。更多信息，详见replace_running_query部分。

可选的quota_key参数可能当做quota key传入（或者任何字符串）。更多信息，详见Quotas部分。

HTTP接口允许传入额外的数据（外部临时表）来查询。更多信息，详见外部数据查询处理部分。

响应缓冲

可以在服务器端启用响应缓冲。提供了buffer_size和wait_end_of_query两个URL参数来达此目的。

buffer_size决定了查询结果要在服务内存中缓冲多少个字节数据. 如果响应体比这个阈值大，缓冲区会写入到HTTP管道，剩下的数据也直接发到HTTP管道中。

为了确保整个响应体被缓冲，可以设置wait_end_of_query=1。这种情况下，存入内存的数据会被缓冲到服务端的一个临时文件中。

示例:

查询请求响应状态码和HTTP头被发送到客户端后，若发生查询处理出错，使用缓冲区可以避免这种情况的发生。在这种情况下，响应主体的结尾会写入一条错误消息，而在客户端，只能在解析阶段检测到该错误。

查询参数

您可以使用参数创建查询，并通过相应的HTTP请求参数为它们传递值。有关更多信息，请参见CLI查询参数。

示例

特定的HTTP接口

ClickHouse通过HTTP接口支持特定的查询。例如，您可以如下所示向表写入数据:

ClickHouse还支持预定义的HTTP接口，可以帮助您更容易与第三方工具集成，如Prometheus Exporter.

示例:

• 首先，将此部分添加到服务器配置文件中:

• 请求Prometheus格式的URL以获取数据:

正如您从示例中看到的，如果在config.xml文件中配置了http_handlers，并且http_handlers可以包含许多规则。ClickHouse将把接收到的HTTP请求与rule中的预定义类型进行匹配，第一个匹配的将运行处理程序。如果匹配成功，ClickHouse将执行相应的预定义查询。

现在rule可以配置method， header， url， handler:

• method 负责匹配HTTP请求的方法部分。 method完全符合HTTP协议中method的定义。这是一个可选的配置。如果它没有在配置文件中定义，那么它与HTTP请求的方法部分不匹配。

• url 负责匹配HTTP请求的URL部分。它匹配RE2正则表达式。这是一个可选的配置。如果配置文件中没有定义它，则它与HTTP请求的URL部分不匹配。

• headers 负责匹配HTTP请求的头部分。它与RE2的正则表达式兼容。这是一个可选的配置。如果它没有在配置文件中定义，那么它与HTTP请求的头部分不匹配。

• handler 包含主要的处理部分。现在handler可以配置type, status, content_type, response_content, query, query_param_name。 type 目前支持三种类型:特定查询, 动态查询, static.

  • query — 使用predefined_query_handler类型，在调用处理程序时执行查询。

  • query_param_name — 与dynamic_query_handler类型一起使用，提取并执行HTTP请求参数中与query_param_name值对应的值。

  • status — 与static类型一起使用，响应状态代码。

  • content_type — 与static类型一起使用，响应信息content-type。

  • response_content — 与static类型一起使用，响应发送给客户端的内容，当使用前缀file://或config://时，从发送给客户端的文件或配置中查找内容。

接下来是不同type的配置方法。

特定查询

predefined_query_handler 支持设置Settings和query_params参数。您可以将query配置为predefined_query_handler类型。

query 是一个预定义的predefined_query_handler查询，它由ClickHouse在匹配HTTP请求并返回查询结果时执行。这是一个必须的配置。

以下是定义的max_threads和max_final_threads设置， 然后查询系统表以检查这些设置是否设置成功。

示例:

Danger

在一个predefined_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，queries设置是否成功的值。

示例:

static

static可以返回content_type, status和response_content。response_content可以返回指定的内容。

示例:

返回信息.

从配置中查找发送到客户端的内容。

从发送到客户端的文件中查找内容。