---

name: clickhouse-database description: "ClickHouse 資料庫操作技能。通過 clickhouse-client CLI 連線資料庫，執行 SELECT 查詢、INSERT/UPDATE/DELETE 增刪改、批次 SQL 執行、資料庫/表管理、JSON 格式輸出。適用場景：大數據查詢、統計分析、資料匯入匯出、資料庫巡檢、表結構檢視、遠端連線、生產環境除錯。觸發關鍵詞：ClickHouse、大數據查詢、SQL 語句執行、連線ClickHouse、查表、資料增刪改、clickhouse jdbc、查看錶結構、表字段分析、檢視索引、EXPLAIN 查詢分析。" license: "Copyright © 2026 少煊（年少有為，名聲煊赫）429668385@qq.com. All rights reserved."

---

ClickHouse Database Skill

Use the clickhouse-client CLI to connect to and interact with ClickHouse databases. Use the -q flag to execute SQL statements and combine with --format options to produce clean output suitable for processing. Pipe the result to jq for reliable JSON formatting.

快速使用場景

場景 1: 查詢資料（最常用）

clickhouse-client -h <host> -u <user> -d <db> -q "SELECT * FROM users LIMIT 10;" --format=JSONEachRow | jq -s '.'

場景 2: 查看錶結構

clickhouse-client -h <host> -u <user> -d <db> -q "DESCRIBE TABLE users;" --format=TSV 2>/dev/null

場景 3: 插入/更新/刪除資料

# 插入
clickhouse-client -h <host> -u <user> -d <db> -q "INSERT INTO users (name, email) VALUES ('Test', 'test@example.com');" 2>/dev/null

# 更新（需表引擎支援，如 MergeTree 家族）
clickhouse-client -h <host> -u <user> -d <db> -q "ALTER TABLE users UPDATE status=1 WHERE id=1;" 2>/dev/null

# 刪除
clickhouse-client -h <host> -u <user> -d <db> -q "ALTER TABLE users DELETE WHERE id=1;" 2>/dev/null

場景 4: 統計資料報表

clickhouse-client -h <host> -u <user> -d <db> -q "SELECT COUNT(*) as total, SUM(amount) as revenue FROM orders WHERE toDate(create_time)=today();" --format=JSONEachRow | jq -s '.'

場景 5: 匯出資料到檔案

clickhouse-client -h <host> -u <user> -d <db> -q "SELECT * FROM users FORMAT CSV" > /tmp/users.csv 2>/dev/null

場景 6: 執行 SQL 指令碼檔案

clickhouse-client -h <host> -u <user> -d <db> --multiquery < script.sql 2>/dev/null

資料庫連線

基礎連線

clickhouse-client -h <hostname> --port <port> -u <username> -d <database-name>

示例 (連線本地資料庫):

CLICKHOUSE_PASSWORD=yourpassword clickhouse-client -h 127.0.0.1 -u app_user -d app_db

從 JDBC URL 解析連線引數

使用者可能提供 JDBC URL 格式：jdbc:clickhouse://host:port/database，需要解析為 clickhouse-client 引數：

jdbc:clickhouse://nexus.syrinxchina.com:8123/test3
  → -h nexus.syrinxchina.com --port 8123 -d test3

# 示例：從 JDBC URL 構建連線
JDBC_URL="jdbc:clickhouse://nexus.syrinxchina.com:8123/test3"
HOST=$(echo $JDBC_URL | sed -n 's/.*:\/\/\([^:]*\):\([0-9]*\)\/\(.*\)/\1/p')
PORT=$(echo $JDBC_URL | sed -n 's/.*:\/\/\([^:]*\):\([0-9]*\)\/\(.*\)/\2/p')
DB=$(echo $JDBC_URL | sed -n 's/.*:\/\/\([^:]*\):\([0-9]*\)\/\(.*\)/\3/p')
clickhouse-client -h "$HOST" --port "$PORT" -u root -d "$DB"

連線參數列

Option	Description
-h / --host	Hostname (default: localhost)
--port	TCP port (default: 9000, HTTP port: 8123)
-u / --user	Username (default: default)
--password	Password (default: empty)
-d / --database	Default database (default: default)
-q / --query	Execute query and exit
--format	Output format (TSV/CSV/JSON/JSONEachRow etc.)
--multiquery	Allow multiple queries in one command
--secure	Use SSL/TLS connection
--connect-timeout	Connection timeout (seconds)
--send-timeout	Send data timeout (seconds)
--receive-timeout	Receive data timeout (seconds)

連線示例 (完整引數):

CLICKHOUSE_PASSWORD=password clickhouse-client -h 192.168.1.100 --port 9000 -u admin -d mydb --secure --connect-timeout=10 --format=JSONEachRow

使用配置檔案

建立 ~/.clickhouse-client/config.xml 簡化頻繁連線：

<config>
  <host>127.0.0.1</host>
  <port>9000</port>
  <user>app_user</user>
  <password>yourpassword</password>
  <database>app_db</database>
  <secure>0</secure>
</config>

clickhouse-client --config ~/.clickhouse-client/config.xml -q "SELECT 1;" --format=JSONEachRow

資料操作

查詢 (SELECT)

clickhouse-client -h <host> -u <user> -d <db> -q "SELECT * FROM your_table LIMIT 5;" --format=JSONEachRow | jq -s '.'

推薦格式化模式: - --format=JSONEachRow：每行一個 JSON 物件，適合多行結果 - --format=JSON：單個 JSON 物件包裹所有結果 - --format=TSV：製表符分隔，適合簡單輸出

插入 (INSERT)

clickhouse-client -h <host> -u <user> -d <db> -q "INSERT INTO users (name, email) VALUES ('New User', 'new@example.com');" 2>/dev/null

更新 (ALTER UPDATE)

clickhouse-client -h <host> -u <user> -d <db> -q "ALTER TABLE users UPDATE status = 'active' WHERE signup_date < '2026-01-01';" 2>/dev/null

刪除 (ALTER DELETE)

clickhouse-client -h <host> -u <user> -d <db> -q "ALTER TABLE sessions DELETE WHERE last_activity < subtractDays(now(), 30);" 2>/dev/null

高階查詢與 JSON 輸出

統計摘要查詢

clickhouse-client -h <host> -u <user> -d <db> -q "
SELECT JSON_OBJECT(
  'total_users', (SELECT COUNT(*) FROM users),
  'active_users', (SELECT COUNT(*) FROM users WHERE status = 'active'),
  'avg_posts', (SELECT AVG(post_count) FROM user_stats)
) AS report;
" --format=JSON | jq .

通用 JSON 輸出模式

想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

單行結果：

clickhouse-client ... -q "SELECT JSON_OBJECT('key1', column1, 'key2', column2) FROM ..." --format=JSON | jq .

多行結果：

clickhouse-client ... -q "SELECT id, name FROM users LIMIT 5" --format=JSONEachRow | jq -s '.'

批次執行 SQL 檔案

clickhouse-client -h <host> -u <user> -d <db> --multiquery < script.sql 2>/dev/null

批次匯入 CSV：

clickhouse-client -h <host> -u <user> -d <db> -q "INSERT INTO my_table FORMAT CSV" < data.csv 2>/dev/null

錯誤處理

常見錯誤碼

Error Code	Meaning	Solution
516	Authentication failed	檢查使用者名稱/密碼是否正確
81	Unknown database	檢查資料庫名是否存在
210	Can't connect to ClickHouse	檢查 ClickHouse 服務是否啟動，埠是否開放
60	Table doesn't exist	檢查表名拼寫是否正確

超時配置

clickhouse-client -h <host> -u <user> -d <db> --connect-timeout=5 --send-timeout=30 --receive-timeout=30 -q "SELECT * FROM large_table;" --format=TSV

連線測試模式

clickhouse-client -h <host> -u <user> -d <db> -q "SELECT 1 AS connected;" --format=TSV 2>&1 | grep -q "connected" && echo "連線成功" || echo "連線失敗"

資料庫與表操作

建立資料庫

clickhouse-client -h <host> -u <user> -q "CREATE DATABASE IF NOT EXISTS new_db ENGINE = Atomic;" --format=TSV

列出所有資料庫

clickhouse-client -h <host> -u <user> -q "SHOW DATABASES;" --format=TSV

列出表

clickhouse-client -h <host> -u <user> -d <db> -q "SHOW TABLES;" --format=TSV

查看錶結構

clickhouse-client -h <host> -u <user> -d <db> -q "DESCRIBE TABLE users;" --format=TSV

檢視索引

clickhouse-client -h <host> -u <user> -d <db> -q "SHOW INDEXES FROM users;" --format=TSV

檢視建表語句

clickhouse-client -h <host> -u <user> -d <db> -q "SHOW CREATE TABLE users;" --format=TSV

DESCRIBE TABLE 詳解

檢視單表結構

clickhouse-client -h <host> -u <user> -d <db> -q "DESCRIBE TABLE users;" --format=TSV

輸出欄位說明：

欄位	說明
name	列名
type	資料型別（String、Int64、DateTime 等）
default_type	預設值型別
default_expression	預設值表示式
comment	欄位註釋
codec_expression	壓縮演算法
ttl_expression	TTL 表示式

格式化輸出為 JSON

clickhouse-client -h <host> -u <user> -d <db> -q "
SELECT JSON_ARRAYAGG(JSON_OBJECT(
  'column', name,
  'type', type,
  'default_type', default_type,
  'default_value', default_expression,
  'comment', comment,
  'ttl', ttl_expression
)) AS columns
FROM system.columns
WHERE database = '<database>' AND table = '<table>'
ORDER BY position;" --format=JSON | jq .

快速檢視主鍵和分割槽鍵

clickhouse-client -h <host> -u <user> -d <db> -q "
SELECT name, type, is_in_primary_key, is_in_partition_key
FROM system.columns
WHERE database = '<database>'
  AND table = '<table>'
  AND (is_in_primary_key = 1 OR is_in_partition_key = 1)
ORDER BY is_in_primary_key DESC, position;" --format=JSONEachRow | jq -s '.'

EXPLAIN 查詢分析（重要！）

分析 SELECT 查詢執行計劃：

clickhouse-client -h <host> -u <user> -d <db> -q "EXPLAIN SELECT * FROM users WHERE phone = '13800138000';" --format=JSONEachRow | jq -s '.'

輸出關鍵欄位說明：

欄位	說明
Expression	表示式計算
Filter	過濾條件
ReadFromStorage	儲存讀取方式
PrimaryKey	主鍵使用情況
Partition	分割槽過濾情況
Files	涉及檔案數
Rows	預計掃描行數（越小越好）

最佳化要點： - 確認分割槽鍵被有效使用 - 避免全表掃描（Full scan） - 檢查主鍵是否命中

EXPLAIN ANALYZE（ClickHouse 21.1+）

clickhouse-client -h <host> -u <user> -d <db> -q "EXPLAIN ANALYZE SELECT * FROM users WHERE phone = '13800138000';" --format=JSONEachRow | jq -s '.'

比 EXPLAIN 更詳細，包含實際執行時間、實際掃描行數和執行步驟耗時。

查看錶大小和行數

clickhouse-client -h <host> -u <user> -d <db> -q "
SELECT
  table AS table_name,
  total_rows AS rows,
  formatReadableSize(total_bytes) AS total_size,
  formatReadableSize(data_bytes) AS data_size,
  formatReadableSize(index_bytes) AS index_size
FROM system.tables
WHERE database = '<database>'
ORDER BY total_bytes DESC;" --format=JSONEachRow | jq -s '.'

檢視資料庫中所有表的基本資訊

clickhouse-client -h <host> -u <user> -d <db> -q "
SELECT
  name AS table,
  engine AS table_engine,
  total_rows AS rows,
  formatReadableSize(total_bytes) AS size,
  comment AS table_comment
FROM system.tables
WHERE database = '<database>'
  AND engine NOT LIKE '%View%'
ORDER BY total_bytes DESC;" --format=JSONEachRow | jq -s '.'

環境變數配置

export CLICKHOUSE_PASSWORD="yourpassword"
export CLICKHOUSE_HOST="127.0.0.1"
export CLICKHOUSE_USER="app_user"
export CLICKHOUSE_DB="app_db"

clickhouse-client -h "$CLICKHOUSE_HOST" -u "$CLICKHOUSE_USER" -d "$CLICKHOUSE_DB" --password="$CLICKHOUSE_PASSWORD" -q "SELECT 1;" --format=JSONEachRow

完整示例指令碼

#!/bin/bash
# 查詢使用者統計資料（帶錯誤處理）

DB_HOST="${CLICKHOUSE_HOST:-127.0.0.1}"
DB_USER="${CLICKHOUSE_USER:-app_user}"
DB_PASS="${CLICKHOUSE_PASSWORD:-}"
DB_NAME="${CLICKHOUSE_DB:-app_db}"

QUERY="
SELECT JSON_OBJECT(
  'timestamp', now(),
  'summary', JSON_OBJECT(
    'total_users', (SELECT COUNT(*) FROM users),
    'active_users', (SELECT COUNT(*) FROM users WHERE status = 'active'),
    'new_today', (SELECT COUNT(*) FROM users WHERE toDate(created_at) = today())
  )
) AS report;
"

clickhouse-client -h "$DB_HOST" -u "$DB_USER" --password="$DB_PASS" -d "$DB_NAME" -q "$QUERY" --format=JSON 2>&1 | jq .

安全建議

1. 禁止在命令列中直接寫密碼（程序列表可見）
2. 使用 CLICKHOUSE_PASSWORD 環境變數或配置檔案
3. 生產環境強制使用 SSL (--secure 選項)
4. 配置檔案許可權設定為 chmod 600 ~/.clickhouse-client/config.xml
5. 查詢操作使用只讀賬號
6. 避免使用預設埠和預設使用者名稱/密碼

重要提示: 使用 --format 引數指定輸出格式（如 TSV/JSON/JSONEachRow）確保 clickhouse-client 輸出純淨資料，是生成有效 JSON 的前提。