> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> 使用 clickhouse-local 在无需服务器的情况下处理数据指南

# clickhouse-local

<div id="when-to-use-clickhouse-local-vs-clickhouse">
  ## 何时使用 clickhouse-local，而不是 ClickHouse
</div>

`clickhouse-local` 是 ClickHouse 的一个易用版本，非常适合那些希望使用 SQL 快速处理本地和远程文件、又不想安装完整数据库服务器的开发者。借助 `clickhouse-local`，开发者可以直接在命令行中使用 SQL 命令 (采用 [ClickHouse SQL 方言](/docs/zh/reference/home)) ，从而以简单高效的方式使用 ClickHouse 的各项功能，而无需完整安装 ClickHouse。`clickhouse-local` 的一大优势在于，安装 [clickhouse-client](/docs/zh/concepts/features/tools-and-utilities/clickhouse-local) 时它就已随附安装。这意味着开发者无需经历复杂的安装流程，即可快速开始使用 `clickhouse-local`。

虽然 `clickhouse-local` 非常适合用于开发、测试和文件处理，但它并不适合为终端用户或应用程序提供服务。在这些场景中，建议使用开源版 [ClickHouse](/docs/zh/get-started/setup/install)。ClickHouse 是一个强大的 OLAP 数据库，专为处理大规模分析型工作负载而设计。它能够快速高效地处理大型数据集上的复杂查询，因此非常适合对高性能要求极高的生产环境。此外，ClickHouse 还提供复制、分片和高可用等丰富功能，这些功能对于扩展系统以处理大型数据集并为应用程序提供服务至关重要。如果你需要处理更大规模的数据集，或为终端用户或应用程序提供服务，我们建议使用开源 ClickHouse，而不是 `clickhouse-local`。

请阅读下方文档，了解 `clickhouse-local` 的示例用例，例如[查询本地文件](#query_data_in_file)或[读取 S3 中的 Parquet 文件](#query-data-in-a-parquet-file-in-aws-s3)。

<div id="download-clickhouse-local">
  ## 下载 clickhouse-local
</div>

`clickhouse-local` 使用与运行 ClickHouse 服务器 和 `clickhouse-client` 相同的 `clickhouse` 二进制文件执行。下载最新版本最简单的方法是使用以下命令：

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

<Note>
  你刚下载的二进制文件可以运行各种 ClickHouse 工具和实用工具。如果你想将 ClickHouse 作为数据库服务器运行，请参阅[快速入门](/docs/zh/get-started/setup/install)。
</Note>

<div id="query_data_in_file">
  ## 使用 SQL 查询文件中的数据
</div>

`clickhouse-local` 的一个常见用途是对文件执行临时查询：无需先将数据插入表中。`clickhouse-local` 可以将文件中的数据流式导入临时表，并执行你的 SQL。

如果文件与 `clickhouse-local` 位于同一台机器上，只需指定要加载的文件即可。下面的 `reviews.tsv` 文件包含部分 Amazon 产品评论样本：

```bash theme={null}
./clickhouse local -q "SELECT * FROM 'reviews.tsv'"
```

此命令是以下命令的简写：

```bash theme={null}
./clickhouse local -q "SELECT * FROM file('reviews.tsv')"
```

ClickHouse 会根据文件扩展名识别该文件使用的是制表符分隔格式。如果你需要显式指定格式，只需添加 [ClickHouse 众多输入格式之一](/docs/zh/reference/formats/index)：

```bash theme={null}
./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"
```

`file` 表函数 会创建一个表，你可以使用 `DESCRIBE` 查看推断出的 schema：

```bash theme={null}
./clickhouse local -q "DESCRIBE file('reviews.tsv')"
```

<Tip>
  允许在文件名中使用通配符 (参见[通配符替换](/docs/zh/reference/functions/table-functions/file#globs-in-path)) 。

  示例：

  ```bash theme={null}
  ./clickhouse local -q "SELECT * FROM 'reviews*.jsonl'"
  ./clickhouse local -q "SELECT * FROM 'review_?.csv'"
  ./clickhouse local -q "SELECT * FROM 'review_{1..3}.csv'"
  ```
</Tip>

```response theme={null}
marketplace    Nullable(String)
customer_id    Nullable(Int64)
review_id    Nullable(String)
product_id    Nullable(String)
product_parent    Nullable(Int64)
product_title    Nullable(String)
product_category    Nullable(String)
star_rating    Nullable(Int64)
helpful_votes    Nullable(Int64)
total_votes    Nullable(Int64)
vine    Nullable(String)
verified_purchase    Nullable(String)
review_headline    Nullable(String)
review_body    Nullable(String)
review_date    Nullable(Date)
```

我们来找出评分最高的产品：

```bash theme={null}
./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"
```

```response theme={null}
Monopoly Junior Board Game    5
```

<div id="query-data-in-a-parquet-file-in-aws-s3">
  ## 查询 AWS S3 中 Parquet 文件的数据
</div>

如果你在 S3 中有一个文件，可以使用 `clickhouse-local` 和 `s3` 表函数直接在原位置查询该文件 (无需先将数据插入 ClickHouse 表中) 。我们在一个公共 bucket 中有一个名为 `house_0.parquet` 的文件，其中包含英国已售房产的价格数据。让我们来看看它有多少行：

```bash theme={null}
./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"
```

文件中有 270 万行：

```response theme={null}
2772030
```

查看 ClickHouse 根据文件推断出的 schema 往往很有帮助：

```bash theme={null}
./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"
```

```response theme={null}
price    Nullable(Int64)
date    Nullable(UInt16)
postcode1    Nullable(String)
postcode2    Nullable(String)
type    Nullable(String)
is_new    Nullable(UInt8)
duration    Nullable(String)
addr1    Nullable(String)
addr2    Nullable(String)
street    Nullable(String)
locality    Nullable(String)
town    Nullable(String)
district    Nullable(String)
county    Nullable(String)
```

来看看哪些街区最贵：

```bash theme={null}
./clickhouse local -q "
SELECT
    town,
    district,
    count() AS c,
    round(avg(price)) AS price,
    bar(price, 0, 5000000, 100)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')
GROUP BY
    town,
    district
HAVING c >= 100
ORDER BY price DESC
LIMIT 10"
```

```response theme={null}
LONDON    CITY OF LONDON    886    2271305    █████████████████████████████████████████████▍
LEATHERHEAD    ELMBRIDGE    206    1176680    ███████████████████████▌
LONDON    CITY OF WESTMINSTER    12577    1108221    ██████████████████████▏
LONDON    KENSINGTON AND CHELSEA    8728    1094496    █████████████████████▉
HYTHE    FOLKESTONE AND HYTHE    130    1023980    ████████████████████▍
CHALFONT ST GILES    CHILTERN    113    835754    ████████████████▋
AMERSHAM    BUCKINGHAMSHIRE    113    799596    ███████████████▉
VIRGINIA WATER    RUNNYMEDE    356    789301    ███████████████▊
BARNET    ENFIELD    282    740514    ██████████████▊
NORTHWOOD    THREE RIVERS    184    731609    ██████████████▋
```

<Tip>
  当您准备好将文件数据插入 ClickHouse 时，请启动 ClickHouse 服务器，并将 `file` 和 `s3` 表函数的结果插入 `MergeTree` 表。更多详情，请参阅[快速入门](/docs/zh/get-started/setup/install)。
</Tip>

<div id="format-conversions">
  ## 格式转换
</div>

你可以使用 `clickhouse-local` 在不同格式之间进行数据转换。示例：

```bash theme={null}
$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv
```

可根据文件扩展名自动识别格式：

```bash theme={null}
$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv
```

作为简写，你也可以使用 `--copy` 参数这样写：

```bash theme={null}
$ clickhouse-local --copy < data.json > data.csv
```

<div id="usage">
  ## 用法
</div>

默认情况下，`clickhouse-local` 可以访问同一主机上 ClickHouse 服务器的数据，且不依赖服务器配置。它还支持通过 `--config-file` 参数加载服务器配置。对于临时数据，默认会创建一个唯一的临时数据目录。

基本用法 (Linux) ：

```bash theme={null}
$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"
```

基本用法 (Mac) ：

```bash theme={null}
$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"
```

<Note>
  也可通过 WSL2 在 Windows 上使用 `clickhouse-local`。
</Note>

参数：

* `-S`, `--structure` — 输入数据的表结构。
* `--input-format` — 输入格式，默认为 `TSV`。
* `-F`, `--file` — 数据路径，默认为 `stdin`。
* `-q`, `--query` — 要执行的查询，以 `;` 作为分隔符。`--query` 可以指定多次，例如 `--query "SELECT 1" --query "SELECT 2"`。不能与 `--queries-file` 同时使用。
* `--queries-file` - 包含待执行查询的文件路径。`--queries-file` 可以指定多次，例如 `--query queries1.sql --query queries2.sql`。不能与 `--query` 同时使用。
* `--multiquery, -n` – 指定后，可在 `--query` 选项后列出多个以分号分隔的查询。为方便起见，也可以省略 `--query`，直接在 `--multiquery` 后传入查询。
* `-N`, `--table` — 用于存放输出数据的表名，默认为 `table`。
* `-f`, `--format`, `--output-format` — 输出格式，默认为 `TSV`。
* `-d`, `--database` — 默认数据库，默认为 `_local`。
* `--stacktrace` — 发生异常时是否转储调试输出。
* `--echo [ <bool> ]` — 在执行前打印每个查询。接受可选的布尔值。在交互模式中默认启用，在批次模式中默认禁用。注意：由于 `--echo` 现在接受可选值，紧跟在单独的 `--echo` 后面的查询位置参数会被当作它的值；请改用 `--echo --query "..."`、`--echo -q "..."`、`--echo=false`，或通过管道传入 `stdin`。
* `--echo-formatted [ <bool> ]` — 格式化回显的查询。接受可选的布尔值。在交互模式中默认启用，在批次模式中默认禁用。
* `--echo-query-id [ <bool> ]` — 在执行前打印 `query_id`。接受可选的布尔值。在交互模式中默认启用，在批次模式中默认禁用。
* `--echo-query-separator <string>` — 在格式化回显的查询前打印此分隔符 (需要 `--echo-formatted`) ，这样更容易区分输入的查询与其重新格式化后的回显。默认为空 (禁用) 。
* `--highlight`, `--hilite` `<bool>` — 切换命令提示符和回显查询的语法高亮。默认启用。仅在输出到终端时应用高亮。
* `--hints <bool>` — 当光标位于输入末尾时，显示输入时自动补全提示 (内联 "ghost" 文本) ，给出最佳匹配建议。可使用 Up/Down (或 Ctrl-Up/Ctrl-Down) 浏览提示；使用 Tab 或 Right 接受内联提示；`Enter` 仅在已显式选中某个提示后才会接受该提示，否则会运行查询；`Tab` 还会打开经典补全列表。需要启用 `--highlight` (提示需要颜色) 以及建议机制 (因此 `--disable_suggestion` 也会将其关闭) 。默认启用。
* `--verbose` — 输出更多查询执行细节。
* `--logger.console` — 输出到控制台。
* `--logger.log` — 日志文件名。
* `--logger.level` — 日志级别。
* `--ignore-error` — 查询失败时不中止处理。
* `-c`, `--config-file` — 配置文件路径，其格式与 ClickHouse 服务器 相同；默认配置为空。
* `--no-system-tables` — 不加载系统表。
* `--help` — `clickhouse-local` 的参数参考。
* `-V`, `--version` — 打印版本信息并退出。

此外，每个 ClickHouse 配置变量也都有对应的参数，这些参数通常比 `--config-file` 更常用。

<div id="commands">
  ## 命令
</div>

<div id="ls-command">
  ### LS 命令
</div>

列出当前工作目录中 clickhouse-local 可访问的所有文件。

你可以在交互模式下这样运行：

```sql title="Query" theme={null}
ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC
```

```text title="Response" theme={null}
┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘
```

你也可以通过 `-q` 参数将其作为查询执行：

```sh theme={null}
./clickhouse-local -q ls
```

```text title="Response" theme={null}
file1.csv
file2.json
file3.xml
```

<div id="clear-command">
  ### CLEAR 命令
</div>

清除终端屏幕 (类似于 Linux 上的 `clear` 命令，或许多终端中的 Ctrl+L) 。这是一个客户端侧操作：不会发送到 SQL 引擎。

在 `clickhouse-local` 中，该元命令会在 **交互式** 模式以及 **`-q`** 和 **`--queries-file`** 输入中被识别 (与 `-q` 走相同的客户端路径，思路上类似 `ls`) ，因此单独输入 `clear` 不会产生 `UNKNOWN_IDENTIFIER` 错误。远程 **`clickhouse-client --queries-file`** 的行为保持不变：文件内容仍然只会作为 SQL 执行 (不支持文本级元命令) 。

在 `clickhouse-client` 中，它仅在 **交互式** 模式下可被识别。使用 **`-q`** 或查询文件时，`clear` 仍会按 SQL 解析，因此自动化场景会保持之前的报错行为，而不会让拼写错误变成无提示的空操作。

支持的形式：`clear`、`CLEAR`、`/clear` (可选的末尾 `;` 会被忽略) 。如果标准输出不是终端 (例如通过管道传递输出时) ，该元命令在可识别的情况下仍会被接受，但不会输出控制序列。

对于 `clickhouse-local` 和 `-q`：

```sh theme={null}
./clickhouse-local -q clear
```

<div id="examples">
  ## 示例
</div>

```bash title="Query" theme={null}
$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Read 2 rows, 32.00 B in 0.000 sec., 5182 rows/sec., 80.97 KiB/sec.
1   2
3   4
```

前一个示例与以下内容相同：

```bash title="Query" theme={null}
$ echo -e "1,2\n3,4" | clickhouse-local -n --query "
    CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin);
    SELECT a, b FROM table;
    DROP TABLE table;"
Read 2 rows, 32.00 B in 0.000 sec., 4987 rows/sec., 77.93 KiB/sec.
1   2
3   4
```

你无需使用 `stdin` 或 `--file` 参数，也可以通过 [`file` 表函数](/docs/zh/reference/functions/table-functions/file) 打开任意多个文件：

```bash title="Query" theme={null}
$ echo 1 | tee 1.tsv
1

$ echo 2 | tee 2.tsv
2

$ clickhouse-local --query "
    select * from file('1.tsv', TSV, 'a int') t1
    cross join file('2.tsv', TSV, 'b int') t2"
1    2
```

现在让我们输出每个 Unix 用户对应的 memory user：

```bash title="Query" theme={null}
$ ps aux | tail -n +2 | awk '{ printf("%s\t%s\n", $1, $4) }' \
    | clickhouse-local --structure "user String, mem Float64" \
        --query "SELECT user, round(sum(mem), 2) as memTotal
            FROM table GROUP BY user ORDER BY memTotal DESC FORMAT Pretty"
```

```text title="Response" theme={null}
Read 186 rows, 4.15 KiB in 0.035 sec., 5302 rows/sec., 118.34 KiB/sec.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...
```

<div id="starting-listeners">
  ## 启动 TCP 和 HTTP 监听器
</div>

`clickhouse-local` 可以转换为一个轻量级服务器，用于接受 TCP (native protocol) 和 HTTP 连接。当你希望让其他 ClickHouse 工具或应用程序访问正在运行的 `clickhouse-local` 实例中的数据库和表时，这会很有用。请注意，每个传入连接都会获得各自独立的会话：交互式 `clickhouse-local` 会话中的临时表和会话级设置对外部连接不可见。

使用 `SYSTEM START LISTEN` 打开监听器，使用 `SYSTEM STOP LISTEN` 关闭它：

```bash theme={null}
clickhouse-local \
    --listen_host 127.0.0.1 \
    --tcp_port 9000 \
    --http_port 8123 \
    --query "
        SYSTEM START LISTEN TCP;
        SYSTEM START LISTEN HTTP;
        SELECT * FROM url('http://127.0.0.1:8123/?query=SELECT+42', LineAsString);
        SYSTEM STOP LISTEN TCP;
        SYSTEM STOP LISTEN HTTP;
    "
```

`--listen_host`、`--tcp_port` 和 `--http_port` 选项用于配置绑定地址和端口。默认端口为：TCP 使用 `9000`，HTTP 使用 `8123`。

<Warning>
  **安全**

  默认情况下，`clickhouse-local` 使用临时用户配置运行，因此它开启的任何监听都不进行身份验证。除非你已通过将 `users_config` 设置指向自定义 `users.xml` (例如通过 `--config-file`) 显式配置用户和访问控制，否则请绑定到回环地址 (`127.0.0.1` 或 `::1`) 。如果在未启用身份验证的情况下监听非回环地址，任何能够访问所选端口的人都可以访问本地实例的数据。
</Warning>

<div id="related-content-1">
  ## 相关内容
</div>

* [使用 clickhouse-local 从本地文件中提取、转换并查询数据](https://clickhouse.com/blog/extracting-converting-querying-local-files-with-sql-clickhouse-local)
* [将数据导入 ClickHouse - 第 1 部分](https://clickhouse.com/blog/getting-data-into-clickhouse-part-1)
* [探索海量真实世界数据集：ClickHouse 中 100 多年的天气记录](https://clickhouse.com/blog/real-world-data-noaa-climate-data)
* 博客：[使用 clickhouse-local 从本地文件中提取、转换并查询数据](https://clickhouse.com/blog/extracting-converting-querying-local-files-with-sql-clickhouse-local)