ClickHouse-2接口
客户端
ClickHouse提供了两个网络接口(两个都可以选择包装在TLS中以增加安全性):
- HTTP, 包含文档，易于使用。
- Native TCP，简单，方便使用。
在大多数情况下，建议使用适当的工具或库，而不是直接与它们交互。Yandex官方支持的项目有:
- 命令行客户端
- JDBC驱动
- ODBC驱动
- C++客户端
还有一些广泛的第三方库可供ClickHouse使用:
- 客户端库
- 第三方集成库
- 可视化UI
命令行客户端
ClickHouse提供了一个原生命令行客户端clickhouse-client客户端支持命令行支持的更多信息详见Configuring。
安装部署后，系统默认会安装clickhouse-client(同时它属于clickhouse-client安装包中)。
$ clickhouse-client
ClickHouse client version 19.17.1.1579 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 19.17.1 revision 54428.
:)
使用方式?
客户端可以在交互和非交互(批处理)模式下使用。要使用批处理模式，请指定query参数，或将数据发送到stdin(它会验证stdin是否是终端)，或两者同时进行。与HTTP接口类似，当使用query参数并向stdin发送数据时，客户端请求就是一行一行的stdin输入作为query的参数。这种方式在大规模的插入请求中非常方便。
使用客户端插入数据的示例：
$ echo -ne "1, 'some text', '2016-08-14 00:00:00'\n2, 'some more text', '2016-08-14 00:00:01'" | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
$ cat <<_EOF | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
3, 'some text', '2016-08-14 00:00:00'
4, 'some more text', '2016-08-14 00:00:01'
_EOF
$ cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
查询语法?
像平常一样格式化一个查询，然后把你想要从app参数传递到查询的值用大括号格式化，格式如下:
{<name>:<data type>}
配置?
您可以通过以下方式传入参数到clickhouse-client中（所有的参数都有默认值）：
-
通过命令行
命令行参数会覆盖默认值和配置文件的配置。
-
配置文件
配置文件的配置会覆盖默认值
命令行参数?
--host, -h-– 服务端的host名称, 默认是localhost。您可以选择使用host名称或者IPv4或IPv6地址。--port– 连接的端口，默认值：9000。注意HTTP接口以及TCP原生接口使用的是不同端口。--user, -u– 用户名。 默认值：default。--password– 密码。 默认值：空字符串。--query, -q– 使用非交互模式查询。--database, -d– 默认当前操作的数据库. 默认值：服务端默认的配置（默认是default）。--multiline, -m– 如果指定，允许多行语句查询（Enter仅代表换行，不代表查询语句完结）。--multiquery, -n– 如果指定, 允许处理用;号分隔的多个查询，只在非交互模式下生效。--format, -f– 使用指定的默认格式输出结果。--vertical, -E– 如果指定，默认情况下使用垂直格式输出结果。这与–format=Vertical相同。在这种格式中，每个值都在单独的行上打印，这种方式对显示宽表很有帮助。--time, -t– 如果指定，非交互模式下会打印查询执行的时间到stderr中。--stacktrace– 如果指定，如果出现异常，会打印堆栈跟踪信息。--config-file– 配置文件的名称。--secure– 如果指定，将通过安全连接连接到服务器。--history_file— 存放命令历史的文件的路径。--param_— 查询参数配置查询参数.
配置文件?
clickhouse-client使用以下第一个配置文件：
- 通过
--config-file参数指定。 ./clickhouse-client.xml~/.clickhouse-client/config.xml/etc/clickhouse-client/config.xml
配置文件示例:
<config>
<user>usernameuser>
<password>passwordpassword>
<secure>Falsesecure>
config>原生接口（TCP）
原生接口协议用于命令行客户端，用于分布式查询处理期间的服务器间通信，以及其他C++ 程序。不幸的是，原生ClickHouse协议还没有正式的规范，但它可以从ClickHouse源代码从这里开始或通过拦截和分析TCP流量进行逆向工程。
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.
通过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本身会对所有内容进行转义，但我们不推荐使用它，因为在使用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
默认情况下，返回的数据是TabSeparated格式的，更多信息，见Formats部分。
您可以使用查询的FORMAT子句来设置其他格式。
另外，还可以使用default_formatURL参数或X-ClickHouse-Format头来指定TabSeparated之外的默认格式。
$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @-
┏━━━┓
┃ 1 ┃
┡━━━┩
│ 1 │
└───┘
使用类似INSERT的查询来插入数据：
$ echo 'INSERT INTO t VALUES (1),(2),(3)' | curl 'http://localhost:8123/' --data-binary @-
您可以指定任何数据格式。Values格式与将INSERT写入t值时使用的格式相同:
$ echo '(7),(8),(9)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20Values' --data-binary @-
从表中读取内容。由于查询处理是并行的，数据以随机顺序输出。
$ curl 'http://localhost:8123/?query=SELECT%20a%20FROM%20t'
7
8
9
10
11
12
1
2
3
4
5
6
成功请求后并不会返回数据，返回一个空的响应体。
在传输数据时，可以使用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/'
默认情况下，在服务器设置中注册的数据库被用作默认数据库。默认情况下，它是名为default的数据库。或者，您可以始终在表名之前使用点来指定数据库。
用户名和密码可以通过以下三种方式指定：
- 通过HTTP Basic Authentication。示例：
$ echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -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 @-
有关其他参数的信息，请参考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"}
查询请求响应状态码和HTTP头被发送到客户端后，若发生查询处理出错，使用缓冲区可以避免这种情况的发生。在这种情况下，响应主体的结尾会写入一条错误消息，而在客户端，只能在解析阶段检测到该错误。
查询参数?
您可以使用参数创建查询，并通过相应的HTTP请求参数为它们传递值。有关更多信息，请参见CLI查询参数。
示例?
$ curl -sS "?param_id=2¶m_phrase=test" -d "SELECT * FROM table WHERE int_column = {id:UInt8} and string_column = {phrase:String}"
ClickHouse还支持预定义的HTTP接口，可以帮助您更容易与第三方工具集成，如Prometheus Exporter.
示例:
- 首先，将此部分添加到服务器配置文件中:
<http_handlers>
<rule>
<url>/predefined_queryurl>
<methods>POST,GETmethods>
<handler>
<type>predefined_query_handlertype>
<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>
正如您从示例中看到的，如果在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>[^/]+)(/(?P[^/]+))?]]>url>
<method>GETmethod>
<headers>
<XXX>TEST_HEADER_VALUEXXX>
<PARAMS_XXX>[^/]+)(/(?P[^/]+))?]]>PARAMS_XXX>
headers>
<handler>
<type>predefined_query_handlertype>
<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>
!!! note "警告" 在一个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_DYNAMICXXX> headers>
<handler>
<type>dynamic_query_handlertype>
<query_param_name>query_paramquery_param_name>
handler>
rule>
http_handlers>
static?
static可以返回content_type, status和response_content。response_content可以返回指定的内容。
示例:
返回信息.
<http_handlers>
<rule>
<methods>GETmethods>
<headers><XXX>xxxXXX>headers>
<url>/hiurl>
<handler>
<type>statictype>
<status>402status>
<content_type>text/html; charset=UTF-8content_type>
<response_content>Say Hi!response_content>
handler>
rule>
http_handlers>
从配置中查找发送到客户端的内容。
<get_config_static_handler>