ClickHouse 提供原生命令行客户端,可直接向 ClickHouse 服务器执行 SQL 查询。 它同时支持交互模式 (用于实时执行查询) 和批次模式 (用于脚本编写和自动化) 。 查询结果既可显示在终端中,也可导出到文件,并支持所有 ClickHouse 输出格式,例如 Pretty、CSV、JSON 等。
该客户端可通过进度条、已读取的行数、已处理的字节数以及查询执行时间,实时反馈查询执行进度。 它同时支持命令行选项和配置文件。
安装
下载 ClickHouse,请运行:
curl https://clickhouse.com/ | sh如需一并安装,请运行:
sudo ./clickhouse install更多安装选项,请参见安装 ClickHouse。
不同版本的客户端和 server 彼此兼容,但某些功能在较旧版本的客户端中可能不可用。我们建议客户端和 server 使用相同的版本。
运行
要连接到 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 <port> |
ClickHouse 服务器接受连接的端口。默认端口为 9440 (TLS) 和 9000 (不使用 TLS)。如果既未指定 --port 也未指定 --secure,则会并发尝试两个默认端口,并使用最先响应的端口。因此,如果 server 仅监听其中一个端口,也能直接连接,无需等待另一个端口的连接超时。请注意,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>更多信息,请参阅配置文件一节。
交互模式
使用 交互模式
要以 交互模式 运行 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或:qlogout或logout;
获取帮助
你无需离开客户端,即可查阅系统中任意函数、表引擎、数据类型、格式、设置及其他组件的文档。输入 help 后接名称即可 (/help、man 和 /man 这几种等效形式也可用) :
help domainWithoutWWW该查找不区分大小写,并会查询 system.documentation 表。匹配到的文档会在终端中由 Markdown 渲染显示,包含粗体/斜体文本、表格以及带语法高亮的代码块。当多个组件共用同一个名称时 (例如 file,它既是函数,也是表引擎) ,它们都会显示出来。
当没有完全匹配的结果时,客户端会列出相近的名称 (允许存在拼写错误) 以及文档中提到该词的组件:
help maxx_threads单独输入 help 会显示简短的用法摘要。
命令
客户端会自行执行一些以 / 开头的命令,而不是将其发送到服务器:
| 命令 | 描述 |
|---|---|
/help <name>, /man <name> |
显示 <name> 的文档,与上述 help 相同 |
/clear |
清空终端 |
在输入开头键入 / 会以提示的形式列出命令;继续输入名称可缩小列表范围。Tab 可补全正在输入的命令;提示被禁用时,也可通过这种方式补全命令。单独提交 / 并非命令:与 Oracle SQL*Plus 一样,它会重复上一次输入。拼写错误的命令名称会被提示为错误,并显示可能想输入的命令,而不会将其作为查询执行:
:) /hepl
Exception on client:
Code: 36. DB::Exception: Unknown command `/hepl`. Maybe you meant: ['/help']. Type `/` at the beginning of the line to see all the commands. (BAD_ARGUMENTS)查询处理信息
在处理查询时,客户端会显示:
- 进度,默认情况下每秒最多更新 10 次。 对于执行很快的查询,进度可能还来不及显示。
- 解析后生成的格式化后的查询,用于调试。
- 以指定格式输出的结果。
- 结果中的行数、已耗时间以及查询处理的平均速度。 所有数据量均指未压缩数据。
你可以按 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。
批次模式
使用批次模式
你可以不以交互方式使用 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 daysAI 将:
- 自动探索你的数据库 schema
- 根据发现的表和列生成合适的 SQL
- 立即执行生成的查询
示例
:) ?? 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 客户端 会自动尝试使用环境变量:
- 首先检查
OPENAI_API_KEY环境变量 - 如果未找到,再检查
ANTHROPIC_API_KEY环境变量 - 如果两者都未找到,则会禁用 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指定自定义位置
<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 才会发送给模型。
默认会省略它,因为某些模型会拒绝此参数。 */}
{/* <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>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 才会发送给模型;默认会省略
# 因为某些模型会拒绝此参数。
# 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 # Use 'openai' for compatibility
api_key: your-openrouter-api-key
base_url: https://openrouter.ai/api/v1
model: anthropic/claude-3.5-sonnet # Use OpenRouter model naming最简配置示例:
# Minimal config - uses environment variable for API key
ai:
provider: openai # Will use OPENAI_API_KEY env var
# No config at all - automatic fallback
# (Empty or no ai section - will try OPENAI_API_KEY then ANTHROPIC_API_KEY)
# Only override model - uses env var for API key
ai:
provider: openai
model: gpt-3.5-turbo参数
必填参数
api_key- AI 服务的 API 密钥。如果已通过环境变量设置,则可省略:- OpenAI:
OPENAI_API_KEY - Anthropic:
ANTHROPIC_API_KEY - 注意:配置文件中的 API 密钥优先于环境变量
- OpenAI:
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
- OpenAI:
连接设置
base_url- 用于兼容 OpenAI 的服务的自定义 API 端点 (可选)timeout_seconds- 请求超时时间 (单位:秒) (默认值:30)
Schema 探索
enable_schema_access- 允许 AI 探索数据库 schema (默认值:true)max_steps- schema 探索期间可调用工具的最大步数 (默认值:10)
生成参数
temperature- 控制随机性,0.0 = 确定性,1.0 = 更具创造性。默认情况下会省略,仅在显式设置时才会发送给模型,因为某些模型会拒绝此参数。max_tokens- 响应的最大长度 (以标记数计) (默认值:1000)system_prompt- 提供给 AI 的自定义指令 (可选)
工作原理
AI SQL 生成器采用多步骤流程:
- Schema 发现
AI 使用内置工具探索你的数据库:
- 列出可用的数据库
- 发现相关数据库中的表
- 通过
CREATE TABLE语句检查表结构
- 查询生成
基于发现的 schema,AI 会生成满足以下条件的 SQL:
- 符合你的自然语言意图
- 使用正确的表名和列名
- 应用适当的连接和聚合
- 执行
生成的 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[,¶m2=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 字符、空格和特殊字符必须进行百分号编码:
userpasswordhostsdatabasequery 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
<config>
<user>username</user>
<password>password</password>
<secure>true</secure>
<openSSL>
<client>
<caConfig>/etc/ssl/cert.pem</caConfig>
</client>
</openSSL>
</config>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。如果未指定 --port 和 --secure,将并发探测端口 9000 和 9440,并使用最先响应的端口。 |
-s [ --secure ] |
是否使用 TLS。 连接到端口 9440 (默认安全端口) 或 ClickHouse Cloud 时会自动启用;当未指定 --port 和 --secure 且安全端口最先响应探测时,也会自动启用。对于仅在安全端口响应的服务器,这始终如此 (例如 play.clickhouse.com,其普通端口受防火墙阻断);对于同时监听两个端口的服务器,也可能如此。由于在这种情况下并未请求 TLS,因此即使安全端口最终无法使用 (例如证书不受信任),也不会视为错误:客户端会回退到普通端口,即未进行自动选择时原本会连接的端口。指定 --secure 以强制使用 TLS。你可能需要在配置文件中配置 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 |
查询选项
| 选项 | 描述 |
|---|---|
--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 Vertical 相同。在这种格式下,每个值都会单独打印在一行中,因此在显示宽表时很有帮助。 |
- |
--echo [ <bool> ] |
在执行前打印每个查询。可选接受一个布尔值。 | 交互模式下为 true,非交互 (批次) 模式下为 false |
--echo-formatted [ <bool> ] |
对回显的查询进行格式化。可选接受一个布尔值。 | 交互模式下为 true,非交互 (批次) 模式下为 false |
--echo-query-id [ <bool> ] |
在执行前打印查询 ID。可选接受一个布尔值。 | 交互模式下为 true,非交互 (批次) 模式下为 false |
--echo-query-separator <string> |
在格式化后的回显查询前打印此分隔符 (需要 --echo-formatted),以便更容易区分输入的查询和重新格式化后的回显。 |
空 (已禁用) |
--highlight [ --hilite ] <bool> |
切换命令提示符和回显查询的语法高亮显示。 | true |
--hints <bool> |
当光标位于输入末尾时,显示键入时的自动补全提示 (内联“幽灵”文本) ,给出最佳匹配建议。使用 Up/Down (或 Ctrl-Up/Ctrl-Down) 浏览提示;使用 Tab 或 Right 接受内联提示;Enter 仅在已显式选择某个提示后才会接受该提示,否则会运行查询;Tab 还会打开传统补全列表。需要启用 --highlight (提示需要颜色)。建议提示还需要建议机制,因此 --disable_suggestion 会将其关闭;只要启用了 --hints 和 --highlight,客户端的 / 命令 就是静态列表,并会始终显示提示。即使关闭了提示,Tab 仍可补全 / 命令。 |
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 (用于性能测试) 。 |
- |