跳至主要内容

clickhouse-client

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。
  • data type — 数据类型 的应用程序参数值。例如，(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：转到首选项 -> 配置文件 -> 键 -> 左选项键并单击 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'

使用端口 9000 和用户 default 连接到 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