データ分析スキル

概要

このスキルは DuckDB を使用してユーザーがアップロードした Excel/CSV ファイルを分析します。DuckDB はインプロセス分析 SQL エンジンです。スキーマ検査、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、最頻値、頻度、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	Yes	スペース区切りの Excel/CSV ファイルパス
--action	Yes	inspect、query、summary のいずれか
--sql	query の場合	実行する SQL クエリ
--table	summary の場合	サマリー対象のテーブル/シート名
--output-file	No	結果をエクスポートするパス (CSV/JSON/MD)

[!NOTE] Python ファイルを読むのではなく、パラメータを指定して呼び出すだけです。

テーブルの命名ルール

• Excel ファイル: 各シートはシート名が付いたテーブルになります (例: Sheet1, Sales, Revenue)
• CSV ファイル: テーブル名は拡張子なしのファイル名です (例: data.csv → data)
• 複数ファイル: すべてのファイルのすべてのテーブルが同一クエリコンテキストで使用可能であり、ファイル間の結合が可能です
• 特殊文字: スペースまたは特殊文字を含むシート/ファイル名は自動的にサニタイズされます (スペース → アンダースコア)。数字で始まる名前や特殊文字を含む名前の場合はダブルクォートを使用します。例: "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

ファイル間の結合

-- 異なるファイルの顧客情報と売上を結合
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 ハッシュです。ファイルが変更されると、新しいキャッシュが作成されます
• 同じファイルでの後続呼び出しはキャッシュされたデータベースを直接使用します (ほぼ瞬時のスタートアップ)
• キャッシュは透過的です。追加パラメータは不要です

これは同じデータファイルに対して複数のクエリを実行する場合 (検査 → クエリ → サマリー) に特に便利です。

注記

• DuckDB はウィンドウ関数、CTE、サブクエリ、高度な集約を含む完全な SQL をサポートしています
• Excel の日付列は自動的に解析されます。DuckDB の日付関数 (DATE_TRUNC、EXTRACT など) を使用します
• 非常に大きなファイル (100MB 以上) の場合、DuckDB はメモリにすべてをロードせずに効率的に処理します
• スペースを含む列名はダブルクォートを使用してアクセスできます: "Column Name"