Hologres：Hologres AI Plugins 使用指南

適用情境

• 在終端或指令碼中批量管理 Hologres 執行個體的表、動態表、Schema 與許可權，替代控制台逐項點擊。

• 在 CI/CD 流水線中自動執行資料匯入、動態表重新整理、Schema 變更，並通過 JSON 輸出對接監控系統。

• 在 Claude Code、Cursor 等 AI 工具中接入 Hologres，使用自然語言完成 SQL 最佳化、慢查詢分析、UV 去重方案設計等情境。

• 通過 CLI 調用 Hologres 的 AI 函數，產生文本、映像、視頻內容並直接落到 Volume 關聯的 OSS 路徑。

與其他工具的關係

方式一：一鍵安裝指令碼（推薦）

執行以下命令完成自動安裝：

curl -sSf https://raw.githubusercontent.com/aliyun/hologres-ai-plugins/master/hologres-cli/install.sh | sh

安裝完成後，重新載入 shell 以使 PATH 生效：

source ~/.bashrc   # bash 使用者
source ~/.zshrc    # zsh 使用者

方式二：pip 安裝

在已配置好的 Python 3.11+ 環境中，執行：

pip install hologres-cli

方式三：uv 安裝

使用 uv tool 全域安裝，CLI 與專案依賴完全隔離：

uv tool install hologres-cli

驗證安裝

執行以下命令查看 CLI 版本，輸出版本號碼即表示安裝成功：

hologres --version

互動式設定精靈

首次使用時執行以下命令啟動嚮導：

hologres config

嚮導按順序提示輸入以下 9 項參數：

1. Profile 名稱：標識一組串連配置，例如 default、dev、prod。命名僅允許字母、數字、底線和連字號，區分大小寫；同名 Profile 會被覆蓋。

2. Region：執行個體所在地區 ID，例如 cn-hangzhou、cn-shanghai、cn-beijing。

3. Instance ID：Hologres 執行個體 ID，格式為 hgprecn-cn-xxx，可在 Hologres 控制台執行個體詳情頁擷取。

4. 網路類型：從 internet（公網）、intranet（傳統網路內網）、vpc（專用網路）中選擇，詳見下方網路類型選型說明。

5. 認證方式：basic（資料庫帳號使用者名稱/密碼）或 ram（RAM 使用者 AccessKey）。

6. 資料庫名：執行個體下的目標資料庫名稱。

7. Warehouse：目標計算群組名稱。

8. Endpoint：可選項。留空時 CLI 根據 Instance ID、Region 和網路類型自動拼接，詳見下方 Endpoint 自動拼接規則。

9. Port：預設 80，對應 Hologres 的 PG Wire 協議連接埠。VPC 與公網均使用此連接埠。如需啟用 SSL/TLS，需在 Endpoint 或專用參數中顯式聲明（詳見 Hologres 執行個體串連文檔）。

嚮導完成後，配置寫入 ~/.hologres/config.json。建議立即執行驗證：

hologres status

網路類型選型

網路類型決定了 CLI 如何拼接 Endpoint 與串連路徑，錯誤的選擇會導致連線逾時或網域名稱解析失敗。按以下規則選擇：

Profile 管理

配置完成後，使用以下命令查看、切換、修改 Profile：

# 列出所有 Profile
hologres config list

# 查看當前 Profile 詳情
hologres config show

# 切換 Profile
hologres config switch prod

# 直接設定配置項
hologres config set database my_new_db
hologres config set warehouse my_warehouse

# 擷取配置項
hologres config get database

# 刪除 Profile
hologres config delete old_profile --confirm

多環境切換

使用 --profile 參數指定本次命令使用的 Profile，無需先切換預設 Profile，適合在指令碼中並行操作多套環境：

hologres --profile dev status
hologres --profile staging sql run "SELECT 1"
hologres --profile prod schema tables

Endpoint 自動拼接規則

Endpoint 留空時，CLI 根據 instance_id、region_id 和網路類型自動拼接 Host：

檢查串連狀態

執行以下命令查看當前 Profile 是否能串連 Hologres：

hologres status

成功時返回類似如下結果：

{
  "ok": true,
  "data": {
    "connected": true,
    "version": "Hologres 2.2.0.x",
    "database": "my_db"
  }
}

串連失敗時 ok 欄位為 false，並返回 CONNECTION_ERROR 錯誤碼與原因描述，可據此排查網路、白名單或認證問題。

輸出格式

CLI 支援 4 種輸出格式，使用 -f 全域參數指定，預設輸出 JSON：

hologres -f json  schema tables    # JSON，預設格式，便於 Agent 與指令碼解析
hologres -f table schema tables    # 終端表格，便於人工查看
hologres -f csv   schema tables    # CSV，便於匯出二次處理
hologres -f jsonl schema tables    # JSON Lines，便於串流

查看執行個體與計算群組

hologres instance                     # 查看當前 profile 對應執行個體的版本與最大串連數
hologres warehouse                    # 列出所有計算群組
hologres warehouse default_warehouse  # 查看指定計算群組詳情

查看命令歷史

hologres history          # 查看最近的命令記錄
hologres history -n 50    # 查看最近 50 條

列出表

hologres table list                    # 列出當前資料庫下所有表
hologres table list --schema public    # 僅列出指定 schema 下的表
hologres table list -f table           # 以終端表格格式輸出

預設 JSON 輸出樣本：

{
  "ok": true,
  "data": [
    {"schema": "public", "name": "orders", "type": "table"},
    {"schema": "public", "name": "users",  "type": "table"}
  ]
}

查看錶結構

hologres table show public.orders        # 查看列定義、類型、主鍵、注釋
hologres table properties public.orders  # 查看錶屬性（儲存格式、分布鍵、TTL）
hologres table dump public.orders        # 匯出完整 DDL
hologres table size public.orders        # 查看錶儲存大小

建立表

建立列存表的樣本：

hologres table create --name public.orders \
  --columns "order_id BIGINT NOT NULL, user_id INT, amount DECIMAL(10,2), created_at TIMESTAMPTZ" \
  --primary-key order_id \
  --orientation column \
  --distribution-key order_id \
  --clustering-key "created_at:asc" \
  --ttl 7776000 \
  --dry-run

建立邏輯分區表的樣本（V3.1+）：

hologres table create --name public.logs \
  --columns "a TEXT, b INT, ds DATE NOT NULL" \
  --primary-key "b,ds" \
  --partition-by ds \
  --partition-mode logical \
  --orientation column \
  --distribution-key b \
  --partition-expiration-time "30 day" \
  --dry-run

修改表

hologres table alter my_table --add-column "age INT"
hologres table alter my_table --rename-column "old_col:new_col"
hologres table alter my_table --ttl 3600
hologres table alter my_table --dictionary-encoding-columns "a:on,b:auto"
hologres table alter my_table --partition-expiration-time "60 day"
hologres table alter my_table --ttl 3600 --dry-run   # 預覽產生的 SQL

刪除與清空表

hologres table drop my_table              # 預設僅預覽（dry-run）
hologres table drop my_table --confirm    # 真正刪除表
hologres table truncate my_table --confirm # 清空表資料但保留表結構

分區管理

hologres partition list --table my_table
hologres partition drop --table my_table --partition "2025-04-01" --confirm
hologres partition alter -t my_table --partition "ds=2025-03-16" --set "keep_alive=TRUE"

視圖管理

hologres view list
hologres view show analytics.daily_stats

建立動態表

基礎建立樣本：

hologres dt create -t my_dt \
  --freshness "10 minutes" \
  -q "SELECT col1, SUM(col2) FROM src GROUP BY col1"

使用增量重新整理和 Serverless 計算資源：

hologres dt create -t ads_report \
  --freshness "5 minutes" \
  --refresh-mode incremental \
  --computing-resource serverless \
  -q "SELECT region, SUM(amount) FROM orders GROUP BY region"

僅預覽產生的 SQL：

hologres dt create -t my_dt --freshness "10 minutes" -q "SELECT 1" --dry-run

查看動態表

hologres dt list                    # 列出所有動態表
hologres dt show public.my_dt       # 查看動態表屬性與重新整理狀態
hologres dt ddl public.my_dt        # 匯出 DDL
hologres dt lineage public.my_dt    # 查看血緣依賴
hologres dt storage public.my_dt    # 查看儲存大小
hologres dt state-size public.my_dt # 查看狀態表大小

修改、重新整理與刪除

hologres dt alter my_dt --freshness "30 minutes"
hologres dt refresh my_dt
hologres dt drop my_dt               # 預設僅預覽
hologres dt drop my_dt --confirm     # 真正刪除

V3.0 升級到 V3.1

將 V3.0 建立的動態表升級到 V3.1 格式：

hologres dt convert my_old_dt   # 升級單個動態表
hologres dt convert --all       # 批量升級當前資料庫下所有 V3.0 動態表

唯讀查詢

hologres sql run "SELECT * FROM orders LIMIT 10"
hologres sql run --with-schema "SELECT * FROM orders LIMIT 10"   # 輸出含列名與類型資訊
hologres sql run --no-limit-check "SELECT * FROM large_table"    # 禁用行數檢查

預設情況下，無 LIMIT 的 SELECT 返回行數超過 100 行會被安全護欄攔截，詳見本文「安全機制」章節的行數限制說明。如需繞過此限制，使用 --no-limit-check 參數。

寫操作

寫入類 SQL 必須顯式聲明 --write：

hologres sql run --write "INSERT INTO logs VALUES (1, 'test')"
hologres sql run --write "DELETE FROM logs WHERE created_at < '2024-01-01'"

查看執行計畫

hologres sql explain "SELECT * FROM orders WHERE status = 'active'"

使用前提

使用 AI 功能前必須完成以下兩步配置：

1. 註冊大模型：通過 hologres model create 將所選模型（如通義千問、通義萬相等）註冊到 Hologres 執行個體，註冊時提供模型類型、名稱與 API Key。詳見本文「模型管理」小節。

2. 配置 Volume：通過 hologres volume create 在 Hologres 中註冊一個指向 OSS Bucket 的 Volume，作為產生內容的儲存位置。詳見本文「Volume 儲存管理」章節。

建立 Volume 時推薦通過 RAM 角色（RoleArn）授權訪問 OSS，憑據請通過環境變數傳入，避免在命令列中明文寫出 AccessKey：

# 通過 RAM 角色授權（推薦）
hologres volume create my_vol \
  --endpoint oss-cn-hangzhou-internal.aliyuncs.com \
  --root oss://my-bucket/ai-output/ \
  --rolearn acs:ram::123456:role/AliyunHologresDefaultRole

# 如必須使用 AccessKey，請通過環境變數傳入，避免寫入程式碼
export HOLO_AK="$(security find-generic-password -s holo_ak -w)"
export HOLO_SK="$(security find-generic-password -s holo_sk -w)"
hologres volume create my_vol \
  --endpoint oss-cn-hangzhou-internal.aliyuncs.com \
  --root oss://my-bucket/ai-output/ \
  --access-key "$HOLO_AK" \
  --access-secret "$HOLO_SK"

文本產生

hologres ai gen "介紹一下 Hologres 的核心優勢"
hologres ai gen "寫一首關於資料的詩" --model qwen-max

映像產生

hologres ai image-gen "科技感資料倉儲概念圖" -o volume://my_vol/images
hologres ai image-gen "產品展示圖" --size "1280*720" -n 2 -o volume://my_vol/output
hologres ai image-gen "Q版風格" --reference-url volume://my_vol/ref.png -o volume://my_vol/output

視頻產生與編輯

# 文字轉視頻
hologres ai t2v "一隻貓在草地上奔跑" -o volume://my_vol/output

# 圖片轉視頻
hologres ai i2v "讓這張圖動起來" --img-url volume://my_vol/frame.png -o volume://my_vol/output

# 參考圖產生視頻
hologres ai r2v "女性在花園漫步" --reference-url volume://my_vol/girl.png -o volume://my_vol/output

# 視頻編輯
hologres ai video-edit "轉為動漫風格" --video volume://my_vol/input.mp4 -o volume://my_vol/output

常用命令

hologres volume list                                    # 列出所有 Volume
hologres volume list-files --volume my_vol              # 列出 Volume 內的檔案
hologres volume list-files --volume my_vol --prefix images/ --max-count 50
hologres volume upload-file --volume my_vol --local-file ./data.csv --target-file data/data.csv
hologres volume download-file --volume my_vol --file report.csv -d ./output
hologres volume view volume://my_vol/images/photo.png   # 在終端中預覽檔案
hologres volume delete-file --volume my_vol --file old.csv --confirm
hologres volume delete my_vol                           # 刪除 Volume 配置（不刪 OSS 資料）

網路類型

Volume 操作支援公網與內網兩種傳輸路徑，使用 --net 參數指定：

hologres volume list-files --volume my_vol --net internet   # 公網（預設）
hologres volume list-files --volume my_vol --net intranet   # 內網（ECS 與 VPC 內推薦）

第 1 層：行數限制

不帶 LIMIT 的 SELECT 預設最多返回 100 行，超過即返回 LIMIT_REQUIRED 錯誤。該限制用於防止誤操作拉取超大結果集。

行數上限為 CLI 內建預設值，需要繞過時通過 --no-limit-check 參數關閉。data export 與 data import 等批量命令不受此限制約束。

第 2 層：串連級唯讀

所有串連預設執行 SET default_transaction_read_only = ON，由資料庫引擎在事務層級拒絕寫入。即使 SQL 誤帶寫入語義，也無法落庫。

第 3 層：寫操作顯式授權

寫操作必須顯式授權才能執行：

未通過顯式授權的寫入返回 WRITE_GUARD_ERROR。

第 4 層：危險操作阻斷

不帶 WHERE 子句的 DELETE 與 UPDATE 直接返回 DANGEROUS_WRITE_BLOCKED，無法通過 --write 繞過，必須補充明確的過濾條件後重新執行。

第 5 層：Serverless 計算隔離

Agent 調用產生的 SQL 預設路由到獨立的 Serverless 算力池，與生產執行個體的常駐計算資源隔離，避免 AI 試探性查詢衝擊線上業務。

第 6 層：自適應執行（Adaptive Execution）

複雜 SQL 通過自適應執行機制分階段調度，按需擴充算力，避免單條查詢觸發 OOM。

敏感性資料自動脫敏

查詢返回結果中匹配以下欄位的列會自動脫敏：

如需關閉脫敏（例如在合規通過的營運情境下查看完整欄位），添加 --no-mask 參數：

hologres sql run --no-mask "SELECT * FROM users LIMIT 10"

憑據加密

資料庫密碼與 AccessKey 在寫入 ~/.hologres/config.json 之前使用 Fernet 演算法加密，加密金鑰儲存在 ~/.hologres/.cipher_key，檔案許可權為 0600。舊版明文配置自動相容並在下一次寫入時升級為加密格式。

錯誤碼

安裝方式

推薦使用一鍵安裝指令碼，自動完成下載、依賴安裝和互動式部署：

curl -sSf https://raw.githubusercontent.com/aliyun/hologres-ai-plugins/master/agent-skills/install.sh | sh

也可以使用 uvx 直接運行（無需提前安裝）：

uvx hologres-agent-skills

互動式安裝流程

安裝指令碼啟動後進入互動式選取器，按 3 步完成部署：

1. 選擇 AI 工具：從 Claude Code、Cursor、OpenAI Codex、GitHub Copilot、Qoder、Trae、OpenClaw、OpenCode 列表中選擇目標工具。使用方向鍵 ↑/↓ 移動游標，Enter 鍵確認選擇。

2. 選擇技能包：進入多選介面，使用空格鍵勾選或取消勾選技能包，使用方向鍵移動游標，使用 Enter 鍵完成選擇並繼續。如需中途退出，按 Esc 鍵返回上一步。

3. 自動部署：指令碼將所選技能包複製到對應 AI 工具的本地目錄，部署完成後輸出每個 Skill 的安裝路徑與版本資訊。

互動介面樣本：

? 選擇 AI 工具 (使用 ↑/↓ 鍵，Enter 確認):
  ❯ Claude Code
    Cursor
    OpenAI Codex
    GitHub Copilot
    Qoder
    Trae
    OpenClaw
    OpenCode

? 選擇要安裝的 Skills (空格鍵勾選，Enter 確認):
  [x] hologres-cli
  [x] hologres-query-optimizer
  [ ] hologres-slow-query-analysis
  [x] hologres-schema-generator
  [ ] hologres-privileges
  [ ] hologres-uv-compute
  [ ] hologres-bsi-profile-analysis
  [ ] hologres-ad-campaign

✔ 部署完成
  hologres-cli                 → ~/project/.claude/skills/hologres-cli
  hologres-query-optimizer     → ~/project/.claude/skills/hologres-query-optimizer
  hologres-schema-generator    → ~/project/.claude/skills/hologres-schema-generator

安裝路徑

不同 AI 工具的 Skills 預設安裝位置：

內建 8 個技能包

情境一：查詢最佳化

在 Claude Code 中輸入自然語言請求，Agent 調用 query-optimizer Skill 完成執行計畫分析與最佳化建議：

使用者: 這條 SQL 跑了 30 秒，幫我看看怎麼最佳化：
       SELECT region, SUM(amount)
       FROM orders
       WHERE created_at > '2025-01-01'
       GROUP BY region;

Agent 調用:
  $ hologres sql explain "SELECT region, SUM(amount) FROM orders \
      WHERE created_at > '2025-01-01' GROUP BY region"

CLI 返回（節選）:
  Seq Scan on orders  (cost=0..120000 rows=10000000)
    Filter: (created_at > '2025-01-01')
  Redistribution: HashRedistribution by region

Agent 總結:
  瓶頸一：Seq Scan 全表掃描，缺少 created_at 上的有效過濾路徑
  瓶頸二：按 region 重分布資料轉送量大
  最佳化建議:
    1. 將 created_at 設為聚簇鍵: ALTER TABLE orders SET clustering_key='created_at:asc'
    2. 將 region 設為分布鍵，避免 GROUP BY 重分布: ALTER TABLE orders SET distribution_key='region'
    3. 啟用結果緩衝: hologres guc set hg_cache_enable on

情境二：慢查詢排查

使用者: 線上查詢有點慢，幫我排查一下。

Agent 調用 (slow-query-analysis Skill):
  1. hologres sql run "SELECT query, duration, start_time FROM hg_query_log
       WHERE start_time > NOW() - INTERVAL '10 minutes'
       ORDER BY duration DESC LIMIT 10"
  2. 定位最耗時的 SQL
  3. hologres sql explain "<最耗時 SQL>"
  4. 輸出執行計畫分析與最佳化方案

情境三：建表設計

使用者: 幫我設計一張日增 1 億行的訂單表。

Agent 調用 (schema-generator Skill):
  1. 詢問查詢模式：高頻按 user_id 查詢、按日彙總統計
  2. 推薦方案：列存 + 按日邏輯分區 + user_id 分布鍵 + created_at 聚簇鍵
  3. hologres table create --name public.orders \
       --columns "order_id BIGINT NOT NULL, user_id INT, amount DECIMAL(10,2), created_at TIMESTAMPTZ, ds DATE NOT NULL" \
       --primary-key "order_id,ds" \
       --partition-by ds --partition-mode logical \
       --orientation column \
       --distribution-key user_id \
       --clustering-key "created_at:asc" \
       --partition-expiration-time "180 day" \
       --dry-run
  4. 輸出 DDL 與設計理由，待使用者確認後去掉 --dry-run 真正建表

情境四：即時 UV 去重

使用者: 5 億使用者即時統計各頻道 UV，幫我設計方案。

Agent 調用 (uv-compute Skill):
  1. 推薦 RoaringBitmap + 動態表方案
  2. 建立使用者字典編碼錶與按頻道彙總的 Bitmap 表
  3. 用動態表增量重新整理各頻道 Bitmap
  4. 查詢時使用 RB_CARDINALITY 函數實現亞秒級 UV 返回

執行 hologres 命令時提示 command not found 怎麼辦？

CLI 安裝目錄未加入 PATH。重新載入 shell 設定檔：

source ~/.bashrc   # 或 source ~/.zshrc

如仍未生效，將 uv 預設安裝目錄手動加入 PATH：

export PATH="$HOME/.local/bin:$PATH"

串連失敗如何排查？

先查看當前配置和串連狀態：

hologres config show    # 查看當前 Profile 詳情
hologres status         # 查看串連狀態與錯誤描述
hologres config         # 重新進入嚮導修正配置

重點檢查 4 項：

• 網路類型與運行環境是否匹配（本地選 internet、VPC 內選 vpc）。

• Instance ID 與 Region 是否正確。

• 認證資訊（帳號密碼或 AccessKey）是否有目標執行個體的存取權限。

• 公網訪問情境下，用戶端 IP 是否已加入執行個體白名單。

寫操作被拒絕怎麼辦？

根據返回的錯誤碼採取對應處理：

# WRITE_GUARD_ERROR：寫操作未授權，添加 --write
hologres sql run --write "INSERT INTO logs VALUES (1, 'test')"

# DANGEROUS_WRITE_BLOCKED：DELETE / UPDATE 缺少 WHERE，補充過濾條件
hologres sql run --write "DELETE FROM users WHERE id = 1"

執行 SELECT 時提示 LIMIT_REQUIRED 怎麼辦？

無 LIMIT 的 SELECT 預設最多返回 100 行。兩種處理方式任選其一：

hologres sql run "SELECT * FROM table LIMIT 100"          # 顯式添加 LIMIT
hologres sql run --no-limit-check "SELECT * FROM table"   # 關閉行數檢查

忘記資料庫密碼怎麼辦？

CLI 不儲存純文字密碼。重新回合組態嚮導，重新輸入即可：

hologres config

如何更新 CLI 與 Skills 到最新版本？

pip install --upgrade hologres-cli       # 升級 CLI
uvx hologres-agent-skills                # 重新啟動 Skills 安裝器，覆蓋更新