データ分析スキル
概要
このスキルは、ユーザーがアップロードしたExcel/CSVファイルを、インプロセス分析SQLエンジンであるDuckDBを使用して分析します。スキーマ検査、SQLベースのクエリ、統計サマリーの生成、結果のエクスポートを、単一のPythonスクリプトで実現します。
コア機能
- Excel/CSVファイルの構造を検査（シート、列、型、行数）
- アップロードされたデータに対して任意のSQLクエリを実行
- 統計サマリーを生成（平均、中央値、標準偏差、パーセンタイル、null数）
- 複数シートのExcelブックをサポート（各シートがテーブルになる）
- クエリ結果をCSV、JSON、Markdownにエクスポート
- DuckDBのカラムナエンジンにより大規模ファイルを効率的に処理
ワークフロー
ステップ1：要件の理解
ユーザーがデータファイルをアップロードして分析を依頼した場合、以下を特定します：
- ファイルの場所：
/mnt/user-data/uploads/以下にあるアップロードされたExcel/CSVファイルへのパス - 分析の目的：ユーザーが求めている洞察（要約、フィルタリング、集計、比較など）
- 出力形式：結果の表示方法（表、CSVエクスポート、JSONなど）
/mnt/user-data以下のフォルダを確認する必要はありません
ステップ2：ファイル構造の検査
まず、アップロードされたファイルのスキーマを理解するために検査します：
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/data.xlsx \
--action inspect
これにより以下が返されます：
- シート名（Excelの場合）またはファイル名（CSVの場合）
- 列名、データ型、非nullカウント
- シート/ファイルごとの行数
- サンプルデータ（最初の5行）
ステップ3：分析の実行
スキーマに基づいて、ユーザーの質問に答えるSQLクエリを構築します。
SQLクエリの実行
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/data.xlsx \
--action query \
--sql "SELECT category, COUNT(*) as count, AVG(amount) as avg_amount FROM Sheet1 GROUP BY category ORDER BY count DESC"
統計サマリーの生成
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/data.xlsx \
--action summary \
--table Sheet1
数値列の場合：count、mean、std、min、25%、50%、75%、max、null_countを返します。 文字列列の場合：count、unique、top value、frequency、null_countを返します。
結果のエクスポート
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/data.xlsx \
--action query \
--sql "SELECT * FROM Sheet1 WHERE amount > 1000" \
--output-file /mnt/user-data/outputs/filtered-results.csv
サポートされる出力形式（拡張子から自動検出）：
.csv— カンマ区切り値.json— レコードのJSON配列.md— Markdownテーブル
パラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
--files | はい | Excel/CSVファイルへのパス（スペース区切り） |
--action | はい | inspect、query、summary のいずれか |
--sql | queryの場合 | 実行するSQLクエリ |
--table | summaryの場合 | サマリーを生成するテーブル/シート名 |
--output-file | いいえ | 結果をエクスポートするパス（CSV/JSON/MD） |
[!NOTE] Pythonファイルを直接読まず、パラメータを指定して呼び出してください。
テーブル命名規則
- Excelファイル：各シートがシート名のテーブルになります（例：
Sheet1、Sales、Revenue） - CSVファイル：テーブル名は拡張子を除いたファイル名です（例：
data.csv→data） - 複数ファイル：すべてのファイルのすべてのテーブルが同じクエリコンテキストで利用可能になり、ファイル間のJOINが可能です
- 特殊文字：スペースや特殊文字を含むシート/ファイル名は自動的にサニタイズされます（スペース → アンダースコア）。数値で始まる名前や特殊文字を含む名前は二重引用符で囲んでください（例：
"2024_Sales"）
分析パターン
基本的な探索
-- 行数
SELECT COUNT(*) FROM Sheet1
-- 列のユニーク値
SELECT DISTINCT category FROM Sheet1
-- 値の分布
SELECT category, COUNT(*) as cnt FROM Sheet1 GROUP BY category ORDER BY cnt DESC
-- 日付範囲
SELECT MIN(date_col), MAX(date_col) FROM Sheet1
集計とグループ化
-- カテゴリと月ごとの売上
SELECT category, DATE_TRUNC('month', order_date) as month,
SUM(revenue) as total_revenue
FROM Sales
GROUP BY category, month
ORDER BY month, total_revenue DESC
-- 支出額トップ10の顧客
SELECT customer_name, SUM(amount) as total_spend
FROM Orders GROUP BY customer_name
ORDER BY total_spend DESC LIMIT 10
ファイル間のJOIN
-- 異なるファイルの売上と顧客情報を結合
SELECT s.order_id, s.amount, c.customer_name, c.region
FROM sales s
JOIN customers c ON s.customer_id = c.id
WHERE s.amount > 500
ウィンドウ関数
-- 累計と順位
SELECT order_date, amount,
SUM(amount) OVER (ORDER BY order_date) as running_total,
RANK() OVER (ORDER BY amount DESC) as amount_rank
FROM Sales
ピボット型分析
-- ピボット：カテゴリ別月次売上
SELECT category,
SUM(CASE WHEN MONTH(date) = 1 THEN revenue END) as Jan,
SUM(CASE WHEN MONTH(date) = 2 THEN revenue END) as Feb,
SUM(CASE WHEN MONTH(date) = 3 THEN revenue END) as Mar
FROM Sales
GROUP BY category
完全な例
ユーザーが sales_2024.xlsx（シート：Orders、Products、Customers）をアップロードし、「売上データを分析して、売上高トップの製品と月次の傾向を見せて」と依頼した場合。
ステップ1：ファイルの検査
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/sales_2024.xlsx \
--action inspect
ステップ2：売上高トップの製品
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/sales_2024.xlsx \
--action query \
--sql "SELECT p.product_name, SUM(o.quantity * o.unit_price) as total_revenue, SUM(o.quantity) as total_units FROM Orders o JOIN Products p ON o.product_id = p.id GROUP BY p.product_name ORDER BY total_revenue DESC LIMIT 10"
ステップ3：月次の売上傾向
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/sales_2024.xlsx \
--action query \
--sql "SELECT DATE_TRUNC('month', order_date) as month, SUM(quantity * unit_price) as revenue FROM Orders GROUP BY month ORDER BY month" \
--output-file /mnt/user-data/outputs/monthly-trends.csv
ステップ4：統計サマリー
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/sales_2024.xlsx \
--action summary \
--table Orders
結果を、発見事項、傾向、実用的な洞察の明確な説明とともにユーザーに提示します。
複数ファイルの例
ユーザーが orders.csv と customers.xlsx をアップロードし、「平均注文金額が最も高い地域はどこ？」と質問した場合：
python /mnt/skills/public/data-analysis/scripts/analyze.py \
--files /mnt/user-data/uploads/orders.csv /mnt/user-data/uploads/customers.xlsx \
--action query \
--sql "SELECT c.region, AVG(o.amount) as avg_order_value, COUNT(*) as order_count FROM orders o JOIN Customers c ON o.customer_id = c.id GROUP BY c.region ORDER BY avg_order_value DESC"
出力の処理
分析後：
- クエリ結果は、整形されたテーブルとして会話内に直接表示
- 大規模な結果の場合は、ファイルにエクスポートして
present_filesツールで共有 - 常に平易な言葉で発見事項を説明し、重要なポイントを示す
- 興味深いパターンが見られた場合は、フォローアップ分析を提案
- ユーザーが結果を保持したい場合、エクスポートを提案
キャッシュ
スクリプトは読み込んだデータを自動的にキャッシュし、呼び出しごとにファイルの再解析を回避します：
- 初回ロード時、ファイルは解析され、
/mnt/user-data/workspace/.data-analysis-cache/の下にある永続的なDuckDBデータベースに保存されます - キャッシュキーはすべての入力ファイルの内容のSHA256ハッシュです — ファイルが変更されると、新しいキャッシュが作成されます
- 同じファイルでの以降の呼び出しでは、キャッシュされたデータベースが直接使用されます（ほぼ瞬時に起動）
- キャッシュは透過的で、追加のパラメータは不要です
これは特に、同じデータファイルに対して複数のクエリ（inspect → query → summary）を実行する場合に便利です。
注記
- DuckDBはウィンドウ関数、CTE、サブクエリ、高度な集計を含む完全なSQLをサポートしています
- Excelの日付列は自動的に解析されます。DuckDBの日付関数（
DATE_TRUNC、EXTRACTなど）を使用してください - 非常に大きなファイル（100MB以上）の場合、DuckDBはすべてをメモリに読み込まず効率的に処理します
- スペースを含む列名は二重引用符でアクセスします：
"Column Name"