2. ClickHouse客户端连接与基础查询操作
两种连接方式的任务分工
clickhouse-client 是原生 TCP 协议客户端，默认端口 9000，返回带列对齐的表格文本，适合交互式探索；HTTP 接口默认端口 8123，返回以 Tab 分隔的纯文本或 JSON/JSONEachRow 等结构化格式，适合脚本、程序与管道处理。两者执行的是同一套 SQL，但传输协议、认证参数和结果呈现方式不同。
clickhouse-client 连接与基础查询
在已启动 ClickHouse 服务的机器上，直接执行以下命令进入交互模式：
clickhouse-client --host 127.0.0.1 --port 9000 --user default --password ''进入交互界面后，依次执行三类基础语句，观察返回格式：
-- 1. 查看当前可用的数据库
SHOW DATABASES;
-- 2. 查看某张表的字段结构
DESCRIBE TABLE system.numbers;
-- 3. 执行简单 SELECT
SELECT number, number * 2 AS double_num
FROM system.numbers
LIMIT 5;clickhouse-client 默认以 PrettyCompact 格式输出，列名居中、列宽自适应，适合人工核对字段与数据。若需脚本化处理，可在命令后追加 --format TabSeparated 或 --format JSONEachRow，此时输出变为纯文本或逐行 JSON，不再有表格边框。
HTTP 接口连接与基础查询
HTTP 接口通过 URL 参数传递 SQL，默认端口 8123。以下命令使用 curl 执行与上面相同的三类语句：
# 1. SHOW DATABASES
curl 'http://127.0.0.1:8123/?query=SHOW%20DATABASES'
# 2. DESCRIBE TABLE
curl 'http://127.0.0.1:8123/?query=DESCRIBE%20TABLE%20system.numbers'
# 3. SELECT，指定 JSONEachRow 格式
curl 'http://127.0.0.1:8123/?query=SELECT%20number,%20number*2%20AS%20double_num%20FROM%20system.numbers%20LIMIT%205%20FORMAT%20JSONEachRow'HTTP 接口默认返回 TabSeparated 格式，每行一条记录，字段之间用 Tab 分隔，无表头。若在 SQL 末尾显式指定 FORMAT JSONEachRow，则每行返回一个 JSON 对象，字段名与值成对出现，便于程序解析。若指定 FORMAT JSON，则返回包含 meta 和 data 两部分的完整 JSON 结构。
两种方式返回格式对比
| 对比项 | clickhouse-client | HTTP 接口 |
|---|---|---|
| 默认端口 | 9000（TCP） | 8123（HTTP） |
| 默认返回格式 | PrettyCompact（表格对齐） | TabSeparated（无表头） |
| 列名是否显示 | 显示，居中加分隔线 | 默认不显示，需 FORMAT 指定 |
| 适合场景 | 交互式探索、人工核对 | 脚本、程序、管道处理 |
| 指定 JSON 输出 | --format JSONEachRow | SQL 末尾加 FORMAT JSONEachRow |
| 认证方式 | --user / --password 参数 | URL 参数 user / password 或 X-ClickHouse-User 头 |
若 HTTP 接口返回
Code: 516. Authentication failed，说明默认用户未设置密码或密码不匹配。可在 URL 中追加 &user=default&password=你的密码，或在服务端配置中确认 users.xml 的密码设置。使用 curl 传递含空格或特殊字符的 SQL 时，必须进行 URL 编码（空格转为 %20，单引号转为 %27），否则服务端会解析失败。也可使用
--data-binary 方式将 SQL 放在请求体中，避免手动编码。快速验证清单
- clickhouse-client 能进入交互界面，执行
SELECT 1返回一行一列。 - HTTP 接口执行
SELECT 1返回1，无多余字符。 - 同一张表分别用两种方式执行
DESCRIBE，字段名与类型一致。 - HTTP 接口指定
FORMAT JSONEachRow后，每行输出为合法 JSON 对象。 - clickhouse-client 指定
--format TabSeparated后，输出与 HTTP 默认格式一致。