ClickHouse 通过 HTTP 接口导入 JSON 格式的数据

本文介绍通过 ClickHouse 的 HTTP 接口导入 JSON 格式的数据。由于 HTTP 协议的通用性，HTTP 接口几乎适用于任何编程语言及 HTTP 协议的客户端工具，如：Python、Ruby、Rust、Perl、PHP、curl、wget、Postman 等。较之 CSV 格式，JSON 格式的数据自带对象定义，且对象属性间顺序无关，更便于理解，但因为每个对象都需要写出属性名，也增加了数据的长度。本文采用 curl 命令及 ClickHouse 支持的众多 JSON 格式中的 JSONEachRow 格式演示数据导入操作，顾名思义，该格式意为：每一个 JSON 对象占用一行。

定义表

假设有如下表定义：

CREATE TABLE IF NOT EXISTS default.user (
  id UInt64 NOT NULL,
  name String NOT NULL,
  description String NULL
) ENGINE = MergeTree()
ORDER BY id;

导入数据

方法一

将 INSERT 语句写入到数据文件的第一行，数据文件 data.sql 内容如下：

INSERT INTO default.user FORMAT JSONEachRow
{"id":1,"name":"Allen","description":"John Allen"}
{"id":2,"name":"Bill","description":"Bill Gates"}

用 curl 命令导入：

curl -i -X POST 'http://127.0.0.1:8123/' --data-binary "@./data.sql"

执行完该命令后 ClickHouse 服务器响应：

HTTP/1.1 200 OK
Date: Thu, 04 Nov 2021 08:37:14 GMT
Connection: Keep-Alive
Content-Type: text/plain; charset=UTF-8
X-ClickHouse-Server-Display-Name: clickhouse
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"}

方法二

将 INSERT 语句作为请求 URL 的 query 参数，数据文件不再包含 INSERT 语句，仅包含 JSON 数据。这时的 URL 为：

http://127.0.0.1:8123/?query=INSERT%20INTO%20default.user%20FORMAT%20JSONEachRow

query 参数为「INSERT INTO default.user FORMAT JSONEachRow」经 URL 编码后的值，curl 不会自动做 URL 编码。

这时数据文件 data.json 的内容为：

{"id":1,"name":"Allen","description":"John Allen"}
{"id":2,"name":"Bill","description":"Bill Gates"}

用 curl 命令导入：

curl -i -X POST 'http://127.0.0.1:8123/?query=INSERT%20INTO%20default.user%20FORMAT%20JSONEachRow' --data-binary "@./data.json"

执行完该命令后 ClickHouse 服务器响应：

HTTP/1.1 200 OK
Date: Thu, 04 Nov 2021 08:37:14 GMT
Connection: Keep-Alive
Content-Type: text/plain; charset=UTF-8
X-ClickHouse-Server-Display-Name: clickhouse
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"}

总结

本文演示了通过 ClickHouse 的 HTTP 接口，用 curl 命令将 JSON 格式的数据导入到数据表。

ClickHouse HTTP 接口的详细说明，可以参看官方文档：https://clickhouse.com/docs/en/interfaces/http/
JSONEachRow 格式的详细说明，可以参看官方文档：https://clickhouse.com/docs/en/interfaces/formats/#jsoneachrow