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 安装器，覆盖更新