Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

clickhouse-local

View as MarkdownEdit this pageReport an issueSet up docs MCP

何时使用 clickhouse-local，而不是 ClickHouse

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

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

请阅读下方文档，了解 clickhouse-local 的示例用例，例如查询本地文件或读取 S3 中的 Parquet 文件。

下载 clickhouse-local

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

curl https://clickhouse.com/ | sh

使用 SQL 查询文件中的数据

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

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

./clickhouse local -q "SELECT * FROM 'reviews.tsv'"

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

./clickhouse local -q "SELECT * FROM file('reviews.tsv')"

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

./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"

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

./clickhouse local -q "DESCRIBE file('reviews.tsv')"

数据不必位于本地：可使用 URL 替代文件名，URL 协议会选择相应的表引擎 (http:// 和 https:// 的读取方式与 url 函数相同，s3:// 与 s3 函数相同，file:// 与 file 函数相同) ：

./clickhouse local -q "SELECT * FROM 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv' LIMIT 3"
./clickhouse local -q "SELECT count() FROM 's3://clickhouse-public-datasets/hits_compatible/athena_partitioned/hits_1.parquet'"
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)

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

./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"
Monopoly Junior Board Game    5

查询 AWS S3 中 Parquet 文件的数据

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

./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

文件中有 270 万行：

2772030

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

./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"
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)

来看看哪些街区最贵：

./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"
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    ██████████████▋

格式转换

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

$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv

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

$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv

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

$ clickhouse-local --copy < data.json > data.csv

用法

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

基本用法 (Linux) ：

$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

基本用法 (Mac) ：

$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

参数：

  • -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 会将其关闭；客户端的 /-commands 是静态列表，只要启用 --hints 和 --highlight 就会持续显示提示。即使关闭提示，Tab 也可补全 /-commands。默认启用。
  • --verbose — 输出更多查询执行细节。
  • --logger.console — 输出到控制台。
  • --logger.log — 日志文件名。
  • --logger.level — 日志级别。
  • --ignore-error — 查询失败时不中止处理。
  • -c, --config-file — 配置文件路径，其格式与 ClickHouse 服务器 相同；默认配置为空。
  • --no-system-tables — 不加载系统表。
  • --help — clickhouse-local 的参数参考。
  • -V, --version — 打印版本信息并退出。

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

命令

LS 命令

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

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

Querysql
ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC
Responsetext
┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

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

./clickhouse-local -q ls
Responsetext
file1.csv
file2.json
file3.xml

CLEAR 命令

清除终端屏幕 (类似于 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：

./clickhouse-local -q clear

示例

Querybash
$ 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

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

Querybash
$ 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 表函数 打开任意多个文件：

Querybash
$ 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：

Querybash
$ 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"
Responsetext
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 │
├──────────┼──────────┤
...

启动 TCP 和 HTTP 监听器

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

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

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。

HTTP 监听器会使用与默认 clickhouse-server 配置相同的宽松请求头响应 CORS 预检请求，因此 Web 应用程序无需额外配置即可从浏览器对其执行查询，包括从 file:// URL 打开的 Web UI，其源为 null。要对此进行限制，请在通过 --config-file 传入的配置文件中定义自己的 http_options_response 部分；这将完全替换默认设置。

相关内容

Navigation