diff --git a/docs/zh/interfaces/cli.md b/docs/zh/interfaces/cli.md deleted file mode 120000 index 04588066828..00000000000 --- a/docs/zh/interfaces/cli.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/cli.md \ No newline at end of file diff --git a/docs/zh/interfaces/cli.md b/docs/zh/interfaces/cli.md new file mode 100644 index 00000000000..a069a8ceb69 --- /dev/null +++ b/docs/zh/interfaces/cli.md @@ -0,0 +1,113 @@ +# 命令行客户端 + +通过命令行来访问 ClickHouse，您可以使用 `clickhouse-client` + +```bash +$ clickhouse-client +ClickHouse client version 0.0.26176. +Connecting to localhost:9000. +Connected to ClickHouse server version 0.0.26176.:) +``` + +该客户端支持命令行参数以及配置文件。查看更多，请看 "[配置](#interfaces_cli_configuration)" + +## 使用方式 + +这个客户端可以选择使用交互式与非交互式（批量）两种模式。 +使用批量模式，要指定 `query` 参数，或者发送数据到 `stdin`（它会检查 `stdin` 是否是 Terminal），或者两种同时使用。 +它与 HTTP 接口很相似，当使用 `query` 参数发送数据到 `stdin` 时，客户端请求就是一行一行的 `stdin` 输入作为 `query` 的参数。这种方式在大规模的插入请求中非常方便。 + +使用这个客户端插入数据的示例： + +```bash +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"; +``` + +在批量模式中，默认的数据格式是 `TabSeparated` 分隔的。您可以根据查询来灵活设置 FORMAT 格式。 + +默认情况下，在批量模式中只能执行单个查询。为了从一个 Script 中执行多个查询，可以使用 `--multiquery` 参数。除了 INSERT 请求外，这种方式在任何地方都有用。查询的结果会连续且不含分隔符地输出。 +同样的，为了执行大规模的查询，您可以为每个查询执行一次 `clickhouse-client`。但注意到每次启动 `clickhouse-client` 程序都需要消耗几十毫秒时间。 + +在交互模式下，每条查询过后，你可以直接输入下一条查询命令。 + +如果 `multiline` 没有指定（默认没指定）：为了执行查询，按下 Enter 即可。查询语句不是必须使用分号结尾。如果需要写一个多行的查询语句，可以在换行之前输入一个反斜杠` \ `，然后在您按下 Enter 键后，您就可以输入当前语句的下一行查询了。 + +如果 `multiline` 指定了：为了执行查询，需要以分号结尾并且按下 Enter 键。如果行末没有分号，将认为当前语句并没有输入完而要求继续输入下一行。 + +若只运行单个查询，分号后面的所有内容都会被忽略。 + +您可以指定 `\G` 来替代分号或者在分号后面，这表示 `Vertical` 的格式。在这种格式下，每一个值都会打印在不同的行中，这种方式对于宽表来说很方便。这个不常见的特性是为了兼容 MySQL 命令而加的。 + +命令行客户端是基于 `readline` 库（`history` 库或者 `libedit` 库, 或不基于其他库, 这取决于客户端是如何编译的）。换句话说，它可以使用我们熟悉的快捷键方式来操作以及保留历史命令。 +历史命令会写入在 `~/.clickhouse-client-history` 中。 + +默认情况下，输出的格式是 `PrettyCompact`。您可以通过 FORMAT 设置根据不同查询来修改格式，或者通过在查询末尾指定 `\G` 字符，或通过在命令行中使用 `--format` or `--vertical` 参数，或使用客户端的配置文件。 + +若要退出客户端，使用 Ctrl+D （或 Ctrl+C），或者输入以下其中一个命令：`exit`, `quit`, `logout`, `учше`, `йгше`, `дщпщге`, `exit;`, `quit;`, `logout;`, `учшеж`, `йгшеж`, `дщпщгеж`, `q`, `й`, `q`, `Q`, `:q`, `й`, `Й`, `Жй` + +当执行一个查询的时候，客户端会显示： + +1. 进度, 进度会每秒更新十次 （默认情况下）。 对于很快的查询，进度可能没有时间显示。 +2. 为了调试会显示解析且格式化后的查询语句。 +3. 指定格式的输出结果。 +4. 输出结果的行数的行数，经过的时间，以及查询处理的速度。 + +您可以通过 Ctrl+C 来取消一个长时间的查询。然而，您依然需要等待服务端来中止请求。在某个阶段去取消查询是不可能的。如果您不等待并再次按下 Ctrl + C，客户端将会退出。 + +命令行客户端允许通过外部数据 （外部临时表） 来查询。更多相关信息，请参考 "[外部数据查询处理](../../table_engines/external_data.html)". + + + +## 配置 + +您可以通过以下方式传入参数到 `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` – 配置文件的名称。 + +### 配置文件 + +`clickhouse-client` 使用一下第一个存在的文件： + +- 通过 `-config-file` 参数指定的文件. +- `./clickhouse-client.xml` +- `\~/.clickhouse-client/config.xml` +- `/etc/clickhouse-client/config.xml` + +配置文件示例: + +```xml + + username + password + +``` + diff --git a/docs/zh/interfaces/http_interface.md b/docs/zh/interfaces/http_interface.md deleted file mode 120000 index 4f0aa6e6a6a..00000000000 --- a/docs/zh/interfaces/http_interface.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/http_interface.md \ No newline at end of file diff --git a/docs/zh/interfaces/http_interface.md b/docs/zh/interfaces/http_interface.md new file mode 100644 index 00000000000..97acd050b91 --- /dev/null +++ b/docs/zh/interfaces/http_interface.md @@ -0,0 +1,215 @@ +# HTTP 接口 + +HTTP 接口可以让你通过任何平台和编程语言来使用 ClickHouse。我们用 Java 和 Perl 以及 shell 脚本来访问它。在其他的部门中，HTTP 接口会用在 Perl，Python 以及 Go 中。HTTP 接口比 TCP 原生接口更为局限，但是却有更好的兼容性。 + +默认情况下，clickhouse-server 会在端口 8123 上监控 HTTP 请求（这可以在配置中修改）。 +如果你发送了一个不带参数的 GET 请求，它会返回一个字符串 "Ok"（结尾有换行）。可以将它用在健康检查脚本中。 + +```bash +$ curl 'http://localhost:8123/' +Ok. +``` + +通过 URL 中的 `query` 参数来发送请求，或者发送 POST 请求，或者将查询的开头部分放在 URL 的 `query` 参数中，其他部分放在 POST 中（我们会在后面解释为什么这样做是有必要的）。URL 的大小会限制在 16 KB，所以发送大型查询时要时刻记住这点。 + +如果请求成功，将会收到 200 的响应状态码和响应主体中的结果。 +如果发生了某个异常，将会收到 500 的响应状态码和响应主体中的异常描述信息。 + +当使用 GET 方法请求时，`readonly` 会被设置。换句话说，若要作修改数据的查询，只能发送 POST 方法的请求。可以将查询通过 POST 主体发送，也可以通过 URL 参数发送。 + +Examples: + +```bash +$ curl 'http://localhost:8123/?query=SELECT%201' +1 + +$ wget -O- -q 'http://localhost:8123/?query=SELECT 1' +1 + +$ GET '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 +Connection: Close +Date: Fri, 16 Nov 2012 19:21:50 GMT + +1 +``` + +可以看到，curl 命令由于空格需要 URL 转义，所以不是很方便。尽管 wget 命令对url做了 URL 转义，但我们并不推荐使用他，因为在 HTTP 1.1 协议下使用 keep-alive 和 Transfer-Encoding: chunked 头部设置它并不能很好的工作。 + +```bash +$ 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 主体发送，两部分查询之间会一行空行插入。 +错误示例： + +```bash +$ 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 格式的，更多信息，见 "[数据格式]" 部分。 +可以使用 FORMAT 设置查询来请求不同格式。 + +```bash +$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @- +┏━━━┓ +┃ 1 ┃ +┡━━━┩ +│ 1 │ +└───┘ +``` + +INSERT 必须通过 POST 方法来插入数据。这种情况下，你可以将查询的开头部分放在 URL 参数中，然后用 POST 主体传入插入的数据。插入的数据可以是，举个例子，从 MySQL 导出的以 tab 分割的数据。在这种方式中，INSERT 查询取代了 LOAD DATA LOCAL INFILE from MySQL。 + +示例: 创建一个表: + +```bash +echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | POST 'http://localhost:8123/' +``` + +使用类似 INSERT 的查询来插入数据： + +```bash +echo 'INSERT INTO t VALUES (1),(2),(3)' | POST 'http://localhost:8123/' +``` + +数据可以从查询中单独发送： + +```bash +echo '(4),(5),(6)' | POST 'http://localhost:8123/?query=INSERT INTO t VALUES' +``` + +可以指定任何数据格式。值的格式和写入表 `t` 的值的格式相同： + +```bash +echo '(7),(8),(9)' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT Values' +``` + +若要插入 tab 分割的数据，需要指定对应的格式： + +```bash +echo -ne '10\n11\n12\n' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT TabSeparated' +``` + +从表中读取内容。由于查询处理是并行的，数据以随机顺序输出。 + +```bash +$ GET 'http://localhost:8123/?query=SELECT a FROM t' +7 +8 +9 +10 +11 +12 +1 +2 +3 +4 +5 +6 +``` + +删除表。 + +```bash +POST 'http://localhost:8123/?query=DROP TABLE t' +``` + +成功请求后并不会返回数据，返回一个空的响应体。 + +可以通过压缩来传输数据。压缩的数据没有一个标准的格式，但你需要指定一个压缩程序来使用它(sudo apt-get install compressor-metrika-yandex）。 + +如果在 URL 中指定了 `compress=1` ，服务会返回压缩的数据。 +如果在 URL 中指定了 `decompress=1` ，服务会解压通过 POST 方法发送的数据。 + +可以通过为每份数据进行立即压缩来减少大规模数据传输中的网络压力。 + +可以指定 'database' 参数来指定默认的数据库。 + +```bash +$ 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`。或者，也可以在表名之前使用一个点来指定数据库。 + +用户名密码可以通过以下两种方式指定： + +1. 通过 HTTP Basic Authentication。示例： + +```bash +echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @- +``` + +2. 通过 URL 参数 中的 'user' 和 'password'。示例： + +```bash +echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @- +``` + +如果用户名没有指定，默认的用户是 `default`。如果密码没有指定，默认会使用空密码。 +可以使用 URL 参数指定配置或者设置整个配置文件来处理单个查询。示例：`http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1` + +更多信息，参见 "[设置](../../operations/settings)" 部分。 + +```bash +$ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @- +0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +``` + +更多关于其他参数的信息，参见 "[设置](../../operations/settings)" 部分。 + +相比起 TCP 原生接口，HTTP 接口不支持会话和会话设置的概念，不允许中止查询（准确地说，只在少数情况下允许），不显示查询处理的进展。执行解析和数据格式化都是在服务端处理，网络上会比 TCP 原生接口更低效。 + +可选的 `query_id` 参数可能当做 query ID 传入（或者任何字符串）。更多信息，参见 "[设置 replace_running_query](../../operations/settings/settings.html#replace-running-query)" 部分。 + +可选的 `quota_key` 参数可能当做 quota key 传入（或者任何字符串）。更多信息，参见 "[配额](../../operations/quotas.html)" 部分。 + +HTTP 接口允许传入额外的数据（外部临时表）来查询。更多信息，参见 "[外部数据查询处理](../../table_engines/external_data.html)" 部分。 + +## 响应缓冲 + +可以在服务器端启用响应缓冲。提供了 `buffer_size` 和 `wait_end_of_query` 两个URL 参数来达此目的。 + +`buffer_size` 决定了查询结果要在服务内存中缓冲多少个字节数据. 如果响应体比这个阈值大，缓冲区会写入到 HTTP 管道，剩下的数据也直接发到 HTTP 管道中。 + +为了确保整个响应体被缓冲，可以设置 `wait_end_of_query=1`。这种情况下，存入内存的数据会被缓冲到服务端的一个临时文件中。 + +示例: + +```bash +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 头被发送到客户端后，若发生查询处理出错，使用缓冲区可以避免这种情况的发生。在这种情况下，响应主体的结尾会写入一条错误消息，而在客户端，只能在解析阶段检测到该错误。 diff --git a/docs/zh/interfaces/index.md b/docs/zh/interfaces/index.md deleted file mode 120000 index 61537763cac..00000000000 --- a/docs/zh/interfaces/index.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/index.md \ No newline at end of file diff --git a/docs/zh/interfaces/index.md b/docs/zh/interfaces/index.md new file mode 100644 index 00000000000..4ff97552792 --- /dev/null +++ b/docs/zh/interfaces/index.md @@ -0,0 +1,7 @@ + + +# 接口 + +为了探索 ClickHouse 的能力，如导入数据到表中，或做一些手动的查询，可以使用 clickhouse-client 命令行程序来完成 + + diff --git a/docs/zh/interfaces/jdbc.md b/docs/zh/interfaces/jdbc.md deleted file mode 120000 index 27dfe0cfa5a..00000000000 --- a/docs/zh/interfaces/jdbc.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/jdbc.md \ No newline at end of file diff --git a/docs/zh/interfaces/jdbc.md b/docs/zh/interfaces/jdbc.md new file mode 100644 index 00000000000..f4c8139ef63 --- /dev/null +++ b/docs/zh/interfaces/jdbc.md @@ -0,0 +1,6 @@ +# JDBC 驱动 + +- ClickHouse官方有 JDBC 的驱动。 见[这里](https://github.com/yandex/clickhouse-jdbc)。 + +- 三方提供的 JDBC 驱动 [ClickHouse-Native-JDBC](https://github.com/housepower/ClickHouse-Native-JDBC). + diff --git a/docs/zh/interfaces/tcp.md b/docs/zh/interfaces/tcp.md deleted file mode 120000 index a0529a856e4..00000000000 --- a/docs/zh/interfaces/tcp.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/tcp.md \ No newline at end of file diff --git a/docs/zh/interfaces/tcp.md b/docs/zh/interfaces/tcp.md new file mode 100644 index 00000000000..1ff4270d690 --- /dev/null +++ b/docs/zh/interfaces/tcp.md @@ -0,0 +1,4 @@ +# 原生接口（TCP） + +TCP 原生接口用于 `clickhouse-client` 命令行，它可以在分布式查询执行中和服务器进行交互，并且可以用在 C++ 程序中。我们讲解只覆盖命令行客户端。 + diff --git a/docs/zh/interfaces/third-party_client_libraries.md b/docs/zh/interfaces/third-party_client_libraries.md deleted file mode 120000 index d483d9e9eba..00000000000 --- a/docs/zh/interfaces/third-party_client_libraries.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/third-party_client_libraries.md \ No newline at end of file diff --git a/docs/zh/interfaces/third-party_client_libraries.md b/docs/zh/interfaces/third-party_client_libraries.md new file mode 100644 index 00000000000..7e9203beb01 --- /dev/null +++ b/docs/zh/interfaces/third-party_client_libraries.md @@ -0,0 +1,47 @@ +# 第三方开发的库 + +以下都是适用于 ClickHouse 的第三方库： + +- Python + - [infi.clickhouse_orm](https://github.com/Infinidat/infi.clickhouse_orm) + - [sqlalchemy-clickhouse](https://github.com/cloudflare/sqlalchemy-clickhouse) + - [clickhouse-driver](https://github.com/mymarilyn/clickhouse-driver) + - [clickhouse-client](https://github.com/yurial/clickhouse-client) +- PHP + - [phpClickHouse](https://github.com/smi2/phpClickHouse) + - [clickhouse-php-client](https://github.com/8bitov/clickhouse-php-client) + - [clickhouse-client](https://github.com/bozerkins/clickhouse-client) + - [PhpClickHouseClient](https://github.com/SevaCode/PhpClickHouseClient) +- Go + - [clickhouse](https://github.com/kshvakov/clickhouse/) + - [go-clickhouse](https://github.com/roistat/go-clickhouse) + - [mailrugo-clickhouse](https://github.com/mailru/go-clickhouse) + - [golang-clickhouse](https://github.com/leprosus/golang-clickhouse) +- NodeJs + - [clickhouse (NodeJs)](https://github.com/TimonKK/clickhouse) + - [node-clickhouse](https://github.com/apla/node-clickhouse) +- Perl + - [perl-DBD-ClickHouse](https://github.com/elcamlost/perl-DBD-ClickHouse) + - [HTTP-ClickHouse](https://metacpan.org/release/HTTP-ClickHouse) + - [AnyEvent-ClickHouse](https://metacpan.org/release/AnyEvent-ClickHouse) +- Ruby + - [clickhouse (Ruby)](https://github.com/archan937/clickhouse) +- R + - [clickhouse-r](https://github.com/hannesmuehleisen/clickhouse-r) + - [RClickhouse](https://github.com/IMSMWU/RClickhouse) +- Scala + - [clickhouse-scala-client](https://github.com/crobox/clickhouse-scala-client) +- .NET + - [ClickHouse.Ado](https://github.com/killwort/ClickHouse-Net) + - [ClickHouse.Net](https://github.com/ilyabreev/ClickHouse.Net) + - [ClickHouse.Net.Migrations](https://github.com/ilyabreev/ClickHouse.Net.Migrations) +- C++ + - [clickhouse-cpp](https://github.com/artpaul/clickhouse-cpp/) +- Elixir + - [clickhousex](https://github.com/appodeal/clickhousex/) + - [clickhouse_ecto](https://github.com/appodeal/clickhouse_ecto) +- Java + - [clickhouse-client-java](https://github.com/VirtusAI/clickhouse-client-java) +- Nim + - [nim-clickhouse](https://github.com/leonardoce/nim-clickhouse) + diff --git a/docs/zh/interfaces/third-party_gui.md b/docs/zh/interfaces/third-party_gui.md deleted file mode 120000 index c100abd8782..00000000000 --- a/docs/zh/interfaces/third-party_gui.md +++ /dev/null @@ -1 +0,0 @@ -../../en/interfaces/third-party_gui.md \ No newline at end of file diff --git a/docs/zh/interfaces/third-party_gui.md b/docs/zh/interfaces/third-party_gui.md new file mode 100644 index 00000000000..db2a0f58243 --- /dev/null +++ b/docs/zh/interfaces/third-party_gui.md @@ -0,0 +1,39 @@ +# 第三方开发的可视化界面 + +## Tabix + +ClickHouse Web 界面 [Tabix](https://github.com/tabixio/tabix). + +主要功能： + +- 浏览器直接连接 ClickHouse，不需要安装其他软件。 +- 高亮语法的编辑器。 +- 自动命令补全。 +- 查询命令执行的图形分析工具。 +- 配色方案选项。 + +[Tabix 文档](https://tabix.io/doc/). + + +## HouseOps + +[HouseOps](https://github.com/HouseOps/HouseOps) 是一个交互式 UI/IDE 工具，可以运行在 OSX, Linux and Windows 平台中。 + +主要功能： + +- 查询高亮语法提示，可以以表格或 JSON 格式查看数据。 +- 支持导出 CSV 或 JSON 格式数据。 +- 支持查看查询执行的详情，支持 KILL 查询。 +- 图形化显示，支持显示数据库中所有的表和列的详细信息。 +- 快速查看列占用的空间。 +- 服务配置。 + +The following features are planned for development: +以下功能正在计划开发： +- 数据库管理 +- 用户管理 +- 实时数据分析 +- 集群监控 +- 集群管理 +- 监控副本情况以及 Kafka 引擎表 +