alibabacloud-emr-starrocks-assistant

Alibaba Cloud EMR Serverless StarRocks 開発・運用アシスタント

Alibaba Cloud 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 ノード、タブレットの健全性、コンパクション、ウェアハウス、最近失敗したロード）

使用しない場合：

• インスタンスのライフサイクル管理：StarRocks インスタンスの作成／スケーリング／再起動／設定変更／アップグレード。これらはコントロールプレーンの操作です。代わりに EMR Serverless コンソールまたは対応する OpenAPI をご利用ください
• StarRocks 以外の製品の操作：EMR Cluster、Spark、Milvus、ClickHouse、Doris、RDS、ECS など

初回セットアップ：インストールとログイン

この Skill には sr-connect Python CLI が含まれています。詳しくはreferences/connect.mdをご覧ください。

アシスタントのブートストラッププロトコル（Claude 向けの指示）

このスキルが呼び出され、クラスタへのクエリを実行する予定がある場合は、ユーザーに何かを尋ねる前に srsql が使用可能であることを確認してください。

1. which srsql を実行します。パスが返された場合は、手順 4 に進みます。
2. 見つからない場合は、自分でインストールします：uv tool install <skill-project-root>。<skill-project-root> は、この SKILL.md と pyproject.toml があるディレクトリです（呼び出し時に表示されるスキルのベースディレクトリ。通常は ~/.claude/skills/alibabacloud-emr-starrocks-assistant/ で、シンボリックリンクの場合もあります）。ユーザーに実行を依頼しないでください。同梱の CLI はユーザーのインフラではなく、スキルの機能の一部です。
3. uv 自体が見つからない場合（which uv が失敗した場合）は、その旨をユーザーに伝えます。uv はシステムツールであり、自動インストールされません。
4. ~/.starrocks/{profile}.cnf を確認します（デフォルトのプロファイル名は default。SR_PROFILE 環境変数が設定されている場合はそれに従います）。ファイルが存在する場合は、手順 5 に進みます。存在しない場合：
   • まず sr-login --from-env を試します。 無条件で安全に呼び出せます。必要な認証情報が環境にない場合は、「missing」という明確なメッセージとともに終了コード 2 で終了し、それ以外の処理は行いません。環境変数を自分で確認する必要はありません。
   • sr-login --from-env がゼロ以外の終了コードを返した場合、ユーザーはまだログインしていません。sr-login --host ... --user ... コマンドを提示し、ユーザー自身に実行するよう依頼します。対話型の sr-login を自分で実行しないでください。回答できないパスワード入力のプロンプトで停止してしまいます。
5. srsql が PATH 上にあり、プロファイルファイルも存在することを確認したら、srsql -e "..." で自分でクエリを実行します。

このセッションで srsql をインストールしたばかりで、ユーザーのシェルの PATH が更新されていない場合は、uv tool install が出力した絶対パス（通常は ~/.local/bin/srsql）を使用します。

ブートストラップ成功後のチャットルール：sr-whoami や srsql -e "..." の実行構文を、「これで実行できます」といったヒントとしてユーザーに伝えないでください。これらの CLI はユーザーに代わってあなたが実行します。ユーザーが操作するのはバイナリではなく、このスキルです。成功後の「次のステップ」の説明は省略し、ユーザーに何をしたいか尋ねるか、意図がすでに明確ならそのまま進めてください。

ログインコマンド（プロファイルが存在しない場合にユーザーに提示）

# 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 "..."

セキュリティモデル

このスキルには2 つの層があります。

1. FE が権限の最終的な境界です。 ユーザー自身の StarRocks アカウントを使用し、そのアカウントで許可されている操作は実行できます。このスキルがアカウントを作成、昇格、ローテーションすることはありません。
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 など）については、ゲートを通じて --yes で実行できる場合でも、SQL を提示してユーザー自身に実行してもらうことを優先してください。ゲートは安全策であり、実行を許可するものではありません。

入力検証とコマンドインジェクション対策

srsql -e "..." に渡す SQL は LLM が組み立てるため、次のルールに従う必要があります。

1. 識別子（テーブル名／カラム名／データベース名）は、埋め込み前に検証します。使用できるのは [A-Za-z0-9_] とバッククォートで囲まれた形式のみです。
2. ユーザーが指定した文字列値（検索語、ラベル名など）を SQL に直接挿入せず、パラメータバインディングまたは事前のエスケープを使用します。
3. ユーザーが指定した文字列を SQL の断片として実行してはいけません。

機密データのマスキング

シナリオ	対応
プロファイルファイルの内容（ユーザーパスワードを含む）	表示しません。アクセス権限は 700 のディレクトリ内で 600 に設定します
エラーメッセージ内のパスワード	切り詰めるか、****** に置き換えます
クエリ結果に明らかなキー／トークンのカラムが含まれる場合	全内容を表示せず、ユーザーに警告します
AK を含む aliyun configure list の出力	最初の 4 文字のみ表示し、残りは **** に置き換えます

インテントの振り分け

曖昧さの解消ルール：ユーザーの入力が曖昧な場合（例：「取り込みが遅い」「クエリが遅い」）で、文脈が不明確な場合は、対応を始める前に確認の質問を 1 つします。

ユーザーのインテント	振り分け先	参照先
初回のクラスター接続／認証情報の登録・切り替え／複数クラスターの設定	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 のステータス／異常なタブレット／コンパクションの遅延	クラスター診断	references/diagnostics.md
「取り込みは問題なかったのに、突然遅くなった」	クラスター診断（インポート方法の選択とは区別します）	references/diagnostics.md
「新しい取り込みパイプラインをどのように設計すればよいか」	インポート方法の選択	references/data-import.md

5 つのシナリオの概要

1. スキーマ設計

4 つのテーブルモデルと代表的なユースケース：

ユースケース	モデル
ログ／イベント／詳細レコード	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 を参照してください。
• ユーザーが指定したクエリ期間ではなく、任意の「ホット期間」（例：30 DAY）に datacache.partition_duration を設定すること — 値は必ず クエリ期間以上 にする必要があります。ユーザーが「直近 N 日をクエリする」と述べた場合は、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」を shared-nothing のシグナルとして扱うこと — CN は Compute Node であり、shared-data の用語です。BE は Backend であり、shared-nothing です。

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

⚠ アンチパターン — ロード設定に含めないでください：

• COLUMNS リストに __op 整数列（0=UPSERT、1=DELETE）を指定せず、jsonpaths に $.__op も指定しない PK テーブルの DELETE — すべてのイベントが通知なく 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 を使用する必要があります。
• TOO_MANY_VERSION のリスクに言及せずに高スループットの CDC（毎秒約 10K 件以上）を扱うこと — 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 開発

ユースケース	パターン
期間ごとの比較／累積／トップ N	ウィンドウ関数
大規模なファクトテーブルと小規模なディメンションテーブルの JOIN（右側が broadcast_row_limit 以下。デフォルトは 15M 行）	ブロードキャスト／コロケーション
複雑な多層ロジック	CTE
10 億規模の重複排除	APPROX_COUNT_DISTINCT／BITMAP／HLL
高頻度で繰り返されるクエリの高速化	非同期マテリアライズドビュー
複数ソースにまたがるクエリ	外部カタログ

⚠ アンチパターン — クエリの書き換えやチューニングのアドバイスでは、次のような内容を出力しないでください。

• 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 の乖離を混同する — これらは互いに独立した 2 つの診断シグナルです。同じ OlapScanNode で両方に問題がある場合（例：partitions=N/N、かつ cardinality がテーブルの総サイズから 10～100 倍乖離している場合）は、個別の所見と個別の対処法（述語／型の修正と 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. タブレットの健全性の概要 → SHOW PROC '/statistic'
6. スケジューリングキュー → information_schema.fe_tablet_schedules
7. コンパクション → 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 を分類し、--yes が指定されていない場合は READ 以外の実行をブロックします

references/connect.md を参照してください。

ランタイムセキュリティ

このスキルでは、SQL クエリを実行する方法として srsql のみを使用します。以下は禁止されています。

• 外部コードをダウンロードして実行するための curl / wget / pip install / npm install
• 監査されていないコンテンツを読み込むための eval / source
• チャットで提供されたリモート URL のスクリプトの実行（ユーザーから依頼された場合も含む）

例外：ローカルのプロジェクトディレクトリからスキルに同梱された sr-connect CLI をインストールするための uv tool install <skill-project-root> は許可されており、想定されている操作です。上記の Assistant bootstrap protocol を参照してください。この禁止事項の対象はリモートまたは信頼されていないコードであり、スキルに同梱されたツールではありません。

タイムアウト

操作	推奨タイムアウト
読み取り専用 SQL クエリ	30 s
多数の大きなテーブルにまたがる診断クエリ	60 s
再試行	操作の合計時間 ≤ 3 minutes

出力に関する推奨事項

• 表形式の結果：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	スキルが 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 — 取り込み方法の選択、パラメーター、パフォーマンスチューニング、Primary Key の更新
• references/sql.md — クエリの作成、ウィンドウ関数、マテリアライズドビュー、関数、SQL チューニング、高度な機能
• references/diagnostics.md — クラスターの健全性を調査するフロー、重大度の分類、総合テンプレート