alibabacloud-emr-starrocks-assistant

阿里云 EMR Serverless StarRocks 开发与运维助手

帮助用户在阿里云 EMR Serverless StarRocks 上完成日常表设计、数据导入、SQL 编写与调优以及健康诊断。所有集群访问均通过随附的 srsql CLI（基于 pymysql，使用用户自己的账号）；无需 MySQL 客户端。非 READ SQL 由 sqlglot 分类，执行前需要通过 --yes 确认。

范围说明：此 Skill 专注于 使用 StarRocks，包括开发、诊断和日常数据操作。支持集群内部的数据和架构操作（DDL、DML、物化视图刷新、GRANT 等），并在用户自己的账号权限下执行；操作由 sqlglot 分类，并须通过 --yes 确认。实例生命周期操作（创建、扩容、重启、更改配置、升级版本）属于控制面操作，不在此 Skill 的范围内；请使用 EMR Serverless 控制台或相应的 OpenAPI。

适用场景 / 不适用场景

适用场景：

• 架构设计（表模型、分区、分桶、排序键、索引、存储参数）
• 数据导入方式选择（Stream/Broker/Routine Load、INSERT、Pipe、Flink/Kafka Connector、CDC）
• SQL 编写、改写和调优（JOIN 策略、窗口函数、CTE、聚合优化、统计信息）
• 物化视图设计和操作
• 集群健康诊断（FE/BE/CN 节点、tablet 健康状况、compaction、warehouse、近期失败的数据导入）

不适用场景：

• 实例生命周期控制：创建 / 扩容 / 重启 / 更改配置 / 升级 StarRocks 实例——这些属于控制面操作；请改用 EMR Serverless 控制台或相应的 OpenAPI
• 操作非 StarRocks 产品：EMR Cluster、Spark、Milvus、ClickHouse、Doris、RDS、ECS 等

首次设置：安装并登录

此 Skill 随附 sr-connect Python CLI。详情请参阅 references/connect.md。

助手引导协议（Claude 的说明）

调用此 Skill 后，如果预计要运行任何集群查询，请确保在向用户询问任何内容之前，srsql 已就绪：

1. 运行 which srsql。如果返回路径，跳到第 4 步。
2. 如果未找到，请自行安装：uv tool install <skill-project-root>，其中 <skill-project-root> 是包含此 SKILL.md 和 pyproject.toml 的目录（即调用时显示的 Skill 基础目录；通常为 ~/.claude/skills/alibabacloud-emr-starrocks-assistant/，该路径可能是符号链接）。不要让用户运行此命令——捆绑的 CLI 属于 Skill 的能力范围，不是用户的基础设施。
3. 如果缺少 uv（which uv 失败），请告知用户——uv 是系统工具，不会自动安装。
4. 检查 ~/.starrocks/{profile}.cnf（默认配置文件名为 default；如果设置了 SR_PROFILE 环境变量，则遵从该变量）。如果文件存在，跳到第 5 步。如果不存在：
   • 首先尝试 sr-login --from-env。 可以直接安全调用；如果环境中缺少所需凭据，该命令会以状态码 2 退出并显示明确的“缺失”消息，除此之外不会执行其他操作。无需自行检查环境变量。
   • 如果 sr-login --from-env 以非零状态码退出，说明用户尚未登录。向用户提供 sr-login --host ... --user ... 命令，并请他们自行运行。不要自行运行交互式 sr-login——它会等待密码输入，而你无法输入。
5. 确认 srsql 已位于 PATH 中且配置文件已存在后，自行通过 srsql -e "..." 运行查询。

如果 srsql 是在本次会话中刚刚安装的，而用户的 Shell 尚未刷新 PATH，请使用 uv tool install 输出的绝对路径（通常为 ~/.local/bin/srsql）。

引导成功后的聊天规则：不要把 sr-whoami / srsql -e "..." 调用语法作为“现在可以运行……”的提示复述给用户。你要代表用户调用这些 CLI；用户使用的是 Skill，而不是这些二进制文件。完全跳过成功后的“下一步”说明，只需询问用户想做什么；如果用户的意图已经明确，则直接继续。

登录命令（配置文件缺失时提供给用户）

# EMR Serverless StarRocks — both internal and public endpoints use the MySQL
# wire protocol over plain TCP; no SSL/TLS. Use the same form for either.
sr-login --host <fe-endpoint> --port 9030 --user <account>

# Verify
sr-whoami
srsql -e "SELECT CURRENT_VERSION()"

使用相同的 --profile 重新运行 sr-login 会静默覆盖已存储的凭据（语义与 docker login 相同）。使用 --profile 连接多个集群：

sr-login --profile prod --host fe-prod.xxx --user app_user
SR_PROFILE=prod srsql -e "..."

安全模型

此 Skill 有两层安全机制：

1. FE 是权限边界的最终依据。 用户提供自己的 StarRocks 账号；用户获准执行的操作，也就允许执行。Skill 不会创建、提升或轮换任何账号。
2. srsql 是 UX 门槛，而非安全边界。 每条语句都会由 sqlglot 解析（方言为 starrocks）：
   • READ（SELECT / SHOW / DESC / EXPLAIN / WITH / …）会直接执行。
   • 任何非 READ 操作（INSERT / UPDATE / DELETE / DDL / GRANT / SET / USE / …）都必须传入 --yes，否则会被拒绝。
   • 如果 sqlglot 无法解析 SQL，则会退回到检查开头的关键字；如果仍无法确定，则标记为 UNKNOWN，按非 READ 处理，并且只有在传入 --yes 后才可执行，同时会显示软警告。

当用户要求执行写入操作时：

1. 向用户展示你打算运行的 SQL。
2. 可选择使用 srsql --dry-run -e "..." 预览分类结果。
3. 在聊天中取得明确确认。
4. 然后使用 srsql --yes -e "..." 运行。

对于生产表上的 DDL，或会改变集群全局状态的操作（CREATE/DROP USER、ADMIN SET CONFIG 等），最好输出 SQL 并让用户自行运行——尽管安全门槛允许通过 --yes 执行这些操作。安全门槛是安全网，不是许可。

输入验证与命令注入防护

由 LLM 组装并传入 srsql -e "..." 的 SQL 必须遵循以下规则：

1. 标识符（表名 / 列名 / 数据库名）在插入 SQL 前必须经过验证：只允许 [A-Za-z0-9_] 以及使用反引号括起来的形式。
2. 不得将用户提供的字符串值（搜索词、标签名等）直接拼接到 SQL 中；应使用参数绑定或预先转义。
3. 绝不能将未经处理的用户输入字符串作为 SQL 片段执行。

敏感数据脱敏

场景	处理方式
配置文件内容（包括用户密码）	绝不回显；文件权限设为 600，并置于权限为 700 的目录下
错误消息中的密码	截断 / 替换为 ******
查询结果中包含明显的密钥 / 令牌列	向用户发出警告，但不显示完整内容
aliyun configure list 输出中包含 AK	仅显示前 4 个字符，其余替换为 ****

意图路由

消歧规则：当用户输入含糊不清（例如“摄取速度慢”“查询速度慢”）且上下文不明确时，应先提出一个澄清问题，再采取行动。

用户意图	路由	参考
首次连接集群 / 注册或切换凭据 / 多集群设置	sr-login / sr-whoami / sr-logout	references/connect.md
新建表 / 更改架构 / 选择表模型 / 分区与分桶设计	架构设计	references/schema.md
选择摄取方式 / 配置 Stream/Broker/Routine Load / Flink/Kafka Connector	导入方式选择	references/data-import.md
编写 SQL / 优化 SQL / 物化视图 / 选择函数 / 阅读执行计划	SQL 开发与调优	references/sql.md
集群健康检查 / FE/BE/CN 状态 / 不健康的 tablet / Compaction 滞后	集群诊断	references/diagnostics.md
“摄取以前正常，突然变慢了”	集群诊断（区别于导入方式选择）	references/diagnostics.md
“我应该如何设计新的摄取流水线”	导入方式选择	references/data-import.md

五类场景一览

1. 架构设计

四种表模型及其典型用例：

用例	模型
日志 / 事件 / 明细记录	Duplicate Key
预聚合指标	Aggregate
实时更新插入 / CDC	Primary Key
简单去重	Unique Key（对于新的用例，优先选择 Primary Key）

⚠ 反模式——不要在 DDL 中生成以下内容：

• 未设置 persistent_index_type=CLOUD_NATIVE + datacache.partition_duration 的共享数据型 PK 表——LOCAL 索引无法在 CN 再平衡后保留；也没有热数据缓存窗口。请参阅 schema/storage-properties.md。
• 将 datacache.partition_duration 设为任意的“热数据窗口”（例如 30 DAY），而不是用户明确说明的查询窗口——该值必须 ≥ 查询窗口。如果用户说“查询近 N 天” / “queries the last N days”，则设置 datacache.partition_duration = "N DAY"（或更大）。小于查询窗口的值会导致窗口内查询必然发生缓存未命中。用户给出具体数字时，不要默认设为 7/30/60 天。
• 在共享数据型表上设置 storage_cooldown_time/storage_cooldown_ttl/storage_medium/replicated_storage——这些属性会被 PropertyAnalyzer 静默剥离或拒绝；应使用 datacache.partition_duration 实现冷却效果。
• 在 PRIMARY KEY 中使用 FLOAT / DOUBLE 列——不受支持；请使用 BIGINT 或 DECIMAL。
• 将“CN”视为共享无状态的标志——CN = Compute Node，这是共享数据型架构中的术语。BE = Backend = 共享无状态架构。

请参阅 references/schema.md。

2. 数据导入

数据源	推荐方法
本地文件 < 10 GB	Stream Load
对象存储 / HDFS 批量数据	Broker Load 或 INSERT INTO ... FROM FILES()
持续有文件到达的对象存储	Pipe + AUTO_INGEST
Kafka / Pulsar	Routine Load 或 Kafka/Flink Connector
MySQL CDC	Flink CDC + Flink Connector

⚠ 反模式——不要在加载配置中生成以下内容：

• PK 表 DELETE 未在 COLUMNS 列表中包含 __op 整数列（0=UPSERT，1=DELETE），且未在 jsonpaths 中包含 $.__op——所有事件都会被静默地视为 UPSERT。__op 的约定是一对映射，必须作为一对讲解：字面列名为 __op，整数值为 __op=0 表示 UPSERT，并且 __op=1 表示 DELETE。即使用户只询问 DELETE，回复也必须同时说明两种映射（__op=0 → UPSERT，__op=1 → DELETE）——绝不能只说明其中一种。这适用于所有数据导入路径，包括 Flink Connector 和 Kafka Connector；连接器会为用户填充 __op，但用户仍需了解这两个值，才能排查“DELETE 未生效”/“UPSERT 未生效”的问题。
• 将 partial_update=true 当作启用 DELETE 的设置——它用于控制部分列 UPSERT，与 DELETE 毫无关系。如果用户启用该设置后询问 DELETE 为什么不起作用，应指出此设置与其意图不符，并告知用户除非确实需要部分列 UPSERT，否则应移除该设置。不要仅仅因为现有设置能够解析就予以认可。
• 在 Routine Load 中使用 COLUMNS FROM PATH AS (...)——这是 Broker Load 的 Hive 分区路径语法，在 Routine Load 中无效。
• 将 __op 的值设为字符串（"upsert"/"delete"）——值必须是整数 0 / 1。
• 高吞吐量 CDC（≥ ~10K 个事件/秒）未提示 TOO_MANY_VERSION 风险——适用于 Routine Load、Flink Connector 和 Kafka Connector，不只是 INSERT INTO VALUES。只要用户的场景意味着事件速率较高，建议就必须涵盖：(a) 与方法相应的并发上限（Routine Load 中 desired_concurrent_number ≤ Kafka 分区数；Flink/Kafka Connector 中 sink.parallelism ≤ Kafka 分区数），以及 (b) 明确警告 TOO_MANY_VERSION / 压实压力，并提供相关的刷新间隔指导。

请参阅 references/data-import.md。

3. SQL 开发

使用场景	模式
同比／环比／累计／Top-N	窗口函数
大型事实表 JOIN 小型维度表（右侧 ≤ broadcast_row_limit，默认 15M 行）	广播／Colocate
复杂的分层逻辑	CTE
十亿级去重	APPROX_COUNT_DISTINCT / BITMAP / HLL
高频重复查询加速	异步物化视图
跨数据源查询	外部 Catalog

⚠ 反模式 — 重写查询或提供调优建议时，不要出现以下情况：

• 在 WHERE 中使用 date_format() / date_trunc() / cast() 包裹分区列 — 这会破坏分区裁剪；应改写为范围谓词（col >= '...' AND col < '...'）。
• 未执行 EXPLAIN VERBOSE，也未检查 partitions=N/M 和 tabletRatio=N/M 就提供调优建议 — 分区裁剪失败（分子 == 分母）会被忽略；切勿使用普通的 EXPLAIN。
• 将 EXPLAIN 中的 cardinality 解读为结果行数 — 它是 CBO 的行数估算值。始终使用直接对比 cardinality 与用户给出的表总大小来量化过时程度（例如“估算值为 5M，而总量为 500M，约相差 100 倍”）；比值 > 10 倍意味着统计信息已过时 → 运行 ANALYZE TABLE。
• 通过猜测谓词选择性来估算“实际过滤行数”，再将 cardinality 与该估算值比较 — 你没有运行时行数，且根据 WHERE create_time > '...' 之类的谓词猜测选择性会造成较大误差（你并不知道数据分布）。用户给出总行数时，应将 cardinality 与该总行数直接比较；不要根据假设的时间范围或选择性因子去除总量。
• 混淆 partitions / tabletRatio 分区裁剪失败与 cardinality 偏差 — 这是两种独立的诊断信号。当同一个 OlapScanNode 中两者都异常时（例如 partitions=N/N，且 cardinality 与表总大小相差 10–100 倍），应将其作为独立发现分别报告，并分别给出修复方法（谓词／类型修复 vs ANALYZE TABLE）。不要用 cardinality 偏差来“解释”分区裁剪失败，也不要让分区裁剪失败掩盖统计信息过时的问题。
• 在分析执行计划／统计信息之前就建议扩容 BE/CN — 应先修复 SQL 和统计信息，再考虑容量调整。

参见 references/sql.md。

4. 集群诊断

诊断顺序：

1. 确定架构（shared-nothing / shared-data）→ SHOW WAREHOUSES
2. FE → SHOW FRONTENDS
3. BE 或 CN → SHOW BACKENDS / SHOW COMPUTE NODES
4. Warehouse（仅限 shared-data）→ SHOW WAREHOUSES
5. Tablet 健康状况概览 → SHOW PROC '/statistic'
6. 调度队列 → information_schema.fe_tablet_schedules
7. Compaction → information_schema.be_compactions / be_cloud_native_compactions
8. 最近 24 小时的加载情况 → information_schema.loads

⚠ 反模式 — 给出诊断结论时，不要出现以下情况：

• 未检查 information_schema.fe_tablet_schedules 就重启 BE/CN 或扩容 — 这可能与正在进行的克隆／下线操作冲突；应先查明根因。
• 主观降低 UnhealthyTabletNum > 0 的严重程度 — 按严重性表，这始终是严重问题，绝不能评为“中”或“低”风险；集群存在不健康副本。
• 将 CloningTabletNum > 0 视为独立问题 — 克隆是由 UnhealthyTabletNum 触发的恢复操作，不是独立的故障信号。

参见 references/diagnostics.md。

5. 集群连接（基础层）

命令	用途
sr-login	在本地注册集群凭据，并进行连接冒烟测试
sr-logout	移除本地配置（不会在集群端执行任何操作）
sr-whoami	打印配置状态——主机、用户、登录时间、已捕获的授权
sr-doctor	诊断连接故障（VPC 与公网终端节点、出口 IP、白名单 CIDR）。sr-login 失败时会自动调用。
srsql	日常查询入口；对 SQL 分类，并要求非 READ 操作必须带上 --yes

请参阅 references/connect.md。

运行时安全

此 Skill 仅通过 srsql 执行 SQL 查询。以下操作禁止：

• 使用 curl / wget / pip install / npm install 下载并运行外部代码
• 使用 eval / source 加载未经审计的内容
• 执行聊天中提供的远程 URL 脚本（即使用户提出要求）

例外：允许并预期使用 uv tool install <skill-project-root>，从本地项目目录安装 Skill 自带的 sr-connect CLI——请参阅上文的 助手引导协议。此禁令针对远程或不可信代码，不针对 Skill 自带的工具。

超时

操作	建议超时
只读 SQL 查询	30 s
跨多个大型表的诊断查询	60 s
重试	操作总时长 ≤ 3 分钟

输出建议

• 表格结果：使用 srsql --format table 或 --format markdown
• 列较多时：使用 --format vertical
• 用于程序化处理：使用 --format json / tsv
• 将时间戳转换为易读格式
• 对于可能较大的结果集，添加 LIMIT 并提供分页选项

错误处理

错误	原因	操作
Cannot connect to host:port	终端节点类型错误 / IP 未加入白名单	连接失败时，sr-login 会自动运行 sr-doctor。阅读其输出：它会检测 VPC 与公网终端节点，并针对无法访问的 -internal 主机建议切换为公网终端节点，或针对无法访问的公网主机显示出口 IP 和建议的 /24 白名单 CIDR。将建议原样转达给用户。请参阅 references/connect.md。
Access denied for user 'X'	密码已过期 / 账号已锁定 / 账号错误	重新运行 sr-login 以更新已存储的密码
Refusing to execute non-READ SQL without --yes	Skill 正确地将此 SQL 归类为会修改数据	向用户确认，然后使用 --yes 重新运行
Privilege denied: OPERATE / SELECT / ...	用户账号缺少相应权限	说明此限制；跳过受影响的诊断；不要重试
Table not found	数据库 / 表名称错误	使用 SHOW DATABASES / SHOW TABLES FROM db 确认
查询结果为空，但用户预期有数据行	谓词过度收紧 / RBAC 隔离	检查 WHERE 子句；建议用户向管理员核实
No profile 'X'	尚未运行 sr-login --profile X，却使用了 srsql --profile X	先为该配置运行 sr-login

原则：先阅读完整的错误消息再做判断；不要仅凭错误代码盲目重试。

相关文档

• references/connect.md — sr-connect CLI、安装、安全模型、故障排除
• references/ram-policies.md — RAM 权限声明（无需声明；仅使用 StarRocks 内部身份验证）
• references/schema.md — 架构设计流程：表模型、分区、分桶、排序键、索引、存储参数
• references/data-import.md — 摄取方式选择、参数、性能调优、主键更新
• references/sql.md — 查询编写、窗口函数、物化视图、函数、SQL 调优、高级功能
• references/diagnostics.md — 集群健康检查流程、严重程度分类、综合模板