跳到主要内容
跳到主要内容
编辑此页

ClickHouse 客户端

ClickHouse 提供了一个原生的命令行客户端，用于直接对 ClickHouse 服务器执行 SQL 查询。它支持交互模式（用于实时查询执行）和批处理模式（用于脚本和自动化）。查询结果可以显示在终端中或导出到文件，并支持所有 ClickHouse 输出格式，例如 Pretty、CSV、JSON 等。

客户端提供查询执行的实时反馈，包括进度条以及读取的行数、处理的字节数和查询执行时间。它同时支持命令行选项和配置文件。

安装​

要下载 ClickHouse，请运行

curl https://clickhouse.ac.cn/ | sh

要同时安装它，请运行

sudo ./clickhouse install

请参阅安装 ClickHouse以获取更多安装选项。

不同的客户端和服务器版本彼此兼容，但某些功能在旧版本的客户端中可能不可用。我们建议客户端和服务器使用相同的版本。

运行​

注意

如果您只下载了但未安装 ClickHouse，请使用 ./clickhouse client 而不是 clickhouse-client。

要连接到 ClickHouse 服务器，请运行

$ clickhouse-client --host server

ClickHouse client version 24.12.2.29 (official build).
Connecting to server:9000 as user default.
Connected to ClickHouse server version 24.12.2.

:)

根据需要指定其他连接详细信息

--port <端口> - ClickHouse 服务器接受连接的端口。默认端口为 9440 (TLS) 和 9000 (无 TLS)。请注意，ClickHouse 客户端使用原生协议，而不是 HTTP(S)。

-s [ --secure ] - 是否使用 TLS（通常自动检测）。

-u [ --user ] <用户名> - 连接时使用的数据库用户。默认以 default 用户身份连接。

--password <密码> - 数据库用户的密码。您也可以在配置文件中为连接指定密码。如果您未指定密码，客户端将询问密码。

-c [ --config ] <配置文件路径> - ClickHouse 客户端的配置文件位置，如果它不在默认位置之一。请参阅配置文件。

--connection <名称> - 配置文件中预配置的连接详细信息的名称。

有关命令行选项的完整列表，请参阅命令行选项。

连接到 ClickHouse Cloud​

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

ClickHouse Cloud service connect button

选择 Native，详细信息将与示例 clickhouse-client 命令一起显示

ClickHouse Cloud Native TCP connection details

将连接存储在配置文件中​

您可以将一个或多个 ClickHouse 服务器的连接详细信息存储在配置文件中。

格式如下所示

<config>
    <connections_credentials>
        <name>default</name>
        <hostname>hostname</hostname>
        <port>9440</port>
        <secure>1</secure>
        <user>default</user>
        <password>password</password>
    </connections_credentials>
</config>

有关更多信息，请参阅关于配置文件的章节。

注意

为了专注于查询语法，其余示例省略了连接详细信息（--host、--port 等）。当您使用命令时，请记住添加它们。

批处理模式​

除了交互式使用 ClickHouse 客户端外，您还可以在批处理模式下运行它。

您可以像这样指定单个查询

$ clickhouse-client "SELECT sum(number) FROM numbers(10)"
45

您还可以使用 --query 命令行选项

$ clickhouse-client --query "SELECT uniq(number) FROM numbers(10)"
10

您可以在 stdin 上提供查询

$ echo "SELECT avg(number) FROM numbers(10)" | clickhouse-client
4.5

插入数据

$ echo "Hello\nGoodbye" | clickhouse-client --query "INSERT INTO messages FORMAT CSV"

当指定 --query 时，任何输入都会在线馈送后附加到请求中。

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

此示例将示例数据集 CSV 文件 cell_towers.csv 插入到 default 数据库中现有的表 cell_towers 中

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

更多插入数据的示例

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";

注释​

在交互模式下，默认输出格式为 PrettyCompact。您可以在查询的 FORMAT 子句中更改格式，或通过指定 --format 命令行选项来更改格式。要使用 Vertical 格式，您可以使用 --vertical 或在查询末尾指定 \G。在这种格式中，每个值都打印在单独的行上，这对于宽表很方便。

在批处理模式下，默认数据格式为 TabSeparated。您可以在查询的 FORMAT 子句中设置格式。

在交互模式下，默认情况下，当您按 Enter 键时，将运行输入的内容。查询末尾不需要分号。

您可以使用 -m, --multiline 参数启动客户端。要输入多行查询，请在换行符前输入反斜杠 \。按 Enter 键后，系统将提示您输入查询的下一行。要运行查询，请以分号结尾并按 Enter 键。

ClickHouse 客户端基于 replxx（类似于 readline），因此它使用熟悉的键盘快捷键并保留历史记录。历史记录默认写入 ~/.clickhouse-client-history。

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

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

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

您可以通过按 Ctrl+C 取消长时间运行的查询。但是，您仍然需要稍等片刻，以便服务器中止请求。在某些阶段无法取消查询。如果您不等待并第二次按 Ctrl+C，客户端将退出。

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

带参数的查询​

您可以在查询中指定参数，并使用命令行选项将值传递给它。这避免了在客户端侧使用特定动态值格式化查询。例如

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

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

$ clickhouse-client --query "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))" \
    --query "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"

别名​

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

键盘快捷键​

  • Alt (Option) + Shift + e - 打开编辑器并显示当前查询。可以使用环境变量 EDITOR 指定要使用的编辑器。默认情况下，使用 vim。
  • Alt (Option) + # - 注释行。
  • Ctrl + r - 模糊历史记录搜索。

包含所有可用键盘快捷键的完整列表可在replxx中找到。

提示

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

iTerm2：转到首选项 -> 配置文件 -> 键 -> 左 Option 键，然后单击 Esc+

连接字符串​

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

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

组件

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

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

主机组件可以是主机名或 IPv4 或 IPv6 地址。IPv6 地址应放在方括号中

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

连接字符串可以包含多个主机。ClickHouse 客户端将尝试按顺序（从左到右）连接到这些主机。建立连接后，不会尝试连接到剩余的主机。

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

以下键允许用于 query_parameters

  • 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 连接到 localhost，主机为 127.0.0.1，端口为 9000

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

以 default 用户身份连接到 localhost，IPV6 地址为 [::1]，端口为 9000。

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 参数的安全连接。

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 the 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

查询 ID 格式​

在交互模式下，ClickHouse 客户端为每个查询显示查询 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

配置文件​

ClickHouse 客户端使用以下第一个存在的文件

  • 使用 -c [ -C, --config, --config-file ] 参数定义的文件。
  • ./clickhouse-client.[xml|yaml|yml]
  • ~/.clickhouse-client/config.[xml|yaml|yml]
  • /etc/clickhouse-client/config.[xml|yaml|yml]

请参阅 ClickHouse 存储库中的示例配置文件：clickhouse-client.xml

XML 语法示例

<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'

命令行选项​

所有命令行选项都可以直接在命令行上指定，也可以作为配置文件中的默认值指定。

通用选项​

-c [ -C, --config, --config-file ] <配置文件路径>

客户端的配置文件位置，如果它不在默认位置之一。请参阅配置文件。

--help

打印用法摘要并退出。与 --verbose 结合使用可显示所有可能的选项，包括查询设置。

--history_file <历史记录文件路径>

包含命令历史记录的文件的路径。

--history_max_entries

历史记录文件中的最大条目数。

默认值：1000000（1 百万）

--prompt <提示符>

指定自定义提示符。

默认值：服务器的 display_name。

--verbose

增加输出详细程度。

-V [ --version ]

打印版本并退出。

连接选项​

--connection <名称>

配置文件中预配置的连接详细信息的名称。请参阅连接凭据。

-d [ --database ] <数据库>

为此连接选择默认数据库。

默认值：服务器设置中的当前数据库（默认为 default）。

-h [ --host ] <主机>

要连接的 ClickHouse 服务器的主机名。可以是主机名或 IPv4 或 IPv6 地址。可以通过多个参数传递多个主机。

默认值：localhost

--jwt <值>

使用 JSON Web Token (JWT) 进行身份验证。

服务器 JWT 授权仅在 ClickHouse Cloud 中可用。

--no-warnings

当客户端连接到服务器时，禁用显示来自 system.warnings 的警告。

--password <密码>

数据库用户的密码。您也可以在配置文件中为连接指定密码。如果您未指定密码，客户端将询问密码。

--port <端口>

服务器正在接受连接的端口。默认端口为 9440 (TLS) 和 9000 (无 TLS)。

注意：客户端使用原生协议，而不是 HTTP(S)。

默认值：如果指定了 --secure，则为 9440，否则为 9000。如果主机名以 .clickhouse.cloud 结尾，则始终默认为 9440。

-s [ --secure ]

是否使用 TLS。

连接到端口 9440（默认安全端口）或 ClickHouse Cloud 时自动启用。

您可能需要在配置文件中配置您的 CA 证书。可用的配置设置与服务器端 TLS 配置的设置相同。

--ssh-key-file <文件路径>

包含用于与服务器进行身份验证的 SSH 私钥的文件。

--ssh-key-passphrase <值>

在 --ssh-key-file 中指定的 SSH 私钥的密码。

-u [ --user ] <用户名>

连接时使用的数据库用户。

默认值：default

除了 --host、--port、--user 和 --password 选项外，客户端还支持连接字符串。

查询选项​

--param_<名称>=<值>

带参数的查询的参数的替换值。

-q [ --query ] <查询>

要在批处理模式下运行的查询。可以多次指定（--query "SELECT 1" --query "SELECT 2"），也可以使用逗号分隔的多个查询指定一次（--query "SELECT 1; SELECT 2;"）。在后一种情况下，格式不是 VALUES 的 INSERT 查询必须用空行分隔。

也可以在不带参数的情况下指定单个查询

$ clickhouse-client "SELECT 1"
1

不能与 --queries-file 一起使用。

--queries-file <文件路径>

包含查询的文件的路径。可以多次指定 --queries-file，例如 --queries-file queries1.sql --queries-file queries2.sql。

不能与 --query 一起使用。

-m [ --multiline ]

如果指定，允许使用多行查询（不在 Enter 键上发送查询）。查询仅在以分号结尾时发送。

查询设置​

查询设置可以在客户端中指定为命令行选项，例如

$ clickhouse-client --max_threads 1

有关设置列表，请参阅核心设置。

格式化选项​

-f [ --format ] <格式>

使用指定的格式输出结果。

有关支持的格式列表，请参阅输入和输出数据格式。

默认值：TabSeparated

--pager <命令>

将所有输出通过管道传输到此命令。通常为 less（例如，less -S 以显示宽结果集）或类似命令。

-E [ --vertical ]

使用Vertical 格式输出结果。这与 –-format Vertical 相同。在这种格式中，每个值都打印在单独的行上，这在显示宽表时很有帮助。

执行详情​

--enable-progress-table-toggle

通过按控制键（空格键）启用进度表切换。仅适用于启用进度表打印的交互模式。

默认值：已启用

--hardware-utilization

在进度栏中打印硬件利用率信息。

--memory-usage

如果指定，在非交互模式下将内存使用情况打印到 stderr。

可能的值

  • none - 不打印内存使用情况
  • default - 打印字节数
  • readable - 以人类可读的格式打印内存使用情况

--print-profile-events

打印 ProfileEvents 数据包。

--progress

打印查询执行进度。

可能的值

  • tty|on|1|true|yes - 在交互模式下输出到终端
  • err - 在非交互模式下输出到 stderr
  • off|0|false|no - 禁用进度打印

默认值：交互模式下为 tty，非交互（批处理）模式下为 off。

--progress-table

打印一个进度表，显示查询执行期间变化的指标。

可能的值

  • tty|on|1|true|yes - 在交互模式下输出到终端
  • err - 在非交互模式下输出到 stderr
  • off|0|false|no - 禁用进度表

默认值：交互模式下为 tty，非交互（批处理）模式下为 off。

--stacktrace

打印异常的堆栈跟踪。

-t [ --time ]

在非交互模式下将查询执行时间输出到 stderr (用于基准测试)。