跳至主要内容

命令行客户端

clickhouse-client​

ClickHouse 提供了一个原生的命令行客户端：clickhouse-client。该客户端支持命令行选项和配置文件。有关更多信息，请参阅配置。

从 clickhouse-client 包中安装它，并使用命令 clickhouse-client 运行它。

$ clickhouse-client
ClickHouse client version 20.13.1.5273 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 20.13.1.

:)

不同的客户端和服务器版本是兼容的，但某些功能可能在较旧的客户端中不可用。我们建议使用与服务器应用程序相同版本的客户端。当您尝试使用旧版本的客户端时，服务器 clickhouse-client 会显示消息

ClickHouse client version is older than ClickHouse server.
It may lack support for new features.

用法​

该客户端可以在交互式和非交互式（批处理）模式下使用。

收集您的连接详细信息​

要使用原生 TCP 连接到 ClickHouse，您需要以下信息

  • 主机和端口：通常，使用 TLS 时端口为 9440，不使用 TLS 时端口为 9000。

  • 数据库名称：默认情况下有一个名为 default 的数据库，请使用您要连接到的数据库的名称。

  • 用户名和密码：默认情况下用户名为 default。请使用适合您用例的用户名。

您的 ClickHouse Cloud 服务的详细信息可在 ClickHouse Cloud 控制台中找到。选择您要连接的服务，然后点击**连接**。

ClickHouse Cloud service connect button

选择**原生**，详细信息可在 clickhouse-client 命令示例中找到。

ClickHouse Cloud Native TCP connection details

如果您使用的是自托管 ClickHouse，则连接详细信息由您的 ClickHouse 管理员设置。

交互式​

要交互式连接到您的 ClickHouse Cloud 服务或任何使用 TLS 和密码的 ClickHouse 服务器，请使用 --secure、端口 9440 并提供您的用户名和密码。

clickhouse-client --host <HOSTNAME> \
                  --secure \
                  --port 9440 \
                  --user <USERNAME> \
                  --password <PASSWORD>

要连接到自托管 ClickHouse 服务器，您将需要该服务器的详细信息。无论是否使用 TLS、端口号和密码都是可配置的。请使用上面 ClickHouse Cloud 的示例作为起点。

批处理​

要使用批处理模式，请指定“query”参数，或将数据发送到“stdin”（它会验证“stdin”不是终端），或两者兼而有之。与 HTTP 接口类似，当使用“query”参数并将数据发送到“stdin”时，请求是“query”参数、换行符和“stdin”中的数据的串联。这对于大型 INSERT 查询非常方便。

使用客户端插入数据的示例

将 CSV 文件插入到远程 ClickHouse 服务​

此示例适用于 ClickHouse Cloud 或任何使用 TLS 和密码的 ClickHouse 服务器。在此示例中，一个示例数据集 CSV 文件 cell_towers.csv 被插入到 default 数据库中现有的表 cell_towers 中。

clickhouse-client --host HOSTNAME.clickhouse.cloud \
  --secure \
  --port 9440 \
  --user default \
  --password PASSWORD \
  --query "INSERT INTO cell_towers FORMAT CSVWithNames" \
  < cell_towers.csv
注意

为了专注于查询语法，其余示例省略了连接详细信息（--host、--port 等）。在尝试这些命令时请添加它们。

三种不同的插入数据的方法​

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 子句中设置格式。

默认情况下，您只能在批处理模式下处理单个查询。要从“脚本”中执行多个查询，请使用 --multiquery 参数。这适用于除 INSERT 之外的所有查询。查询结果会连续输出，没有任何额外的分隔符。同样，要处理大量查询，您可以为每个查询运行“clickhouse-client”。请注意，启动“clickhouse-client”程序可能需要花费数十毫秒。

在交互模式下，您将获得一个命令行，您可以在其中输入查询。

如果未指定“multiline”（默认值）：要运行查询，请按 Enter 键。查询末尾不需要分号。要输入多行查询，在换行符前输入反斜杠 \。按下 Enter 键后，系统会提示您输入查询的下一行。

如果指定了 multiline：要运行查询，请以分号结尾并按 Enter 键。如果在输入行的末尾省略了分号，系统会提示您输入查询的下一行。

只会运行单个查询，因此分号之后的所有内容都会被忽略。

您可以指定 \G 来代替或跟在分号之后。这表示垂直格式。在此格式中，每个值都打印在单独的行上，这对于宽表很方便。此不寻常的功能是为了与 MySQL CLI 兼容而添加的。

命令行基于“replxx”（类似于“readline”)。换句话说，它使用熟悉的键盘快捷键并保留历史记录。历史记录写入 ~/.clickhouse-client-history。

默认情况下，使用的格式为 PrettyCompact。您可以在查询的 FORMAT 子句中更改格式，或在查询末尾指定 \G，或在命令行中使用 --format 或 --vertical 参数，或使用客户端配置文件。

要退出客户端，请按 Ctrl+D，或输入以下内容之一代替查询：“exit”、“quit”、“logout”、“exit;”、“quit;”、“logout;”、“q”、“Q”、“:q”。

处理查询时，客户端会显示

  1. 进度，每秒更新不超过 10 次（默认值）。对于快速查询，进度可能没有时间显示。
  2. 解析后的格式化查询，用于调试。
  3. 结果以指定的格式显示。
  4. 结果中的行数、经过的时间以及查询处理的平均速度。所有数据量均指未压缩数据。

您可以通过按 Ctrl+C 取消长时间运行的查询。但是，您仍然需要等待一段时间才能让服务器中止请求。在某些阶段无法取消查询。如果您没有等待并再次按下 Ctrl+C，客户端将退出。

命令行客户端允许传递外部数据（外部临时表）以进行查询。有关更多信息，请参阅“查询处理的外部数据”部分。

带参数的查询​

您可以创建带参数的查询，并将值从客户端应用程序传递给它们。这样可以避免在客户端对查询进行格式化以包含特定的动态值。例如

$ clickhouse-client --param_parName="[1, 2]"  -q "SELECT * FROM table WHERE a = {parName:Array(UInt16)}"

也可以在交互式会话中设置参数

$ clickhouse-client -nq "
  SET param_parName='[1, 2]';
  SELECT {parName:Array(UInt16)}"

查询语法​

像往常一样格式化查询，然后将您希望从应用程序参数传递到查询的值放在以下格式的花括号中

{<name>:<data type>}
  • name — 占位符标识符。在控制台客户端中，它应在应用程序参数中使用以下格式：--param_<name> = value。

  • 数据类型 — 应用参数值的数据类型。例如，像 (integer, ('string', integer)) 这样的数据结构可以具有 Tuple(UInt8, Tuple(String, UInt8)) 数据类型（您也可以使用其他整数类型）。也可以将表、数据库、列名称作为参数传递，在这种情况下，您需要使用 Identifier 作为数据类型。

示例​

$ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" -q "SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}"
$ clickhouse-client --param_tbl="numbers" --param_db="system" --param_col="number" --param_alias="top_ten" --query "SELECT {col:Identifier} as {alias:Identifier} FROM {db:Identifier}.{tbl:Identifier} LIMIT 10"

配置​

您可以使用以下方法将参数传递给 clickhouse-client（所有参数都有默认值）

  • 从命令行

    命令行选项会覆盖配置文件中的默认值和设置。

  • 配置文件。

    配置文件中的设置会覆盖默认值。

命令行选项​

  • --host, -h – 服务器名称，默认为 ‘localhost’。您可以使用名称或 IPv4 或 IPv6 地址。
  • --port – 要连接的端口。默认值：9000。请注意，HTTP 接口和本机接口使用不同的端口。
  • --user, -u – 用户名。默认值：default。
  • --password – 密码。默认值：空字符串。
  • --ask-password - 提示用户输入密码。
  • --query, -q – 使用非交互模式时要处理的查询。--query 可以多次指定，例如 --query "SELECT 1" --query "SELECT 2"。不能与 --queries-file 同时使用。
  • --queries-file – 包含要执行的查询的文件路径。--queries-file 可以多次指定，例如 --queries-file queries1.sql --queries-file queries2.sql。不能与 --query 同时使用。
  • --multiquery, -n – 如果指定，则可以在 --query 选项后列出多个用分号分隔的查询。为了方便起见，也可以省略 --query 并直接在 --multiquery 后传递查询。
  • --multiline, -m – 如果指定，则允许多行查询（不要在 Enter 键上发送查询）。
  • --database, -d – 选择当前默认数据库。默认值：服务器设置中的当前数据库（默认为 ‘default’）。
  • --format, -f – 使用指定的默认格式输出结果。
  • --vertical, -E – 如果指定，则默认使用垂直格式输出结果。这与 –format=Vertical 相同。在此格式中，每个值都打印在一行上，这在显示宽表时很有帮助。
  • --time, -t – 如果指定，则在非交互模式下将查询执行时间打印到 ‘stderr’。
  • --memory-usage – 如果指定，则在非交互模式下将内存使用情况打印到 ‘stderr’。可能的值：'none' - 不打印内存使用情况，'default' - 打印字节数，'readable' - 以人类可读的格式打印内存使用情况。
  • --stacktrace – 如果指定，则如果发生异常，也会打印堆栈跟踪。
  • --config-file – 配置文件的名称。
  • --secure – 如果指定，将通过安全连接 (TLS) 连接到服务器。您可能需要在配置文件中配置您的 CA 证书。可用的配置设置与服务器端 TLS 配置相同。
  • --history_file — 包含命令历史记录的文件路径。
  • --param_<name> — 带参数的查询的值。
  • --hardware-utilization — 在进度条中打印硬件利用率信息。
  • --print-profile-events – 打印 ProfileEvents 数据包。
  • --profile-events-delay-ms – 打印 ProfileEvents 数据包之间的延迟（-1 - 仅打印总数，0 - 打印每个数据包）。
  • --jwt – 如果指定，则启用通过 JSON Web Token 进行授权。服务器 JWT 授权仅在 ClickHouse Cloud 中可用。
  • --progress – 打印查询执行进度。可能的值：'tty|on|1|true|yes' - 在交互模式下输出到 TTY；'err' - 在非交互模式下输出到 STDERR；'off|0|false|no' - 禁用进度打印。默认值：在交互模式下为 TTY，在非交互模式下禁用。
  • --progress-table – 在查询执行期间打印一个带有变化指标的进度表。可能的值：'tty|on|1|true|yes' - 在交互模式下输出到 TTY；'err' - 在非交互模式下输出到 STDERR；'off|0|false|no' - 禁用进度表。默认值：在交互模式下为 TTY，在非交互模式下禁用。
  • --enable-progress-table-toggle – 通过按控制键（空格键）启用切换进度表。仅适用于启用进度表打印的交互模式。默认值：'true'。

除了 --host、--port、--user 和 --password 选项外，ClickHouse 客户端还支持连接字符串（请参阅下一节）。

别名​

  • \l - SHOW DATABASES
  • \d - SHOW TABLES
  • \c <DATABASE> - USE DATABASE
  • . - 重复上一个查询

快捷键​

  • Alt (Option) + Shift + e - 使用当前查询打开编辑器。可以设置环境变量 - EDITOR，默认使用 vim。
  • Alt (Option) + # - 注释行。
  • Ctrl + r - 模糊历史搜索。
提示

配置 MacOS 上元键 (Option) 的正确工作方式

iTerm2：转到 Preferences -> Profile -> Keys -> Left Option key 并单击 Esc+

所有可用快捷键的完整列表 - replxx。

连接字符串​

clickhouse-client 还可以支持使用类似于MongoDB、PostgreSQL、MySQL的连接字符串连接到 ClickHouse 服务器。它具有以下语法

clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters]

其中

  • user - （可选）是用户名，
  • password - （可选）是用户密码。如果指定了 : 且密码为空，则客户端将提示用户输入密码。
  • hosts_and_ports - （可选）是主机和可选端口的列表 host[:port] [, host:[port]], ...，
  • database - （可选）是数据库名称，
  • query_parameters - （可选）是键值对列表 param1=value1[,&param2=value2], ...。对于某些参数，不需要值。参数名称和值区分大小写。

如果未指定用户，则将使用无密码的 default 用户。如果未指定主机，则将使用 localhost（localhost）。如果未指定端口，则将使用 9000 作为端口。如果未指定数据库，则将使用 default 数据库。

如果在连接字符串中指定了用户名、密码或数据库，则不能使用 --user、--password 或 --database 指定（反之亦然）。

主机组件可以是主机名和 IP 地址。将 IPv6 地址放在方括号中以指定它

clickhouse://[2001:db8::1234]

URI 允许连接到多个主机。连接字符串可以包含多个主机。ClickHouse-client 将尝试按顺序（即从左到右）连接到这些主机。建立连接后，不会尝试连接到其余主机。

连接字符串必须指定为 clickhouse-client 的第一个参数。连接字符串可以与任意其他命令行选项组合，除了 --host/-h 和 --port。

以下键允许用于组件 query_parameter

  • secure 或简写 s - 无值。如果指定，客户端将通过安全连接 (TLS) 连接到服务器。请参阅命令行选项中的 secure

百分比编码​

user、password、hosts、database 和 query parameters 中的非 US ASCII、空格和特殊字符必须进行百分比编码。

示例​

使用端口 9000 连接到 localhost 并执行查询 SELECT 1。

clickhouse-client clickhouse://127.0.0.1:9000 --query "SELECT 1"

使用用户名 john 和密码 secret、主机 127.0.0.1 和端口 9000 连接到 localhost

clickhouse-client clickhouse://john:[email protected]:9000

使用默认用户、主机 IPV6 地址 [::1] 和端口 9000 连接到 localhost。

clickhouse-client clickhouse://[::1]:9000

使用端口 9000 以多行模式连接到 localhost。

clickhouse-client clickhouse://127.0.0.1:9000 '-m'

使用用户 default 使用端口 9000 连接到 localhost。

clickhouse-client clickhouse://default@localhost:9000

# equivalent to:
clickhouse-client clickhouse://127.0.0.1:9000 --user default

使用端口 9000 连接到 localhost 的 my_database 数据库。

clickhouse-client clickhouse://127.0.0.1:9000/my_database

# equivalent to:
clickhouse-client clickhouse://127.0.0.1:9000 --database my_database

使用端口 9000 连接到 localhost 的 my_database 数据库（在连接字符串中指定）并使用简写 's' URI 参数建立安全连接。

clickhouse-client clickhouse://127.0.0.1/my_database?s

# equivalent to:
clickhouse-client clickhouse://127.0.0.1/my_database -s

连接到默认主机，使用默认端口、默认用户和默认数据库。

clickhouse-client clickhouse:

连接到默认主机，使用默认端口，使用用户 my_user 且无密码。

clickhouse-client clickhouse://my_user@

# Using a blank password between : and @ means to asking user to enter the password before starting the connection.
clickhouse-client clickhouse://my_user:@

使用电子邮件作为用户名连接到 localhost。@ 符号被百分比编码为 %40。

clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000

连接到提供的其中一个主机：192.168.1.15、192.168.1.25。

clickhouse-client clickhouse://192.168.1.15,192.168.1.25

配置文件​

clickhouse-client 使用以下第一个存在的文件

  • 在 --config-file 参数中定义。
  • ./clickhouse-client.xml、.yaml、.yml
  • ~/.clickhouse-client/config.xml、.yaml、.yml
  • /etc/clickhouse-client/config.xml、.yaml、.yml

配置文件示例

<config>
    <user>username</user>
    <password>password</password>
    <secure>true</secure>
    <openSSL>
      <client>
        <caConfig>/etc/ssl/cert.pem</caConfig>
      </client>
    </openSSL>
</config>

或 YAML 格式的相同配置

user: username
password: 'password'
secure: true
openSSL:
  client:
    caConfig: '/etc/ssl/cert.pem'

查询 ID 格式​

在交互模式下，clickhouse-client 会为每个查询显示查询 ID。默认情况下，ID 格式如下所示

Query id: 927f137d-00f1-4175-8914-0dd066365e96

可以在配置文件中的 query_id_formats 标签内指定自定义格式。格式字符串中的 {query_id} 占位符将替换为查询的 ID。标签内允许使用多个格式字符串。此功能可用于生成 URL 以便于查询分析。

示例

<config>
  <query_id_formats>
    <speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
  </query_id_formats>
</config>

如果应用上述配置，则查询 ID 将以以下格式显示

speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d