analyzing-data

データ分析

データウェアハウスにクエリを実行して、ビジネス上の質問に回答します。カーネルは最初の exec 呼び出し時に自動的に起動します。

以下の CLI コマンドはすべて、このスキルのディレクトリを基準とします。 scripts/cli.py コマンドを実行する前に、このファイルがあるディレクトリに cd してください。

ワークフロー

1. パターンの検索 — キャッシュ済みのクエリ戦略を確認します。

   uv run scripts/cli.py pattern lookup "<user's question>"
   

   パターンがある場合は、その戦略に従います。実行後に結果を記録します。

   uv run scripts/cli.py pattern record <name> --success  # or --failure
   

2. 概念の検索 — 既知のテーブルマッピングを確認します。

   uv run scripts/cli.py concept lookup <concept>
   

3. テーブルの特定 — キャッシュにない場合は、コードベースを検索するか（Grep pattern="<concept>" glob="**/*.sql"）、INFORMATION_SCHEMA にクエリを実行します。reference/discovery-warehouse.md を参照してください。

4. クエリの実行：

   uv run scripts/cli.py exec "df = run_sql('SELECT ...')"
   uv run scripts/cli.py exec "print(df)"
   

5. 学びのキャッシュ — 結果を提示する前に、必ずキャッシュします。

   # Cache concept → table mapping
   uv run scripts/cli.py concept learn <concept> <TABLE> -k <KEY_COL>
   # Cache query strategy (if discovery was needed)
   uv run scripts/cli.py pattern learn <name> -q "question" -s "step" -t "TABLE" -g "gotcha"
   

6. 調査結果をユーザーに提示します。

カーネル関数

関数	戻り値
run_sql(query, limit=100)	Polars DataFrame
run_sql_pandas(query, limit=100)	Pandas DataFrame
run_sql_many(queries, limit=100)	Polars DataFrame のリスト（クエリごとに 1 つ）

pl（Polars）と pd（Pandas）は事前にインポートされています。

run_sql_many を使って、独立したクエリをまとめて実行できます。順番に 1 つずつ実行するのではなく、同時に実行されます（Snowflake の非同期処理／コネクションプールによる並列実行）。

uv run scripts/cli.py exec "dfs = run_sql_many(['SELECT ...', 'SELECT ...']); print(dfs[0])"

run_sql_many はエラー時に即時停止します。いずれかのクエリでエラーが発生すると呼び出しが例外を送出し、成功したクエリの結果も破棄されます。一部の結果が必要な場合は、run_sql を個別に呼び出してください。

タイムアウト： exec はデフォルトで最大 120 秒待機し、その後クエリを中断して「クライアントの待機が停止しました」というメッセージを返します（サーバー側ではクエリが引き続き実行される場合があります）。実行時間が長いことが分かっているクエリでは、タイムアウトを延長してください：uv run scripts/cli.py exec "..." -t 600。

アイドル状態のカーネル： カーネルは 2 時間アイドル状態が続くと自動終了します（それまでは状態が保持されます）。ASTRO_KERNEL_IDLE_TIMEOUT（秒単位。0 を指定すると無効）で変更できます。

CLI リファレンス

カーネル

uv run scripts/cli.py warehouse list      # List warehouses
uv run scripts/cli.py start [-w name]     # Start kernel (with optional warehouse)
uv run scripts/cli.py exec "..."          # Execute Python code
uv run scripts/cli.py status              # Kernel status
uv run scripts/cli.py restart             # Restart kernel
uv run scripts/cli.py stop                # Stop kernel
uv run scripts/cli.py install <pkg>       # Install package

概念キャッシュ

uv run scripts/cli.py concept lookup <name>                     # Look up
uv run scripts/cli.py concept learn <name> <TABLE> -k <KEY_COL> # Learn
uv run scripts/cli.py concept list                               # List all
uv run scripts/cli.py concept import -p /path/to/warehouse.md   # Bulk import

パターンキャッシュ

uv run scripts/cli.py pattern lookup "question"                                      # Look up
uv run scripts/cli.py pattern learn <name> -q "..." -s "..." -t "TABLE" -g "gotcha"  # Learn
uv run scripts/cli.py pattern record <name> --success                                # Record outcome
uv run scripts/cli.py pattern list                                                   # List all
uv run scripts/cli.py pattern delete <name>                                          # Delete

テーブルスキーマキャッシュ

uv run scripts/cli.py table lookup <TABLE>            # Look up schema
uv run scripts/cli.py table cache <TABLE> -c '[...]'  # Cache schema
uv run scripts/cli.py table list                       # List cached
uv run scripts/cli.py table delete <TABLE>             # Delete

キャッシュ管理

uv run scripts/cli.py cache status                # Stats
uv run scripts/cli.py cache clear [--stale-only]  # Clear

リファレンス

• reference/discovery-warehouse.md — 大規模テーブルの扱い、データウェアハウスの調査、INFORMATION_SCHEMA クエリ
• reference/common-patterns.md — トレンド、比較、トップ N、分布、コホートの SQL テンプレート