ClickHouse 客户端

ClickHouse 命令行客户端的文档

ClickHouse 提供原生命令行客户端，可直接向 ClickHouse 服务器执行 SQL 查询。 它同时支持交互模式 (用于实时执行查询) 和批次模式 (用于脚本编写和自动化) 。 查询结果既可显示在终端中，也可导出到文件，并支持所有 ClickHouse 输出格式，例如 Pretty、CSV、JSON 等。

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

​

安装

下载 ClickHouse，请运行：

curl https://clickhouse.com/ | sh

如需一并安装，请运行：

sudo ./clickhouse install

更多安装选项，请参见安装 ClickHouse。

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

​

运行

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

要连接到 ClickHouse server，请运行：

$ 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 <port>	ClickHouse server 接受连接的端口。默认端口为 9440 (TLS) 和 9000 (不使用 TLS) 。请注意，ClickHouse 客户端 使用的是 native protocol，而不是 HTTP(S)。
-s [ --secure ]	是否使用 TLS (通常会自动检测) 。
-u [ --user ] <username>	用于连接的数据库用户。默认以 default 用户连接。
--password <password>	数据库用户的密码。你也可以在配置文件中为连接指定密码。如果未指定密码，客户端会提示你输入。
-c [ --config ] <path-to-file>	ClickHouse 客户端 配置文件的位置 (如果该文件不在默认位置之一) 。请参见配置文件。
--connection <name>	配置文件中预先配置的连接信息名称。

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

​

连接到 ClickHouse Cloud

你可以在 ClickHouse Cloud 控制台中查看 ClickHouse Cloud 服务的详细信息。选择要连接的服务，然后点击 Connect：

选择 Native，即可看到详细信息以及一个 clickhouse-client 命令示例：

​

在配置文件中存储连接信息

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

格式如下：

<config>
    <connections_credentials>
        <connection>
            <name>default</name>
            <hostname>hostname</hostname>
            <port>9440</port>
            <secure>1</secure>
            <user>default</user>
            <password>password</password>
            <!-- <history_file></history_file> -->
            <!-- <history_max_entries></history_max_entries> -->
            <!-- <accept-invalid-certificate>false</accept-invalid-certificate> -->
            <!-- <prompt></prompt> -->
        </connection>
    </connections_credentials>
</config>

更多信息，请参阅配置文件一节。

为了突出查询语法，其余示例省略了连接信息 (--host、--port 等) 。使用这些命令时，请记得补上。

​

交互模式

​

使用 交互模式

要以 交互模式 运行 ClickHouse，只需执行：

clickhouse-client

这会打开读取-求值-输出循环 (REPL) ，你可以开始以交互方式输入 SQL 查询。 连接成功后，会出现一个提示符，你可以在其中输入查询：

ClickHouse client version 25.x.x.x
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 25.x.x.x

hostname :)

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

在交互模式下，默认情况下，按下 Enter 时会执行你输入的内容。 查询末尾无需分号。

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

ClickHouse 客户端 基于 replxx (类似于 readline) ，因此支持常见的键盘快捷键并保留历史记录。 默认情况下，历史记录会写入 ~/.clickhouse-client-history。

要退出客户端，请按 Ctrl+D，或者输入以下任一内容来代替查询：

• exit 或 exit;
• quit 或 quit;
• q、Q 或 :q
• logout 或 logout;

​

查询处理信息

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

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

你可以按 Ctrl+C 取消长时间运行的查询。 不过，你仍需要稍等片刻，让服务器中止该请求。 在某些阶段，查询无法取消。 如果不等待而再次按下 Ctrl+C，客户端将退出。

ClickHouse 客户端 允许在查询时传递外部数据 (外部临时表) 。 更多信息，请参见 查询处理的外部数据 一节。

​

别名

你可以在 REPL 中使用以下别名：

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

​

键盘快捷键

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

所有可用键盘快捷键的完整列表请参见 replxx。

要在 MacOS 上正确配置 Meta 键 (Option) ：

iTerm2：依次进入 Preferences -> Profile -> Keys -> Left Option key，然后点击 Esc+

​

批次模式

​

使用批次模式

你可以不以交互方式使用 ClickHouse 客户端，而是让它以批次模式运行。 在批次模式下，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

假设存在一个 messages 表，你也可以通过命令行插入数据：

$ 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

​

从命令行插入数据示例

可以通过多种方式从命令行插入数据。 下面的示例使用批次模式将两行 CSV 数据插入 ClickHouse 表中：

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 会开启一个 heredoc，它会持续读取内容，直到再次遇到 _EOF，然后将其输出：

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 的内容输出到 stdout，并通过管道传递给 clickhouse-client 作为输入：

cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

在批次模式下，默认的数据格式为 TabSeparated。 如上例所示，你可以在查询的 FORMAT 子句中设置格式。

​

带参数的查询

你可以在查询中指定参数，并通过命令行选项为其传入值。 这样可以避免在客户端使用特定的动态值来格式化查询。 例如：

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

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

$ clickhouse-client
ClickHouse client version 25.X.X.XXX (official build).

:) SET param_parName='[1, 2]';

SET param_parName = '[1, 2]'

Query id: 7ac1f84e-e89a-4eeb-a4bb-d24b8f9fd977

Ok.

0 rows in set. Elapsed: 0.000 sec.

:) SELECT {parName:Array(UInt16)}

SELECT {parName:Array(UInt16)}

Query id: 0358a729-7bbe-4191-bb48-29b063c548a7

   ┌─_CAST([1, 2]⋯y(UInt16)')─┐
1. │ [1,2]                    │
   └──────────────────────────┘

1 row in set. Elapsed: 0.006 sec.

​

查询语法

在查询中，将要通过命令行参数填入的值用花括号括起来，格式如下：

{<name>:<data type>}

参数	描述
name	占位符标识符。对应的命令行选项为 --param_<name> = value。
data type	参数的数据类型。 例如，(integer, ('string', integer)) 这样的数据结构可以使用 Tuple(UInt8, Tuple(String, UInt8)) 数据类型 (也可以使用其他整数类型) 。 表名、database 名和列名也可以作为参数传递；在这种情况下，需要使用 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"

​

AI SQL 生成

ClickHouse Client 内置了 AI 辅助功能，可根据自然语言描述生成 SQL 查询。该功能可帮助用户在无需深入了解 SQL 的情况下编写复杂查询。

如果已设置 OPENAI_API_KEY 或 ANTHROPIC_API_KEY 环境变量，AI 辅助功能即可开箱即用。有关更高级的配置，请参阅配置部分。

​

用法

如需使用 AI SQL 生成功能，请在自然语言查询前加上 ??：

:) ?? show all users who made purchases in the last 30 days

AI 将：

1. 自动探索你的数据库 schema
2. 根据发现的表和列生成合适的 SQL
3. 立即执行生成的查询

​

示例

:) ?? count orders by product category

正在启动 AI SQL 生成，并进行 schema 发现...
──────────────────────────────────────────────────

🔍 list_databases
   ➜ system, default, sales_db

🔍 list_tables_in_database
   database: sales_db
   ➜ orders, products, categories

🔍 get_schema_for_table
   database: sales_db
   table: orders
   ➜ CREATE TABLE orders (order_id UInt64, product_id UInt64, quantity UInt32, ...)

✨ SQL 查询生成成功！
──────────────────────────────────────────────────

SELECT
    c.name AS category,
    COUNT(DISTINCT o.order_id) AS order_count
FROM sales_db.orders o
JOIN sales_db.products p ON o.product_id = p.product_id
JOIN sales_db.categories c ON p.category_id = c.category_id
GROUP BY c.name
ORDER BY order_count DESC

​

配置

要使用 AI SQL 生成功能，您需要在 ClickHouse 客户端 的配置文件中配置 AI 提供商。您可以使用 OpenAI、Anthropic 或任何兼容 OpenAI 的 API 服务。

​

基于环境变量的回退机制

如果配置文件中未指定 AI 配置，ClickHouse 客户端 会自动尝试使用环境变量：

1. 首先检查 OPENAI_API_KEY 环境变量
2. 如果未找到，再检查 ANTHROPIC_API_KEY 环境变量
3. 如果两者都未找到，则会禁用 AI 功能

这样无需配置文件也能快速完成设置：

# 使用 OpenAI
export OPENAI_API_KEY=your-openai-key
clickhouse-client

# 使用 Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key
clickhouse-client

​

配置文件

如需更精细地控制 AI 设置，请在位于以下位置的 ClickHouse 客户端配置文件中进行配置：

• $XDG_CONFIG_HOME/clickhouse/config.xml (如果未设置 XDG_CONFIG_HOME，则使用 ~/.config/clickhouse/config.xml) (XML 格式)
• $XDG_CONFIG_HOME/clickhouse/config.yaml (如果未设置 XDG_CONFIG_HOME，则使用 ~/.config/clickhouse/config.yaml) (YAML 格式)
• ~/.clickhouse-client/config.xml (XML 格式，旧版位置)
• ~/.clickhouse-client/config.yaml (YAML 格式，旧版位置)
• 或使用 --config-file 指定自定义位置

XML

<config>
    <ai>
        {/* 必填：你的 API 密钥（或通过环境变量设置） */}
        <api_key>your-api-key-here</api_key>

        {/* 必填：提供商类型（openai、anthropic） */}
        <provider>openai</provider>

        {/* 要使用的模型（默认值因提供商而异） */}
        <model>gpt-4o</model>

        {/* 可选：用于 OpenAI 兼容服务的自定义 API 端点 */}
        {/* <base_url>https://openrouter.ai/api</base_url> */}

        {/* schema 探索设置 */}
        <enable_schema_access>true</enable_schema_access>

        {/* 生成参数 */}
        <temperature>0.0</temperature>
        <max_tokens>1000</max_tokens>
        <timeout_seconds>30</timeout_seconds>
        <max_steps>10</max_steps>

        {/* 可选：自定义系统提示 */}
        {/* <system_prompt>You are an expert ClickHouse SQL assistant...</system_prompt> */}
    </ai>
</config>

YAML

ai:
  # 必填：你的 API 密钥（或通过环境变量设置）
  api_key: your-api-key-here

  # 必填：提供商类型（openai、anthropic）
  provider: openai

  # 要使用的模型
  model: gpt-4o

  # 可选：用于 OpenAI 兼容服务的自定义 API 端点
  # base_url: https://openrouter.ai/api

  # 启用 schema 访问 - 允许 AI 查询数据库/表信息
  enable_schema_access: true

  # 生成参数
  temperature: 0.0      # 控制随机性（0.0 = 确定性）
  max_tokens: 1000      # 最大响应长度
  timeout_seconds: 30   # 请求超时
  max_steps: 10         # schema 探索的最大步数

  # 可选：自定义系统提示
  # system_prompt: |
  #   You are an expert ClickHouse SQL assistant. Convert natural language to SQL.
  #   Focus on performance and use ClickHouse-specific optimizations.
  #   Always return executable SQL without explanations.

使用 OpenAI 兼容 API (例如 OpenRouter) ：

ai:
  provider: openai  # 使用 'openai' 以保持兼容性
  api_key: your-openrouter-api-key
  base_url: https://openrouter.ai/api/v1
  model: anthropic/claude-3.5-sonnet  # 使用 OpenRouter 模型命名规范

最简配置示例：

# 最小配置 - 使用环境变量作为 API 密钥
ai:
  provider: openai  # 将使用 OPENAI_API_KEY 环境变量

# 完全无配置 - 自动回退
# （ai 部分为空或不存在 - 将依次尝试 OPENAI_API_KEY 和 ANTHROPIC_API_KEY）

# 仅覆盖模型 - 使用环境变量作为 API 密钥
ai:
  provider: openai
  model: gpt-3.5-turbo

​

参数

必填参数

• api_key - AI 服务的 API 密钥。如果已通过环境变量设置，则可省略：
  • OpenAI: OPENAI_API_KEY
  • Anthropic: ANTHROPIC_API_KEY
  • 注意：配置文件中的 API 密钥优先于环境变量
• provider - AI 提供商：openai 或 anthropic
  • 如果省略，将根据可用的环境变量自动进行回退

模型配置

• model - 要使用的模型 (默认值：取决于所选提供商)
  • OpenAI: gpt-4o, gpt-4, gpt-3.5-turbo 等
  • Anthropic: claude-3-5-sonnet-20241022, claude-3-opus-20240229 等
  • OpenRouter: 使用其模型命名格式，例如 anthropic/claude-3.5-sonnet

连接设置

• base_url - 用于 OpenAI 兼容服务的自定义 API 端点 (可选)
• timeout_seconds - 请求超时时间 (单位：秒) (默认值：30)

Schema 探索

• enable_schema_access - 允许 AI 探索数据库 schema (默认值：true)
• max_steps - schema 探索期间可调用工具的最大步数 (默认值：10)

生成参数

• temperature - 控制随机性，0.0 = 确定性，1.0 = 更具创造性 (默认值：0.0)
• max_tokens - 响应的最大长度 (以标记数计) (默认值：1000)
• system_prompt - 提供给 AI 的自定义指令 (可选)

​

工作原理

AI SQL 生成器采用多步骤流程：

1. Schema 发现

AI 使用内置工具探索你的数据库：

• 列出可用的数据库
• 发现相关数据库中的表
• 通过 CREATE TABLE 语句检查表结构

2. 查询生成

基于发现的 schema，AI 会生成满足以下条件的 SQL：

• 符合你的自然语言意图
• 使用正确的表名和列名
• 应用适当的连接和聚合

3. 执行

生成的 SQL 会自动执行，并显示结果

​

局限性

• 需要可用的互联网连接
• API 的使用受 AI 提供商的速率限制和费用约束
• 复杂查询可能需要多次调整
• AI 仅对 schema 信息具有只读访问权限，无法访问实际数据

​

安全性

• API 密钥绝不会发送到 ClickHouse 服务器
• AI 只能看到 schema 信息 (表名/列名和类型) ，看不到实际数据
• 所有生成的查询都会遵循您现有的数据库权限

​

连接字符串

​

用法

ClickHouse Client 还支持通过与 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 允许以下键：

Key	Description
secure (or s)	如果指定，客户端将通过安全连接 (TLS) 连接到服务器。请参见命令行选项中的 --secure。

百分号编码

以下参数中的非 US-ASCII 字符、空格和特殊字符必须进行百分号编码：

• user
• password
• hosts
• database
• query parameters

​

示例

连接到 localhost 的 9000 端口，并执行查询 SELECT 1。

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

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

clickhouse-client clickhouse://john:secret@127.0.0.1:9000

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

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

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

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

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

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

# 等价于：
clickhouse-client clickhouse://localhost:9000 --user default

连接到 localhost 的 9000 端口，并默认使用 my_database 数据库。

clickhouse-client clickhouse://localhost:9000/my_database

# 等价于：
clickhouse-client clickhouse://localhost:9000 --database my_database

连接到端口 9000 上的 localhost，默认使用连接字符串中指定的 my_database database，并通过简写的 s 参数建立安全连接。

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

# 等价于：
clickhouse-client clickhouse://localhost/my_database -s

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

clickhouse-client clickhouse:

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

clickhouse-client clickhouse://my_user@

# 在 : 和 @ 之间使用空密码，表示在建立连接之前提示用户输入密码。
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]
• $XDG_CONFIG_HOME/clickhouse/config.[xml|yaml|yml] (如果未设置 XDG_CONFIG_HOME，则使用 ~/.config/clickhouse/config.[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'

​

环境变量选项

可通过环境变量 CLICKHOUSE_USER、CLICKHOUSE_PASSWORD 和 CLICKHOUSE_HOST 设置用户名、密码和主机。 命令行参数 --user、--password 或 --host，或者连接字符串 (如果已指定) ，其优先级均高于环境变量。

​

命令行选项

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

​

常规选项

选项	描述	默认值
-c [ -C, --config, --config-file ] <path-to-file>	如果客户端的配置文件不在默认位置之一，可用此选项指定其位置。参见 配置文件。	-
--help	打印用法摘要并退出。与 --verbose 一起使用时，可显示所有可用选项，包括查询设置。	-
--history_file <path-to-file>	包含命令历史记录的文件路径。	-
--history_max_entries	历史记录文件中的最大条目数。	1000000 (100 万)
--prompt <prompt>	指定自定义提示符。	server 的 display_name
--verbose	提高输出的详细程度。	-
-V [ --version ]	打印版本信息并退出。	-

​

连接选项

选项	描述	默认值
--connection <name>	配置文件中预先配置的连接信息名称。请参见连接凭据。	-
-d [ --database ] <database>	选择此连接默认使用的数据库。	服务器设置中的当前数据库 (默认为 default)
-h [ --host ] <host>	要连接的 ClickHouse 服务器主机名。可以是主机名，也可以是 IPv4 或 IPv6 地址。也可以通过多次传入该参数指定多个主机。	localhost
--jwt <value>	使用 JSON Web Token (JWT) 进行身份验证。 服务器 JWT 授权仅在 ClickHouse Cloud 中可用。	-
login	调用设备授权 OAuth 流程，通过 IdP 进行身份验证。 对于 ClickHouse Cloud 主机，OAuth 变量会自动推断；否则必须通过 --oauth-url、--oauth-client-id 和 --oauth-audience 提供。	-
--no-warnings	禁止在客户端连接到服务器时显示来自 system.warnings 的警告。	-
--no-server-client-version-message	禁止在客户端连接到服务器时显示服务端与客户端版本不匹配的消息。	-
--password <password>	数据库用户的密码。你也可以在配置文件中为连接指定密码。如果未指定密码，客户端会提示你输入。	-
--port <port>	服务器接受连接的端口。默认端口为 9440 (TLS) 和 9000 (无 TLS) 。 注意：客户端使用的是原生协议，而不是 HTTP(S)。	如果指定了 --secure，则为 9440，否则为 9000。如果主机名以 .clickhouse.cloud 结尾，则始终默认为 9440。
-s [ --secure ]	是否使用 TLS。 连接到端口 9440 (默认安全端口) 或 ClickHouse Cloud 时会自动启用。 你可能需要在配置文件中配置 CA 证书。可用配置项与服务端 TLS 配置相同。	连接到端口 9440 或 ClickHouse Cloud 时自动启用
--ssh-key-file <path-to-file>	包含用于向服务器进行身份验证的 SSH 私钥的文件。	-
--ssh-key-passphrase <value>	--ssh-key-file 中指定的 SSH 私钥的密码短语。	-
--tls-sni-override <server name>	如果使用 TLS，则在握手时传递的服务器名称 (SNI) 。	通过 -h 或 --host 提供的主机名。
-u [ --user ] <username>	用于连接的数据库用户。	default

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

​

查询选项

选项	描述
--param_<name>=<value>	带参数的查询中某个参数的替换值。
-q [ --query ] <query>	要在批次模式下运行的查询。可多次指定 (--query "SELECT 1" --query "SELECT 2") ，也可一次指定多个以分号分隔的查询 (--query "SELECT 1; SELECT 2;") 。在后一种情况下，格式不是 VALUES 的 INSERT 查询必须用空行分隔。 也可以不带参数直接指定单个查询：clickhouse-client "SELECT 1" 不能与 --queries-file 同时使用。
--queries-file <path-to-file>	包含查询的文件路径。--queries-file 可多次指定，例如 --queries-file queries1.sql --queries-file queries2.sql。 不能与 --query 同时使用。
-m [ --multiline ]	如果指定此选项，则允许输入多行查询 (按 Enter 时不会发送查询) 。只有当查询以分号结尾时才会发送。
--inline-insert-data	将 INSERT ... VALUES (以及其他内联格式) 按原样作为查询文本发送，而不是先将数据转换为原生格式中的块。服务器会自行解析内联数据，从而避免将表结构和列默认值回传给客户端所需的往返通信。对于通过原生协议执行的大量小型插入操作，这可以提升性能。会自动将 send_table_structure_on_insert_with_inline_data 设置为 0。不能与内联数据和外部数据 (来自 stdin 或 INFILE) 同时使用。

​

查询设置

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

$ clickhouse-client --max_threads 1

设置列表请参见设置。

​

格式选项

Option	Description	Default
-f [ --format ] <format>	使用指定的格式输出结果。 支持的格式列表请参见输入和输出数据格式。	TabSeparated
--pager <command>	将所有输出通过管道传递给此命令。通常是 less (例如，使用 less -S 显示较宽的结果集) 或类似命令。	-
-E [ --vertical ]	使用 Vertical format 输出结果。这与 –-format Vertical 相同。在这种格式下，每个值都会单独打印在一行中，因此在显示宽表时很有帮助。	-
--echo [ <bool> ]	在执行前打印每个查询。可选接受一个布尔值。	交互模式下为 true，非交互 (批次) 模式下为 false
--echo-formatted [ <bool> ]	对回显的查询进行格式化。可选接受一个布尔值。	交互模式下为 true，非交互 (批次) 模式下为 false
--echo-query-id [ <bool> ]	在执行前打印查询 ID。可选接受一个布尔值。	交互模式下为 true，非交互 (批次) 模式下为 false
--highlight [ --hilite ] <bool>	切换命令提示符和回显查询的语法高亮显示。	true

​

执行细节

选项	说明	默认值
--chime [N]	当查询运行时间至少达到 N 秒后结束时 (无论成功还是出错) ，向 stderr 写入 BEL 控制字符。仅当 stderr 连接到终端 (TTY) 时才会发出；重定向 stderr (例如 2>err.log) 会抑制它，而重定向 stdout (例如 > result.tsv) 则不会。传入不带值的 --chime 时，将使用默认阈值。设为 --chime 0 可禁用。	5 秒
--enable-progress-table-toggle	启用通过按控制键 (空格) 切换进度表的功能。仅适用于已启用进度表打印的交互模式。	enabled
--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 (用于性能测试) 。	-