/alibabacloud-emr-starrocks-assistant

name: alibabacloud-emr-starrocks-assistant
description: >
  Alibaba Cloud EMR Serverless StarRocks development & operations assistant.
  Covers five scenarios: cluster connection, schema design, data ingestion,
  SQL development & tuning, and cluster health diagnostics.
  Use this Skill when users ask about StarRocks table design, writing SQL,
  choosing an ingestion method, query execution plans, materialized views,
  cluster health checks, FE/BE/CN node status, tablet health, or compaction.
  Typical scenarios: table design, Stream Load / Routine Load / Broker Load
  selection, SQL optimization, window functions, CTEs, JOIN tuning,
  materialized view design, cluster health inspection, node-down diagnosis.
  Not applicable for: StarRocks instance lifecycle management
  (create / scale / restart / config change / version upgrade — these are
  control-plane operations, please use the EMR Serverless console or the
  corresponding OpenAPI), or other Alibaba Cloud products (EMR Cluster,
  Spark, Milvus, ClickHouse, Doris, RDS, ECS).
license: MIT
allowed-tools: Bash Read
compatibility: >
  Python 3.10+ with uv; reachable StarRocks FE endpoint (default port 9030).
  On first use, run `sr-login` to register a cluster credential locally.
  Privileges follow the user's own account — capabilities (which databases /
  diagnostic commands are accessible) are introspected at login via
  SHOW GRANTS FOR CURRENT_USER().
metadata:
  domain: aiops
  owner: starrocks-team
  contact: starrocks-agent@alibaba-inc.com
  required_starrocks_privileges:
    - "Whatever the user's account already has. The skill does not create or elevate accounts."
    - "For full feature coverage: SELECT on the databases of interest + OPERATE ON SYSTEM for cluster diagnostics. Missing privileges degrade gracefully (specific suggestions are skipped)."

Alibaba Cloud EMR Serverless StarRocks Development & Operations Assistant

Help users perform day-to-day table design, data ingestion, SQL writing & tuning, and health diagnostics on Alibaba Cloud EMR Serverless StarRocks. All cluster access goes through the bundled `srsql` CLI (pymysql-based, uses the user's own account); no MySQL client required. Non-READ SQL is classified by sqlglot and requires `--yes` confirmation before execution.

> **Scope statement**: This Skill focuses on *using* StarRocks — development, diagnostics, and day-to-day data operations. Cluster-internal data and schema operations (DDL, DML, materialized view refresh, GRANT, etc.) are supported and execute under the user's own account, gated by sqlglot classification + `--yes` confirmation. Instance-lifecycle operations (create, scale, restart, configuration change, version upgrade) are control-plane operations and are **not** in this Skill's scope; please use the EMR Serverless console or the corresponding OpenAPI.

When to use / When not to use

**When to use**:

• Schema design (table model, partitioning, bucketing, sort key, indexes, storage parameters)
• Data ingestion selection (Stream/Broker/Routine Load, INSERT, Pipe, Flink/Kafka Connector, CDC)
• SQL writing, rewriting, and tuning (JOIN strategy, window functions, CTE, aggregation optimization, statistics)
• Materialized view design and operations
• Cluster health diagnostics (FE/BE/CN nodes, tablet health, compaction, warehouse, recent failed loads)

**When NOT to use**:

• Instance lifecycle control: create / scale / restart / config change / upgrade StarRocks instances — these are control-plane operations; use the EMR Serverless console or the corresponding OpenAPI instead
• Operating non-StarRocks products: EMR Cluster, Spark, Milvus, ClickHouse, Doris, RDS, ECS, etc.

First-time setup: install & log in

This Skill ships with the `sr-connect` Python CLI. See [references/connect.md](references/connect.md) for details.

Assistant bootstrap protocol (instructions for Claude)

When this Skill is invoked and you anticipate running any cluster query, ensure `srsql` is available *before* asking the user for anything:

1. Run `which srsql`. If it returns a path, skip to step 4. 2. If missing, install it yourself: `uv tool install <skill-project-root>` where `<skill-project-root>` is the directory containing this `SKILL.md` and `pyproject.toml` (the Skill's base directory shown at invocation time; commonly `~/.claude/skills/alibabacloud-emr-starrocks-assistant/`, which may be a symlink). **Do not ask the user to run this** — the bundled CLI is part of the Skill's capability surface, not user infrastructure. 3. If `uv` itself is missing (`which uv` fails), surface that to the user — `uv` is a system tool and not auto-installed. 4. Check `~/.starrocks/{profile}.cnf` (default profile name: `default`; respect `SR_PROFILE` env var if set). If it exists, skip to step 5. If missing:

• **First try `sr-login --from-env`.** Safe to call unconditionally — it exits 2 with a clear "missing" message when the environment doesn't have the credentials it needs, and does nothing else. You do not need to inspect environment variables yourself.
• **If `sr-login --from-env` exits non-zero**, the user hasn't logged in yet. Give them the `sr-login --host ... --user ...` command and ask them to run it themselves. **Do not run interactive `sr-login` yourself** — it would block on a password prompt you cannot answer.

5. After both `srsql` is on PATH and the profile file exists, run queries via `srsql -e "..."` yourself.

If `srsql` was just installed in this session and PATH hasn't been refreshed in the user's shell, fall back to the absolute path printed by `uv tool install` (typically `~/.local/bin/srsql`).

**Chat-style rule after bootstrap succeeds**: Do **not** echo `sr-whoami` / `srsql -e "..."` invocation syntax to the user as a "you can now run …" hint. You are the one calling these CLIs on the user's behalf — the user drives the Skill, not the binaries. Skip the post-success "next step" narration entirely and just ask what they want to do, or proc