第 2 章 · 客户端与基础 SQL

三个交互演示：① HTTP 接口模拟器 · ② FORMAT 全家桶预览 · ③ SYSTEM 命令速查卡

把 SQL 翻译成 curl 命令 → 看 HTTP 协议长啥样

HTTP 接口是 ClickHouse 的「万能粘合剂」：浏览器 / 任意语言 / Grafana / Postman 都能用。在下面文本框输入 SQL，自动生成 curl 命令，再点「▶ 执行」可在右侧看到模拟的响应：

点 ▶ 生成
服务端返回内容会显示在这里...
提示： 真实环境只需把 curl 命令复制到终端跑就能拿到结果。注意 GET 模式 URL 长度有限（一般 4KB），复杂 SQL 务必用 POST。

📚 HTTP 接口的常用参数 / 路径速查

路径 / 参数用途示例
/?query=...执行 SQL/?query=SELECT 1
/?database=...默认库/?database=learn_ck
/?default_format=...默认 FORMAT/?default_format=JSONEachRow
/?query_id=...指定 query_id（便于追查）/?query_id=q-2026
/?max_memory_usage=...临时覆盖内存上限/?max_memory_usage=10000000000
/ping健康检查curl /ping → Ok.
/replicas_status副本健康检查返回 OK / Lag
/metricsPrometheus 指标对接 Prometheus exporter
/play内置 Web SQL Playground浏览器打开 http://host:8123/play

同一份数据，6 种 FORMAT 输出长啥样

这是一段示例查询：SELECT country, count() AS pv, avg(bytes) AS avg_bytes FROM events GROUP BY country ORDER BY pv DESC LIMIT 3 在不同 FORMAT 下的输出：



    

      选型要点：
      • 人眼调试 → PrettyCompact / Vertical；
      • 跟 Excel / 旧系统对接 → CSVWithNames；
      • 流式管道 / Kafka / 灌数据 → JSONEachRow；
      • 跟 Spark / pandas 互通 → Parquet / Arrow；
      • 跨 ClickHouse 集群高速复制 → Native；
      • 直接贴博客 → Markdown。
    

  


  

    
📋 ClickHouse 70+ 种 FORMAT（仅列高频）

    

      
FORMAT输入输出典型场景

      
        
PrettyCompact—✅CLI 默认，人眼好看

        
Pretty—✅带边框表格，文档友好

        
TabSeparated (TSV)✅✅shell 管道

        
TabSeparatedWithNames✅✅带表头 TSV

        
CSV✅✅Excel / 老系统

        
CSVWithNames✅✅标准导出 / Pandas read_csv

        
JSON—✅含 meta + data + 统计

        
JSONEachRow✅✅流式 / Kafka / 灌数据

        
JSONCompactEachRow✅✅每行是数组而非对象，省字节

        
Parquet✅✅数据湖 / Spark / DuckDB

        
Arrow / ArrowStream✅✅pandas / DataFusion 互通

        
ORC✅✅Hive 生态

        
Avro✅✅Kafka schema registry

        
Native✅✅跨 CK 集群最高速复制

        
RowBinary✅✅极简二进制；clickhouse-driver 用

        
Vertical—✅列纵向；字段太多调试用

        
Markdown—✅直接贴 Markdown 文档

        
SQLInsert—✅导出成 INSERT 语句

      
    

  







  

    
SYSTEM 命令速查卡 —— 运维 / 调优必背

    
ClickHouse 提供了一套以 SYSTEM 开头的「运维操作 SQL」，对应 MySQL 的 FLUSH / RESET。按分类点击查看：