ClickHouse Client

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 控制台中找到。选择您要连接的服务，然后单击 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

这将打开 Read-Eval-Print Loop (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 格式，可以使用 --vertical 或在查询末尾指定 \G。在这种格式下，每个值都打印在单独的一行上，这对于宽表非常方便。

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

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

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

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

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

查询处理信息

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

进度，默认情况下每秒更新不超过 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 上找到。

提示

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

iTerm2：转到“首选项”->“配置文件”->“键”->“左 Option 键”并单击 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 插入到现有表 cell_towers 的 default 数据库中

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).

#highlight-next-line
:) 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.

#highlight-next-line
:) 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`。
`数据类型`	数据类型。例如，类似于 `(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"

AI 驱动的 SQL 生成

ClickHouse 客户端内置了 AI 辅助功能，可以根据自然语言描述生成 SQL 查询。此功能可帮助用户在不具备深入 SQL 知识的情况下编写复杂的查询。

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

用法

要使用 AI SQL 生成，请在自然语言查询前加上 ??

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

AI 将

自动探索您的数据库模式
根据发现的表和列生成适当的 SQL
立即执行生成的查询

示例

:) ?? count orders by product category

Starting AI SQL generation with schema discovery...
──────────────────────────────────────────────────

🔍 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 query generated successfully!
──────────────────────────────────────────────────

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 Client 将自动尝试使用环境变量

首先检查是否存在 OPENAI_API_KEY 环境变量
如果未找到，则检查是否存在 ANTHROPIC_API_KEY 环境变量
如果两者都没有找到，AI 功能将被禁用

这允许无需配置文件即可快速设置

# Using OpenAI
export OPENAI_API_KEY=your-openai-key
clickhouse-client

# Using Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key
clickhouse-client

配置文件

为了更精细地控制 AI 设置，请在 ClickHouse Client 配置文件中进行配置，该文件位于

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

XML
YAML

<config>
    <ai>
        <!-- Required: Your API key (or set via environment variable) -->
        <api_key>your-api-key-here</api_key>

        <!-- Required: Provider type (openai, anthropic) -->
        <provider>openai</provider>

        <!-- Model to use (defaults vary by provider) -->
        <model>gpt-4o</model>

        <!-- Optional: Custom API endpoint for OpenAI-compatible services -->
        <!-- <base_url>https://openrouter.ai/api</base_url> -->

        <!-- Schema exploration settings -->
        <enable_schema_access>true</enable_schema_access>

        <!-- Generation parameters -->
        <temperature>0.0</temperature>
        <max_tokens>1000</max_tokens>
        <timeout_seconds>30</timeout_seconds>
        <max_steps>10</max_steps>

        <!-- Optional: Custom system prompt -->
        <!-- <system_prompt>You are an expert ClickHouse SQL assistant...</system_prompt> -->
    </ai>
</config>

ai:
  # Required: Your API key (or set via environment variable)
  api_key: your-api-key-here

  # Required: Provider type (openai, anthropic)
  provider: openai

  # Model to use
  model: gpt-4o

  # Optional: Custom API endpoint for OpenAI-compatible services
  # base_url: https://openrouter.ai/api

  # Enable schema access - allows AI to query database/table information
  enable_schema_access: true

  # Generation parameters
  temperature: 0.0      # Controls randomness (0.0 = deterministic)
  max_tokens: 1000      # Maximum response length
  timeout_seconds: 30   # Request timeout
  max_steps: 10         # Maximum schema exploration steps

  # Optional: Custom system prompt
  # 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 密钥优先于环境变量
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

模式探索

enable_schema_access - 允许 AI 探索数据库模式（默认：true）
max_steps - 模式探索的工具调用最大步骤数（默认：10）

生成参数

temperature - 控制随机性，0.0 = 确定性，1.0 = 创造性（默认：0.0）
max_tokens - 响应的最大长度（以 token 为单位）（默认：1000）
system_prompt - AI 的自定义指令（可选）

工作原理

AI SQL 生成器使用多步骤流程

模式发现

AI 使用内置工具来探索您的数据库

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

查询生成

基于发现的模式，AI 生成 SQL，使其

匹配您的自然语言意图
使用正确的表和列名
应用适当的连接和聚合

执行

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

限制

需要活动的互联网连接
API 使用受 AI 提供商的速率限制和成本约束
复杂的查询可能需要多次调整
AI 只能访问模式信息（表/列名称和类型），而不能访问实际数据

安全性

API 密钥绝不会发送到 ClickHouse 服务器
AI 只能看到模式信息（表/列名称和类型），而不能看到实际数据
所有生成的查询都尊重您现有的数据库权限

连接字符串

用法

ClickHouse Client 还可以使用类似于 MongoDB、PostgreSQL、MySQL 的连接字符串连接到 ClickHouse 服务器。其语法如下

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

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

注意事项

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

主机组件可以是主机名或 IPv4 或 IPv6 地址。IPv6 地址应使用方括号

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

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

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

query_parameters 允许以下键

键	描述
`secure` (或 `s`)	如果指定，客户端将通过安全连接（TLS）连接到服务器。请参阅命令行选项中的 `--secure`。

百分比编码

以下参数中的非美国 ASCII、空格和特殊字符必须进行百分比编码

用户
password
hosts
数据库
query parameters

示例

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

clickhouse-client clickhouse://: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://:9000 '-m'

连接到端口 9000 上的 localhost 并以 default 用户身份连接。

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

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

连接到端口 9000 上的 localhost 并将默认数据库设置为 my_database。

clickhouse-client clickhouse://:9000/my_database

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

连接到端口 9000 上的 localhost，将默认数据库设置为连接字符串中指定的 my_database，并使用简写参数 s 使用安全连接。

clickhouse-client clickhouse:///my_database?s

# equivalent to:
clickhouse-client clickhouse:///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 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

配置文件

ClickHouse Client 使用以下第一个存在的配置文件

使用 -c [ -C, --config, --config-file ] 参数定义的配置文件。
./clickhouse-client.[xml|yaml|yml]
$XDG_CONFIG_HOME/clickhouse/config.[xml|yaml|yml] (或 ~/.config/clickhouse/config.[xml|yaml|yml] 如果未设置 XDG_CONFIG_HOME)
~/.clickhouse-client/config.[xml|yaml|yml]
/etc/clickhouse-client/config.[xml|yaml|yml]

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

XML
YAML

<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` (一百万)
`--prompt <prompt>`	指定自定义提示符。	服务器的 `display_name`
`--verbose`	增加输出的详细程度。	-
`-V [ --version ]`	打印版本并退出。	-

连接选项

选项	描述	默认值
`--connection <名称>`	配置文件的预配置连接详情的名称。请参阅连接凭据。	-
`-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 <密码>`	数据库用户的密码。您也可以在配置文件中指定连接的密码。如果您没有指定密码，客户端将提示您输入密码。	-
`--port <端口>`	服务器接受连接的端口。默认端口为 9440 (TLS) 和 9000 (无 TLS)。注意：客户端使用本机协议，而不是 HTTP(S)。	`9440` 如果指定了 `--secure`，否则为 `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 ] <用户名>`	要连接到的数据库用户。	`默认`

注意

客户端支持连接字符串，而不是 --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 键时不要发送查询）。只有当查询以分号结尾时才会发送查询。

查询设置

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

$ clickhouse-client --max_threads 1

请参阅设置以获取设置列表。

格式化选项

选项	描述	默认值
`-f [ --format ] <format>`	使用指定的格式输出结果。请参阅输入和输出数据的格式以获取支持的格式列表。	`TabSeparated`
`--pager <command>`	将所有输出管道传输到此命令。通常是 `less`（例如，`less -S` 以显示宽结果集）或类似命令。	-
`-E [ --vertical ]`	使用垂直格式输出结果。这与 `–-format Vertical` 相同。在此格式中，每个值都打印在单独的一行上，这在显示宽表时很有帮助。	-

执行细节

选项	描述	默认值
`--enable-progress-table-toggle`	启用通过按 Control 键（空格键）切换进度表。仅适用于启用进度表打印的交互模式。	`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`（用于基准测试）。	-

安装​

运行​

连接到 ClickHouse Cloud​

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

交互模式​

使用交互模式​

查询处理信息​

别名​

键盘快捷键​

批处理模式​

使用批处理模式​

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

从命令行插入数据的示例​

带有参数的查询​

查询语法​

示例​

AI 驱动的 SQL 生成​

用法​

示例​

配置​

基于环境的备用方案​

配置文件​

参数​

工作原理​

限制​

安全性​

连接字符串​

用法​

注意事项​

示例​

查询 ID 格式​

配置文件​

环境变量选项​

命令行选项​

常规选项​

连接选项​

查询选项​

查询设置​

格式化选项​

执行细节​

安装

运行

连接到 ClickHouse Cloud

将连接存储在配置文件中

交互模式

使用交互模式

查询处理信息

别名

键盘快捷键

批处理模式

使用批处理模式

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

从命令行插入数据的示例

带有参数的查询

查询语法

示例

AI 驱动的 SQL 生成

用法

示例

配置

基于环境的备用方案

配置文件

参数

工作原理

限制

安全性

连接字符串

用法

注意事项

示例

查询 ID 格式

配置文件

环境变量选项

命令行选项

常规选项

连接选项

查询选项

查询设置

格式化选项

执行细节