> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 命令行客户端的文档

# ClickHouse 客户端

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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

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

<div id="install">
  ## 安装
</div>

下载 ClickHouse，请运行：

```bash theme={null}
curl https://clickhouse.com/ | sh
```

如需一并安装，请运行：

```bash theme={null}
sudo ./clickhouse install
```

更多安装选项，请参见[安装 ClickHouse](/zh/get-started/setup/install)。

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

<div id="run">
  ## 运行
</div>

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

要连接到 ClickHouse server，请运行：

```bash theme={null}
$ 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 客户端 配置文件的位置 (如果该文件不在默认位置之一) 。请参见[配置文件](#configuration_files)。                                          |
| `--connection <name>`            | [配置文件](#connection-credentials)中预先配置的连接信息名称。                                                                      |

有关命令行选项的完整列表，请参见[命令行选项](#command-line-options)。

<div id="connecting-cloud">
  ### 连接到 ClickHouse Cloud
</div>

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

<Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/1oh4rjwfuHRS2yL2/images/_snippets/cloud-connect-button.png?fit=max&auto=format&n=1oh4rjwfuHRS2yL2&q=85&s=81c1524ac8ac2dac27e1558f13fcfd29" size="md" alt="ClickHouse Cloud 服务连接按钮" width="998" height="932" data-path="images/_snippets/cloud-connect-button.png" />

<br />

<br />

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

<Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/1oh4rjwfuHRS2yL2/images/_snippets/connection-details-native.png?fit=max&auto=format&n=1oh4rjwfuHRS2yL2&q=85&s=9ba181c45544519e5740b47a78269f38" size="md" alt="ClickHouse Cloud Native TCP 连接详细信息" width="1290" height="1176" data-path="images/_snippets/connection-details-native.png" />

<div id="connection-credentials">
  ### 在配置文件中存储连接信息
</div>

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

格式如下：

```xml theme={null}
<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>
```

更多信息，请参阅[配置文件](#configuration_files)一节。

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

<div id="interactive-mode">
  ## 交互模式
</div>

<div id="using-interactive-mode">
  ### 使用 交互模式
</div>

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

```bash theme={null}
clickhouse-client
```

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

```bash theme={null}
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;`

<div id="processing-info">
  ### 查询处理信息
</div>

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

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

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

ClickHouse 客户端 允许在查询时传递外部数据 (外部临时表) 。
更多信息，请参见 [查询处理的外部数据](/zh/reference/engines/table-engines/special/external-data) 一节。

<div id="cli_aliases">
  ### 别名
</div>

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

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

<div id="keyboard_shortcuts">
  ### 键盘快捷键
</div>

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

所有可用键盘快捷键的完整列表请参见 [replxx](https://github.com/AmokHuginnsson/replxx/blob/1f149bf/src/replxx_impl.cxx#L262)。

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

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

<div id="batch-mode">
  ## 批次模式
</div>

<div id="using-batch-mode">
  ### 使用批次模式
</div>

你可以不以交互方式使用 ClickHouse 客户端，而是让它以批次模式运行。
在批次模式下，ClickHouse 只执行一条查询并立即退出——不会出现交互式提示符，也不会进入循环。

你可以像下面这样指定单条查询：

```bash theme={null}
$ clickhouse-client "SELECT sum(number) FROM numbers(10)"
45
```

你也可以使用命令行选项 `--query`：

```bash theme={null}
$ clickhouse-client --query "SELECT uniq(number) FROM numbers(10)"
10
```

你可以通过 `stdin` 传入查询：

```bash theme={null}
$ echo "SELECT avg(number) FROM numbers(10)" | clickhouse-client
4.5
```

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

```bash theme={null}
$ echo "Hello\nGoodbye" | clickhouse-client --query "INSERT INTO messages FORMAT CSV"
```

指定 `--query` 时，所有输入都会在一个换行符后追加到请求中。

<div id="cloud-example">
  ### 将 CSV 文件插入远程 ClickHouse 服务
</div>

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

```bash theme={null}
clickhouse-client --host HOSTNAME.clickhouse.cloud \
  --port 9440 \
  --user default \
  --password PASSWORD \
  --query "INSERT INTO cell_towers FORMAT CSVWithNames" \
  < cell_towers.csv
```

<div id="more-examples">
  ### 从命令行插入数据示例
</div>

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

```bash theme={null}
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`，然后将其输出：

```bash theme={null}
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` 作为输入：

```bash theme={null}
cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
```

在批次模式下，默认的数据[格式](/zh/reference/formats)为 `TabSeparated`。
如上例所示，你可以在查询的 `FORMAT` 子句中设置格式。

<div id="cli-queries-with-parameters">
  ## 带参数的查询
</div>

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

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

也可以在[交互式会话](#interactive-mode)中设置参数：

```text highlight={4,14} theme={null}
$ 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.
```

<div id="cli-queries-with-parameters-syntax">
  ### 查询语法
</div>

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

```sql theme={null}
{<name>:<data type>}
```

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

<div id="cli-queries-with-parameters-examples">
  ### 示例
</div>

```bash theme={null}
$ 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"
```

<div id="ai-sql-generation">
  ## AI SQL 生成
</div>

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

如果已设置 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` 环境变量，AI 辅助功能即可开箱即用。有关更高级的配置，请参阅[配置](#ai-sql-generation-configuration)部分。

<div id="ai-sql-generation-usage">
  ### 用法
</div>

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

```bash theme={null}
:) ?? show all users who made purchases in the last 30 days
```

AI 将：

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

<div id="cli-queries-with-parameters-examples">
  ### 示例
</div>

```bash theme={null}
:) ?? 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
```

<div id="ai-sql-generation-configuration">
  ### 配置
</div>

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

<div id="ai-sql-generation-fallback">
  #### 基于环境变量的回退机制
</div>

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

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

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

```bash theme={null}
# 使用 OpenAI
export OPENAI_API_KEY=your-openai-key
clickhouse-client

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

<div id="ai-sql-generation-configuration-file">
  #### 配置文件
</div>

如需更精细地控制 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` 指定自定义位置

<Tabs>
  <Tab title="XML">
    ```xml theme={null}
    <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>
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    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.
    ```
  </Tab>
</Tabs>

<br />

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

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

**最简配置示例：**

```yaml theme={null}
# 最小配置 - 使用环境变量作为 API 密钥
ai:
  provider: openai  # 将使用 OPENAI_API_KEY 环境变量

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

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

<div id="ai-sql-generation-parameters">
  ### 参数
</div>

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

<Accordion title="模型配置">
  * `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`
</Accordion>

<Accordion title="连接设置">
  * `base_url` - 用于 OpenAI 兼容服务的自定义 API 端点 (可选)
  * `timeout_seconds` - 请求超时时间 (单位：秒)  (默认值：`30`)
</Accordion>

<Accordion title="Schema 探索">
  * `enable_schema_access` - 允许 AI 探索数据库 schema (默认值：`true`)
  * `max_steps` - schema 探索期间可调用工具的最大步数 (默认值：`10`)
</Accordion>

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

<div id="ai-sql-generation-how-it-works">
  ### 工作原理
</div>

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

1. **Schema 发现**

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

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

2. **查询生成**

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

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

3. **执行**

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

<div id="ai-sql-generation-limitations">
  ### 局限性
</div>

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

<div id="ai-sql-generation-security">
  ### 安全性
</div>

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

<div id="connection_string">
  ## 连接字符串
</div>

<div id="ai-sql-generation-usage">
  ### 用法
</div>

ClickHouse Client 还支持通过与 [MongoDB](https://www.mongodb.com/docs/manual/reference/connection-string/)、[PostgreSQL](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) 和 [MySQL](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri) 类似的连接字符串连接到 ClickHouse 服务器。其语法如下：

```text theme={null}
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], ...`。对于某些参数，可以不提供值。参数名称和值区分大小写。 | -                |

<div id="connection-string-notes">
  ### 注意事项
</div>

如果用户名、密码或数据库已在连接字符串中指定，则不能再通过 `--user`、`--password` 或 `--database` 指定 (反之亦然) 。

主机部分可以是主机名，也可以是 IPv4 或 IPv6 地址。
IPv6 地址应放在 `[]` 中：

```text theme={null}
clickhouse://[2001:db8::1234]
```

连接字符串可以包含多个主机。
ClickHouse 命令行客户端会按顺序 (从左到右) 尝试连接这些主机。
连接一旦建立，就不会再尝试连接其余主机。

连接字符串必须作为 `clickHouse-client` 的第一个参数指定。
除 `--host` 和 `--port` 外，连接字符串还可以与任意数量的其他[命令行选项](#command-line-options)组合使用。

`query_parameters` 允许以下键：

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

**百分号编码**

以下参数中的非 US-ASCII 字符、空格和特殊字符必须进行[百分号编码](https://en.wikipedia.org/wiki/URL_encoding)：

* `user`
* `password`
* `hosts`
* `database`
* `query parameters`

<div id="cli-queries-with-parameters-examples">
  ### 示例
</div>

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

```bash theme={null}
clickhouse-client clickhouse://localhost:9000 --query "SELECT 1"
```

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

```bash theme={null}
clickhouse-client clickhouse://john:secret@127.0.0.1:9000
```

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

```bash theme={null}
clickhouse-client clickhouse://[::1]:9000
```

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

```bash theme={null}
clickhouse-client clickhouse://localhost:9000 '-m'
```

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

```bash theme={null}
clickhouse-client clickhouse://default@localhost:9000

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

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

```bash theme={null}
clickhouse-client clickhouse://localhost:9000/my_database

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

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

```bash theme={null}
clickhouse-client clickhouse://localhost/my_database?s

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

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

```bash theme={null}
clickhouse-client clickhouse:
```

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

```bash theme={null}
clickhouse-client clickhouse://my_user@

# 在 : 和 @ 之间使用空密码，表示在建立连接之前提示用户输入密码。
clickhouse-client clickhouse://my_user:@
```

使用电子邮件地址作为用户名连接到 `localhost`。`@` 符号会进行百分号编码，变为 `%40`。

```bash theme={null}
clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000
```

连接到以下两台主机中的任意一台：`192.168.1.15`、`192.168.1.25`。

```bash theme={null}
clickhouse-client clickhouse://192.168.1.15,192.168.1.25
```

<div id="query-id-format">
  ## 查询 ID 格式
</div>

在交互模式中，ClickHouse 客户端 会为每个查询显示查询 ID。默认情况下，该 ID 的格式如下：

```sql theme={null}
Query id: 927f137d-00f1-4175-8914-0dd066365e96
```

可以在配置文件中的 `query_id_formats` 标签内指定自定义格式。格式字符串中的 `{query_id}` 占位符会替换为查询 ID。该标签内可包含多个格式字符串。
此功能可用于生成 URL，便于对查询进行性能分析。

**示例**

```xml theme={null}
<config>
  <query_id_formats>
    <speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
  </query_id_formats>
</config>
```

使用上述配置后，查询 ID 将以以下格式显示：

```response theme={null}
speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d
```

<div id="configuration_files">
  ## 配置文件
</div>

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`](https://github.com/ClickHouse/ClickHouse/blob/master/programs/client/clickhouse-client.xml)

<Tabs>
  <Tab title="XML">
    ```xml theme={null}
    <config>
        <user>username</user>
        <password>password</password>
        <secure>true</secure>
        <openSSL>
          <client>
            <caConfig>/etc/ssl/cert.pem</caConfig>
          </client>
        </openSSL>
    </config>
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    user: username
    password: 'password'
    secure: true
    openSSL:
      client:
        caConfig: '/etc/ssl/cert.pem'
    ```
  </Tab>
</Tabs>

<div id="environment-variable-options">
  ## 环境变量选项
</div>

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

<div id="command-line-options">
  ## 命令行选项
</div>

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

<div id="command-line-options-general">
  ### 常规选项
</div>

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

<div id="command-line-options-connection">
  ### 连接选项
</div>

| 选项                                   | 描述                                                                                                                                                                                                        | 默认值                                                                                |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `--connection <name>`                | 配置文件中预先配置的连接信息名称。请参见[连接凭据](#connection-credentials)。                                                                                                                                                      | -                                                                                  |
| `-d [ --database ] <database>`       | 选择此连接默认使用的数据库。                                                                                                                                                                                            | 服务器设置中的当前数据库 (默认为 `default`)                                                       |
| `-h [ --host ] <host>`               | 要连接的 ClickHouse 服务器主机名。可以是主机名，也可以是 IPv4 或 IPv6 地址。也可以通过多次传入该参数指定多个主机。                                                                                                                                     | `localhost`                                                                        |
| `--jwt <value>`                      | 使用 JSON Web Token (JWT) 进行身份验证。<br /><br />服务器 JWT 授权仅在 ClickHouse Cloud 中可用。                                                                                                                             | -                                                                                  |
| `login`                              | 调用设备授权 OAuth 流程，通过 IdP 进行身份验证。<br /><br />对于 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) 。<br /><br />注意：客户端使用的是原生协议，而不是 HTTP(S)。                                                                                                                       | 如果指定了 `--secure`，则为 `9440`，否则为 `9000`。如果主机名以 `.clickhouse.cloud` 结尾，则始终默认为 `9440`。 |
| `-s [ --secure ]`                    | 是否使用 TLS。<br /><br />连接到端口 9440 (默认安全端口) 或 ClickHouse Cloud 时会自动启用。<br /><br />你可能需要在[配置文件](#configuration_files)中配置 CA 证书。可用配置项与[服务端 TLS 配置](/zh/reference/settings/server-settings/settings#openssl)相同。 | 连接到端口 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`                                                                          |

<Note>
  除了 `--host`、`--port`、`--user` 和 `--password` 选项外，客户端还支持[连接字符串](#connection_string)。
</Note>

<div id="command-line-options-query">
  ### 查询选项
</div>

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

<div id="command-line-options-query-settings">
  ### 查询设置
</div>

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

```bash theme={null}
$ clickhouse-client --max_threads 1
```

设置列表请参见[设置](/zh/reference/settings/session-settings)。

<div id="command-line-options-formatting">
  ### 格式选项
</div>

| Option                     | Description                                                                                                            | Default        |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
| `-f [ --format ] <format>` | 使用指定的格式输出结果。<br /><br />支持的格式列表请参见[输入和输出数据格式](/zh/reference/formats)。                                                  | `TabSeparated` |
| `--pager <command>`        | 将所有输出通过管道传递给此命令。通常是 `less` (例如，使用 `less -S` 显示较宽的结果集) 或类似命令。                                                           | -              |
| `-E [ --vertical ]`        | 使用 [Vertical format](/zh/reference/formats/Vertical) 输出结果。这与 `–-format Vertical` 相同。在这种格式下，每个值都会单独打印在一行中，因此在显示宽表时很有帮助。 | -              |

<div id="command-line-options-execution-details">
  ### 执行细节
</div>

| 选项                               | 说明                                                                                                                                                               | 默认值                              |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `--enable-progress-table-toggle` | 启用通过按控制键 (空格) 切换进度表的功能。仅适用于已启用进度表打印的交互模式。                                                                                                                        | `enabled`                        |
| `--hardware-utilization`         | 在进度条中打印硬件利用率信息。                                                                                                                                                  | -                                |
| `--memory-usage`                 | 如果指定，则在非交互模式下将内存使用情况打印到 `stderr`。 <br /><br />可选值： <br />• `none` - 不打印内存使用情况 <br />• `default` - 打印字节数 <br />• `readable` - 以易读格式打印内存使用情况                       | -                                |
| `--print-profile-events`         | 打印 `ProfileEvents` 数据包。                                                                                                                                          | -                                |
| `--progress`                     | 打印查询执行进度。 <br /><br />可选值： <br />• `tty\|on\|1\|true\|yes` - 在交互模式下输出到终端 <br />• `err` - 在非交互模式下输出到 `stderr` <br />• `off\|0\|false\|no` - 禁用进度打印                | 交互模式下为 `tty`，非交互 (批次) 模式下为 `off` |
| `--progress-table`               | 在查询执行期间打印一个会随指标变化而更新的进度表。 <br /><br />可选值： <br />• `tty\|on\|1\|true\|yes` - 在交互模式下输出到终端 <br />• `err` - 在非交互模式下输出到 `stderr` <br />• `off\|0\|false\|no` - 禁用进度表 | 交互模式下为 `tty`，非交互 (批次) 模式下为 `off` |
| `--stacktrace`                   | 打印异常的堆栈跟踪。                                                                                                                                                       | -                                |
| `-t [ --time ]`                  | 在非交互模式下将查询执行时间打印到 `stderr` (用于性能测试) 。                                                                                                                            | -                                |