data-analysis

データ分析スキル

概要

このスキルでは、プロセス内で動作する分析用 SQL エンジンである DuckDB を使用して、ユーザーがアップロードした Excel/CSV ファイルを分析します。スキーマの確認、SQL によるクエリ、統計要約、結果のエクスポートに対応しており、すべて単一の Python スクリプトから実行できます。

環境のセットアップ

分析を実行する前に、Python 環境を準備してください。スクリプトの実行に使用するものと同じインタープリターを使って、必要なパッケージを明示的にインストールします。

python -m pip install duckdb openpyxl

いずれかのパッケージが不足している場合、スクリプトはセットアップ手順を表示して終了します。インストーラーを実行したり、環境を変更したりすることはありません。ファイルの読み込みに使用する DuckDB の既存の空間拡張機能のセットアップに変更はありません。

主な機能

• 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 テーブル

相対出力パスは、現在の作業ディレクトリを基準に解決されます。report.csv のようにファイル名だけを指定すると、その場所に直接書き込みます。reports/report.csv のようなパスで親ディレクトリが存在しない場合は、自動的に作成されます。 出力先にファイルがすでに存在する場合、警告なしで上書きされます。

JSON の結果では、列名が一意である必要があります。同じ名前が繰り返される場合は、たとえば SELECT a.id AS left_id, b.id AS right_id FROM ... のように、明示的な SQL エイリアスを使用してください。 列名が重複しているとエラーになり、既存の出力ファイルは変更されません。エラーには重複している名前が一覧表示されるため、直接エイリアスを指定できます。この拒否が発生すると、CLI は短い Error: ... メッセージを標準エラーに出力し、0 以外の終了コードで終了します。

JSON エクスポートでは、出力ファイルを開く前に、リストや構造体の内部に含まれる値も含めて、有限ではない数値（NaN、Infinity、-Infinity）も拒否されます。SQL でフィルタリングするか、たとえば CASE WHEN isfinite(ratio) THEN ratio ELSE NULL END AS ratio のように置き換えてください。有限の数値、NULL、'NaN' のようなテキストは有効です。

パラメーター

パラメーター	必須	説明
--files	はい	Excel/CSV ファイルのパス（スペース区切り）
--action	はい	次のいずれか：inspect、query、summary
--sql	query の場合	実行する SQL クエリ
--table	summary の場合	要約するテーブル／シート名
--output-file	いいえ	結果をエクスポートするパス（CSV/JSON/MD）

メモ

Python ファイルを読み込まず、パラメーターを指定して呼び出してください。

テーブル名の規則

• Excel ファイル：各シートがテーブルになり、シート名がテーブル名になります（例：Sheet1、Sales、Revenue）
• CSV ファイル：拡張子を除いたファイル名がテーブル名になります（例：data.csv → data）
• 複数のファイル：すべてのファイルのテーブルが同じクエリコンテキストで利用でき、ファイルをまたいだ結合が可能です
• 名前の重複：大文字と小文字だけが異なる場合も含め、名前が重複すると、入力順に report、report_1、report_2 のような一意の SQL 名が割り当てられます。これは Excel のシート名が重複する場合にも適用されます。クエリや概要の作成には、inspect に表示される SQL 名を使用してください。元の名前のエイリアスが、先に割り当てられた SQL 名を上書きすることはありません。
• 特殊文字：シート名やファイル名は SQL 名に変換されます（例：sales-2026 → sales_2026）。inspect に表示される SQL 名を使用するか、一意の元の名前を二重引用符で囲んでください（例：SELECT * FROM "sales-2026"）。クエリは変更されずに実行されます。文字列リテラル、列エイリアス、コメント、CTE は、通常の DuckDB のセマンティクスに従います。二重引用符を含む名前では、二重引用符を重ねてエスケープします（例："net""amount"）

分析パターン

基本的なデータ探索

-- Row count
SELECT COUNT(*) FROM Sheet1

-- Distinct values in a column
SELECT DISTINCT category FROM Sheet1

-- Value distribution
SELECT category, COUNT(*) as cnt FROM Sheet1 GROUP BY category ORDER BY cnt DESC

-- Date range
SELECT MIN(date_col), MAX(date_col) FROM Sheet1

集計とグループ化

-- Revenue by category and month
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

-- Top 10 customers by spend
SELECT customer_name, SUM(amount) as total_spend
FROM Orders GROUP BY customer_name
ORDER BY total_spend DESC LIMIT 10

ファイルをまたいだ結合

-- Join sales with customer info from different files
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

ウィンドウ関数

-- Running total and rank
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

ピボット形式の分析

-- Pivot: monthly revenue by category
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 ツールで共有します
• 重要なポイントを含め、わかりやすい言葉で必ず結果を説明します
• 興味深いパターンが見られた場合は、追加分析を提案します
• ユーザーが結果を保存したい場合は、エクスポートを提案します

キャッシュ

このスクリプトは、呼び出しのたびにファイルを再解析しなくて済むよう、読み込んだデータを自動的にキャッシュします。

• 初回の読み込み時にファイルを解析し、システムの一時ディレクトリ（.data-analysis-cache/）内の永続的な DuckDB データベースに保存します
• キャッシュキーは、入力されたファイルのベース名の順序と、各ファイルの個別の SHA256 ダイジェストをハッシュ化したものです。名前変更、順序変更、入力内容の変更があると新しいキャッシュが作成されます。変更のない同名の入力ファイルを別のディレクトリに移動しても、キャッシュは再利用されます。更新後のキー名前空間では以前のキャッシュ済みテーブルマップを無視し、初回使用時に再構築します
• 同じファイルを使った以降の呼び出しでは、キャッシュ済みのデータベースを直接使用します（起動はほぼ瞬時です）
• キャッシュは自動的に処理されるため、追加のパラメーターは必要ありません

これは、同じデータファイルに対して複数のクエリを実行する場合（inspect → query → summary）に特に便利です。

注意事項

• DuckDB は、ウィンドウ関数、CTE、サブクエリ、高度な集計を含む完全な SQL に対応しています
• Excel の日付列は自動的に解析されます。DuckDB の日付関数（DATE_TRUNC、EXTRACT など）を使用してください
• 非常に大きなファイル（100MB 以上）でも、すべてをメモリに読み込まずに DuckDB が効率的に処理します
• スペースを含む列名には、二重引用符を使ってアクセスできます："Column Name"