---

name: metabase-query-dev description: Metabase Dev環境からデータを取得・エクスポートするSkill。フルスキャンクエリを検出し、最適化を提案します。 allowed-tools: Bash(curl:*), Write, AskUserQuestion

Metabase Query Skill (Dev環境)

概要

このSkillは、Metabase Dev環境（https://metabase.dev.recerqa.com）からデータを取得し、CSVでエクスポートします。 重要: クエリ実行前に必ずEXPLAINでフルスキャンをチェックし、パフォーマンス問題を防ぎます。

環境設定

APIキー: 実行前にユーザーへヒアリングし、必要に応じて環境変数 MB_API_KEY を利用します。 ベースURL: デフォルトは https://metabase.dev.recerqa.com。必要ならユーザーに確認して上書きします。

curlコマンドの注意事項

重要: curlコマンドは必ず以下の形式で実行してください:

• 1行で記述する - バックスラッシュ(\)での改行継続を使用しない
• --header を使用する - -H の短い形式を避ける
• --fail-with-body と --show-error を使う - 失敗時に検知できるようにする
• JSONは標準入力で渡す - SQL内のシングルクォートで壊れないようにする

APIキーに含まれる特殊文字（+, =）やSQL内のシングルクォートがシェル環境で正しく解釈されない場合があるためです。

利用可能なデータベース

ワークフロー

Step 1: ユーザー要求の理解

ユーザーから以下を確認:

• どのデータが必要か
• どのデータベースを使うか (デフォルト: rq-dev-db, ID=2)
• フィルタ条件（日付範囲、特定のID等）
• 出力ファイル名（未指定なら ./export_YYYYmmdd_HHMMSS.csv を使用）
• APIキー（未指定なら MB_API_KEY を利用、なければ必ずユーザーに再確認）
• ベースURL（未指定なら https://metabase.dev.recerqa.com を使用）

Step 2: スキーマ情報の取得（必要に応じて）

テーブル一覧を取得:

Copyprintf '%s' '{"database": 2, "type": "native", "native": {"query": "SHOW TABLES"}}' | curl -s --fail-with-body --show-error -X POST 'https://metabase.dev.recerqa.com/api/dataset' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/json' --data @- | jq '.data.rows[]'

テーブルのカラム情報を取得:

Copyprintf '%s' '{"database": 2, "type": "native", "native": {"query": "DESCRIBE {table_name}"}}' | curl -s --fail-with-body --show-error -X POST 'https://metabase.dev.recerqa.com/api/dataset' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/json' --data @- | jq '.data.rows'

Step 3: SQL生成

ユーザーの要求に基づいてSQLを生成します。 この時点ではまだ実行しません。

Step 4: フルスキャン検出 (必須)

クエリ実行前に必ずEXPLAINを実行してください。

Copyprintf '%s' '{"database": 2, "type": "native", "native": {"query": "EXPLAIN {生成したSQL}"}}' | curl -s --fail-with-body --show-error -X POST 'https://metabase.dev.recerqa.com/api/dataset' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/json' --data @- | jq '.data.rows'

EXPLAIN結果の解析

追加チェック項目

• rows > 10000: 大量行スキャンの警告
• possible_keys = NULL: インデックス未使用の警告
• Extra に Using filesort / Using temporary: パフォーマンス注意

Step 5: フルスキャン検出時の対応

A) フルスキャン検出時

1. 問題を明確に説明:

   Copy⚠️ フルスキャン警告
   
   このクエリはフルテーブルスキャンを実行します:
   - テーブル: {table_name}
   - 推定行数: {rows}行
   - type: ALL
   
   これはデータベースに負荷をかける可能性があります。
   

2. 修正案を提示:

   • WHERE句の追加（インデックスカラムを使用）
   • LIMIT句の追加
   • 日付範囲の絞り込み

3. ユーザーに選択肢を提示:

   • 修正案を採用する
   • フルスキャンを許可して続行する
   • キャンセルする

B) 修正不可能な場合

ユーザーに以下を警告:

Copy⚠️ このクエリはフルスキャンが必要です

理由: {理由を説明}

続行する場合、データベースに負荷がかかる可能性があります。
本当に実行しますか？

Step 6: クエリ実行

承認後、クエリを実行:

Copyprintf '%s' '{"database": 2, "type": "native", "native": {"query": "{SQL}"}}' | curl -s --fail-with-body --show-error -X POST 'https://metabase.dev.recerqa.com/api/dataset' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/json' --data @- | jq '.data.rows'

Step 7: CSV エクスポート

結果をCSVでエクスポート:

Copyprintf '%s' 'query={"database":2,"type":"native","native":{"query":"{SQL}"}}' | curl -s --fail-with-body --show-error -X POST 'https://metabase.dev.recerqa.com/api/dataset/csv' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/x-www-form-urlencoded' --data @- > ./export_$(date +%Y%m%d_%H%M%S).csv

エクスポート完了後、ファイルパスをユーザーに報告してください。

使用例

例1: 特定テーブルの全データ取得（LIMIT付き）

ユーザー: 「api_keysテーブルのデータを10件取得して」

1. EXPLAIN実行 → type確認
2. 問題なければ実行
3. CSVエクスポート

例2: 日付範囲でフィルタ

ユーザー: 「2024年1月以降に作成されたデータを取得して」

1. SQLを生成: SELECT * FROM {table} WHERE created_at >= '2024-01-01'
2. EXPLAIN実行 → インデックス使用を確認
3. 問題なければ実行

例3: フルスキャンが必要な場合

ユーザー: 「全ユーザーのデータが欲しい」

1. EXPLAIN実行 → type=ALL検出
2. 警告を表示
3. 修正案を提示（LIMIT追加など）
4. ユーザーの承認を得て実行

注意事項

1. 本番環境では使用しないでください - このSkillはDev環境専用です
2. APIキーは必ずユーザーに確認し、環境変数で扱うこと - ドキュメントやログに平文で残さない
3. 大量データの取得時は必ずLIMITを使用してください
4. 機密データ（パスワード、トークン等）は取得しないでください
5. クエリ実行前のEXPLAINは必須です - スキップしないでください

トラブルシューティング

APIキーエラー

認証エラーが発生した場合、APIキーの有効期限を確認してください。

タイムアウト

大量データの場合、クエリがタイムアウトする可能性があります。 LIMIT句を追加してデータ量を制限してください。

カラム名エラー

テーブルのスキーマを再確認してください:

Copyprintf '%s' '{"database": 2, "type": "native", "native": {"query": "DESCRIBE {table_name}"}}' | curl -s --fail-with-body --show-error -X POST 'https://metabase.dev.recerqa.com/api/dataset' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/json' --data @- | jq '.data.rows'

curlコマンドエラー

curl: option : blank argument where content is expected エラーが発生した場合:

重要: curlコマンドは必ず以下の形式で実行してください:

1. 1行で記述する - バックスラッシュ(\)での改行継続を使用しない
2. --header を使用する - -H の短い形式を避ける
3. --fail-with-body と --show-error を使う
4. JSONは標準入力で渡す

Copy# ✅ 正しい形式
printf '%s' '{"database": 2, "type": "native", "native": {"query": "SHOW TABLES"}}' | curl -s --fail-with-body --show-error -X POST 'https://...' --header "X-API-Key: $MB_API_KEY" --header 'Content-Type: application/json' --data @-

# ❌ 避けるべき形式
curl -s -X POST https://... \
  -H "X-API-Key: ..." \
  -H "Content-Type: application/json" \
  -d '...'

原因: APIキーに含まれる特殊文字やSQL内のシングルクォートがシェル環境で正しく解釈されない場合があります。