ClickHouse HTTP客户端
HTTP接口允许您在任何编程语言的任何平台上使用ClickHouse。我们使用它在Java和Perl以及shell脚本中工作。在其他部门中,HTTP接口用于Perl、Python和Go。HTTP接口比原生接口受到更多的限制,但它具有更好的兼容性。
默认情况下,clickhouse-server会在8123端口上监控HTTP请求(这可以在配置中修改)。
如果你发送了一个未携带任何参数的GET /请求,它会返回一个字符串 «Ok.»(结尾有换行)。可以将它用在健康检查脚本中。
如果你发送了一个未携带任何参数的GET /请求,它返回响应码200和OK字符串定义,可在Http服务响应配置定义(在末尾添加换行)
$ curl 'http://localhost:8123/' Ok.
Web UI 可以通过这个地址访问: http://localhost:8123/play.
在运行状况检查脚本中,使用GET /ping请求。这个处理方法总是返回 "Ok"。(以换行结尾)。可从18.12.13版获得。请参见' /replicas_status '检查复制集的延迟。
$ curl 'http://localhost:8123/ping' Ok. $ curl 'http://localhost:8123/replicas_status' Ok.
通过URL中的 query 参数来发送请求,或者发送POST请求,或者将查询的开头部分放在URL的query参数中,其他部分放在POST中(我们会在后面解释为什么这样做是有必要的)。URL的大小会限制在16KB,所以发送大型查询时要时刻记住这点。
如果请求成功,将会收到200的响应状态码和响应主体中的结果。
如果发生了某个异常,将会收到500的响应状态码和响应主体中的异常描述信息。
当使用GET方法请求时,readonly会被设置。换句话说,若要作修改数据的查询,只能发送POST方法的请求。可以将查询通过POST主体发送,也可以通过URL参数发送。
示例:
$ curl 'http://localhost:8123/?query=SELECT%201' 1 $ wget -nv -O- 'http://localhost:8123/?query=SELECT 1' 1 $ echo -ne 'GET /?query=SELECT%201 HTTP/1.0\r\n\r\n' | nc localhost 8123 HTTP/1.0 200 OK Date: Wed, 27 Nov 2019 10:30:18 GMT Connection: Close Content-Type: text/tab-separated-values; charset=UTF-8 X-ClickHouse-Server-Display-Name: clickhouse.ru-central1.internal X-ClickHouse-Query-Id: 5abe861c-239c-467f-b955-8a201abb8b7f X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} 1
可以看到,curl 命令由于空格需要 URL 转义,所以不是很方便。尽管 wget 命令对url做了 URL 转义,但我们并不推荐使用他,因为在 HTTP 1.1 协议下使用 keep-alive 和 Transfer-Encoding: chunked 头部设置它并不能很好的工作。
$ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @- 1 $ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @- 1 $ echo '1' | curl 'http://localhost:8123/?query=SELECT' --data-binary @- 1
如您所见,curl有些不方便,因为空格必须进行URL转义。
尽管wget本身会对所有内容进行转义,但我们不推荐使用它,因为在使用keepalive和传输编码chunked时,它在HTTP 1.1上不能很好地工作。
$ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @- 1 $ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @- 1 $ echo '1' | curl 'http://localhost:8123/?query=SELECT' --data-binary @- 1
如果部分查询是在参数中发送的,部分是在POST中发送的,则在这两个数据部分之间插入换行。
错误示例:
$ echo 'ECT 1' | curl 'http://localhost:8123/?query=SEL' --data-binary @- Code: 59, e.displayText() = DB::Exception: Syntax error: failed at position 0: SEL ECT 1 , expected One of: SHOW TABLES, SHOW DATABASES, SELECT, INSERT, CREATE, ATTACH, RENAME, DROP, DETACH, USE, SET, OPTIMIZE., e.what() = DB::Exception
默认情况下,返回的数据是TabSeparated格式的,更多信息,见Formats部分。
您可以使用查询的FORMAT子句来设置其他格式。
另外,还可以使用default_formatURL参数或X-ClickHouse-Format头来指定TabSeparated之外的默认格式。
$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @- ┏━━━┓ ┃ 1 ┃ ┡━━━┩ │ 1 │ └───┘
INSERT必须通过POST方法来插入数据。在这种情况下,您可以在URL参数中编写查询的开始部分,并使用POST传递要插入的数据。例如,要插入的数据可以是来自MySQL的一个以tab分隔的存储。通过这种方式,INSERT查询替换了从MySQL查询的LOAD DATA LOCAL INFILE。
示例: 创建一个表:
$ echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | curl 'http://localhost:8123/' --data-binary @-
使用类似INSERT的查询来插入数据:
$ echo 'INSERT INTO t VALUES (1),(2),(3)' | curl 'http://localhost:8123/' --data-binary @-
数据可以从查询中单独发送:
$ echo '(4),(5),(6)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20VALUES' --data-binary @-
您可以指定任何数据格式。Values格式与将INSERT写入t值时使用的格式相同:
$ echo '(7),(8),(9)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20Values' --data-binary @-
若要插入tab分割的数据,需要指定对应的格式:
$ echo -ne '10\n11\n12\n' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20TabSeparated' --data-binary @-
从表中读取内容。由于查询处理是并行的,数据以随机顺序输出。
$ curl 'http://localhost:8123/?query=SELECT%20a%20FROM%20t' 7 8 9 10 11 12 1 2 3 4 5 6
删除表:
$ echo 'DROP TABLE t' | curl 'http://localhost:8123/' --data-binary @-
成功请求后并不会返回数据,返回一个空的响应体。
在传输数据时,可以使用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压缩级别设置中为所有压缩方法配置数据压缩级别。
您可以使用它在传输大量数据时减少网络流量,或者创建立即压缩的转储。
通过压缩发送数据的例子:
#Sending data to the server: $ curl -vsS "http://localhost:8123/?enable_http_compression=1" -d 'SELECT number FROM system.numbers LIMIT 10' -H 'Accept-Encoding: gzip' #Sending data to the client: $ echo "SELECT 1" | gzip -c | curl -sS --data-binary @- -H 'Content-Encoding: gzip' 'http://localhost:8123/'
警告
一些HTTP客户端可能会在默认情况下从服务器解压数据(使用gzip和deflate),即使您未正确地使用了压缩设置,您也可能会得到解压数据。
您可以使用databaseURL参数或X-ClickHouse-Database头来指定默认数据库。
$ echo 'SELECT number FROM numbers LIMIT 10' | curl 'http://localhost:8123/?database=system' --data-binary @- 0 1 2 3 4 5 6 7 8 9
默认情况下,在服务器设置中注册的数据库被用作默认数据库。默认情况下,它是名为default的数据库。或者,您可以始终在表名之前使用点来指定数据库。
用户名和密码可以通过以下三种方式指定:
- 通过HTTP Basic Authentication。示例:
$ echo 'SELECT 1' | curl 'http://user:[email protected]:8123/' -d @-
- 通过URL参数中的user和password。示例:
$ echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @-
- 使用X-ClickHouse-User或X-ClickHouse-Key头指定,示例:
$ echo 'SELECT 1' | curl -H 'X-ClickHouse-User: user' -H 'X-ClickHouse-Key: password' 'http://localhost:8123/' -d @-
如果未指定用户名,则使用default。如果未指定密码,则使用空密码。
您还可以使用URL参数来指定处理单个查询或整个设置配置文件的任何设置。例子:http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1
更多信息,详见设置部分。
$ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @- 0 1 2 3 4 5 6 7 8 9
有关其他参数的信息,请参考SET一节。
类似地,您可以在HTTP协议中使用ClickHouse会话。为此,需要向请求添加session_idGET参数。您可以使用任何字符串作为会话ID。默认情况下,会话在60秒不活动后终止。要更改此超时配置,请修改服务器配置中的default_session_timeout设置,或向请求添加session_timeoutGET参数。要检查会话状态,使用session_check=1参数。一次只能在单个会话中执行一个查询。
您可以在X-ClickHouse-Progress响应头中收到查询进度的信息。为此,启用Http Header携带进度。示例:
X-ClickHouse-Progress: {"read_rows":"2752512","read_bytes":"240570816","total_rows_to_read":"8880128"} X-ClickHouse-Progress: {"read_rows":"5439488","read_bytes":"482285394","total_rows_to_read":"8880128"} X-ClickHouse-Progress: {"read_rows":"8783786","read_bytes":"819092887","total_rows_to_read":"8880128"}
显示字段信息:
- 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。这种情况下,存入内存的数据会被缓冲到服务端的一个临时文件中。
示例:
$ curl -sS 'http://localhost:8123/?max_result_bytes=4000000&buffer_size=3000000&wait_end_of_query=1' -d 'SELECT toUInt8(number) FROM system.numbers LIMIT 9000000 FORMAT RowBinary'
查询请求响应状态码和HTTP头被发送到客户端后,若发生查询处理出错,使用缓冲区可以避免这种情况的发生。在这种情况下,响应主体的结尾会写入一条错误消息,而在客户端,只能在解析阶段检测到该错误。
查询参数
您可以使用参数创建查询,并通过相应的HTTP请求参数为它们传递值。有关更多信息,请参见CLI查询参数。
示例
$ curl -sS "<address>?param_id=2¶m_phrase=test" -d "SELECT * FROM table WHERE int_column = {id:UInt8} and string_column = {phrase:String}"
特定的HTTP接口
ClickHouse通过HTTP接口支持特定的查询。例如,您可以如下所示向表写入数据:
$ echo '(4),(5),(6)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20VALUES' --data-binary @-
ClickHouse还支持预定义的HTTP接口,可以帮助您更容易与第三方工具集成,如Prometheus Exporter.
示例:
- 首先,将此部分添加到服务器配置文件中:
<http_handlers> <rule> <url>/predefined_query</url> <methods>POST,GET</methods> <handler> <type>predefined_query_handler</type> <query>SELECT * FROM system.metrics LIMIT 5 FORMAT Template SETTINGS format_template_resultset = 'prometheus_template_output_format_resultset', format_template_row = 'prometheus_template_output_format_row', format_template_rows_between_delimiter = '\n'</query> </handler> </rule> <rule>...</rule> <rule>...</rule> </http_handlers>
- 请求Prometheus格式的URL以获取数据:
$ curl -v 'http://localhost:8123/predefined_query' * Trying ::1... * Connected to localhost (::1) port 8123 (#0) > GET /predefined_query HTTP/1.1 > Host: localhost:8123 > User-Agent: curl/7.47.0 > Accept: */* > < HTTP/1.1 200 OK < Date: Tue, 28 Apr 2020 08:52:56 GMT < Connection: Keep-Alive < Content-Type: text/plain; charset=UTF-8 < X-ClickHouse-Server-Display-Name: i-mloy5trc < Transfer-Encoding: chunked < X-ClickHouse-Query-Id: 96fe0052-01e6-43ce-b12a-6b7370de6e8a < X-ClickHouse-Format: Template < X-ClickHouse-Timezone: Asia/Shanghai < Keep-Alive: timeout=3 < X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} < # HELP "Query" "Number of executing queries" # TYPE "Query" counter "Query" 1 # HELP "Merge" "Number of executing background merges" # TYPE "Merge" counter "Merge" 0 # HELP "PartMutation" "Number of mutations (ALTER DELETE/UPDATE)" # TYPE "PartMutation" counter "PartMutation" 0 # HELP "ReplicatedFetch" "Number of data parts being fetched from replica" # TYPE "ReplicatedFetch" counter "ReplicatedFetch" 0 # HELP "ReplicatedSend" "Number of data parts being sent to replicas" # TYPE "ReplicatedSend" counter "ReplicatedSend" 0 * Connection #0 to host localhost left intact * Connection #0 to host localhost left intact
正如您从示例中看到的,如果在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设置, 然后查询系统表以检查这些设置是否设置成功。
示例:
<http_handlers> <rule> <url><![CDATA[/query_param_with_url/\w+/(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></url> <method>GET</method> <headers> <XXX>TEST_HEADER_VALUE</XXX> <PARAMS_XXX><![CDATA[(?P<name_1>[^/]+)(/(?P<name_2>[^/]+))?]]></PARAMS_XXX> </headers> <handler> <type>predefined_query_handler</type> <query>SELECT value FROM system.settings WHERE name = {name_1:String}</query> <query>SELECT name, value FROM system.settings WHERE name = {name_2:String}</query> </handler> </rule> </http_handlers>
$ curl -H 'XXX:TEST_HEADER_VALUE' -H 'PARAMS_XXX:max_threads' 'http://localhost:8123/query_param_with_url/1/max_threads/max_final_threads?max_threads=1&max_final_threads=2' 1 max_final_threads 2
警告
在一个predefined_query_handler中,只支持insert类型的一个查询。
动态查询
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设置是否成功的值。
示例:
<http_handlers> <rule> <headers> <XXX>TEST_HEADER_VALUE_DYNAMIC</XXX> </headers> <handler> <type>dynamic_query_handler</type> <query_param_name>query_param</query_param_name> </handler> </rule> </http_handlers>
$ curl -H 'XXX:TEST_HEADER_VALUE_DYNAMIC' 'http://localhost:8123/own?max_threads=1&max_final_threads=2¶m_name_1=max_threads¶m_name_2=max_final_threads&query_param=SELECT%20name,value%20FROM%20system.settings%20where%20name%20=%20%7Bname_1:String%7D%20OR%20name%20=%20%7Bname_2:String%7D' max_threads 1 max_final_threads 2
static
static可以返回content_type, status和response_content。response_content可以返回指定的内容。
示例:
返回信息.
<http_handlers> <rule> <methods>GET</methods> <headers><XXX>xxx</XXX></headers> <url>/hi</url> <handler> <type>static</type> <status>402</status> <content_type>text/html; charset=UTF-8</content_type> <response_content>Say Hi!</response_content> </handler> </rule> </http_handlers>
$ curl -vv -H 'XXX:xxx' 'http://localhost:8123/hi' * Trying ::1... * Connected to localhost (::1) port 8123 (#0) > GET /hi HTTP/1.1 > Host: localhost:8123 > User-Agent: curl/7.47.0 > Accept: */* > XXX:xxx > < HTTP/1.1 402 Payment Required < Date: Wed, 29 Apr 2020 03:51:26 GMT < Connection: Keep-Alive < Content-Type: text/html; charset=UTF-8 < Transfer-Encoding: chunked < Keep-Alive: timeout=3 < X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} < * Connection #0 to host localhost left intact Say Hi!%
从配置中查找发送到客户端的内容。
<get_config_static_handler><![CDATA[<html ng-app="SMI2"><head><base href="http://ui.tabix.io/"></head><body><div ui-view="" class="content-ui"></div><script src="http://loader.tabix.io/master.js"></script></body></html>]]></get_config_static_handler> <http_handlers> <rule> <methods>GET</methods> <headers><XXX>xxx</XXX></headers> <url>/get_config_static_handler</url> <handler> <type>static</type> <response_content>config://get_config_static_handler</response_content> </handler> </rule> </http_handlers>
$ curl -v -H 'XXX:xxx' 'http://localhost:8123/get_config_static_handler' * Trying ::1... * Connected to localhost (::1) port 8123 (#0) > GET /get_config_static_handler HTTP/1.1 > Host: localhost:8123 > User-Agent: curl/7.47.0 > Accept: */* > XXX:xxx > < HTTP/1.1 200 OK < Date: Wed, 29 Apr 2020 04:01:24 GMT < Connection: Keep-Alive < Content-Type: text/plain; charset=UTF-8 < Transfer-Encoding: chunked < Keep-Alive: timeout=3 < X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} < * Connection #0 to host localhost left intact <html ng-app="SMI2"><head><base href="http://ui.tabix.io/"></head><body><div ui-view="" class="content-ui"></div><script src="http://loader.tabix.io/master.js"></script></body></html>%
从发送到客户端的文件中查找内容。
<http_handlers> <rule> <methods>GET</methods> <headers><XXX>xxx</XXX></headers> <url>/get_absolute_path_static_handler</url> <handler> <type>static</type> <content_type>text/html; charset=UTF-8</content_type> <response_content>file:///absolute_path_file.html</response_content> </handler> </rule> <rule> <methods>GET</methods> <headers><XXX>xxx</XXX></headers> <url>/get_relative_path_static_handler</url> <handler> <type>static</type> <content_type>text/html; charset=UTF-8</content_type> <response_content>file://./relative_path_file.html</response_content> </handler> </rule> </http_handlers>
$ user_files_path='/var/lib/clickhouse/user_files' $ sudo echo "<html><body>Relative Path File</body></html>" > $user_files_path/relative_path_file.html $ sudo echo "<html><body>Absolute Path File</body></html>" > $user_files_path/absolute_path_file.html $ curl -vv -H 'XXX:xxx' 'http://localhost:8123/get_absolute_path_static_handler' * Trying ::1... * Connected to localhost (::1) port 8123 (#0) > GET /get_absolute_path_static_handler HTTP/1.1 > Host: localhost:8123 > User-Agent: curl/7.47.0 > Accept: */* > XXX:xxx > < HTTP/1.1 200 OK < Date: Wed, 29 Apr 2020 04:18:16 GMT < Connection: Keep-Alive < Content-Type: text/html; charset=UTF-8 < Transfer-Encoding: chunked < Keep-Alive: timeout=3 < X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} < <html><body>Absolute Path File</body></html> * Connection #0 to host localhost left intact $ curl -vv -H 'XXX:xxx' 'http://localhost:8123/get_relative_path_static_handler' * Trying ::1... * Connected to localhost (::1) port 8123 (#0) > GET /get_relative_path_static_handler HTTP/1.1 > Host: localhost:8123 > User-Agent: curl/7.47.0 > Accept: */* > XXX:xxx > < HTTP/1.1 200 OK < Date: Wed, 29 Apr 2020 04:18:31 GMT < Connection: Keep-Alive < Content-Type: text/html; charset=UTF-8 < Transfer-Encoding: chunked < Keep-Alive: timeout=3 < X-ClickHouse-Summary: {"read_rows":"0","read_bytes":"0","written_rows":"0","written_bytes":"0","total_rows_to_read":"0"} < <html><body>Relative Path File</body></html> * Connection #0 to host localhost left intact
ClickHouse支持MySQL wire通讯协议。可以通过在配置文件中设置 mysql_port 来启用它:<mysql_port>9004</mysql_port>使用命令 ...