explore-data

/explore-data - データセットのプロファイリングと探索

見慣れないプレースホルダーがある場合や、接続されているツールを確認する必要がある場合は、CONNECTORS.md を参照してください。

テーブルまたはアップロードされたファイルの包括的なデータプロファイルを生成します。分析に取りかかる前に、その形状、品質、パターンを把握します。

使用方法

/explore-data <table_name or file>

ワークフロー

1. データにアクセスする

データウェアハウスの MCP サーバーが接続されている場合：

1. テーブル名を解決します（スキーマのプレフィックスに対応し、あいまいな場合は候補を提示します）
2. テーブルのメタデータをクエリします：列名、型、利用可能な場合は説明
3. ライブデータに対してプロファイリングクエリを実行します

ファイル（CSV、Excel、Parquet、JSON）が提供されている場合：

1. ファイルを読み込み、作業用データセットにロードします
2. データから列の型を推測します

どちらでもない場合：

1. テーブル名を提示する（データウェアハウスに接続した状態で）か、ファイルをアップロードするようユーザーに依頼します
2. テーブルスキーマの説明がある場合は、実行すべきプロファイリングクエリを案内します

2. 構造を把握する

データを分析する前に、その構造を把握します。

テーブルレベルの質問：

• 行と列はいくつありますか？
• 粒度は何ですか（1行は何を表しますか）？
• 主キーは何ですか？一意ですか？
• データが最後に更新されたのはいつですか？
• データはどの時点まで遡りますか？

列の分類 — 各列を次のいずれかに分類します：

• 識別子：一意キー、外部キー、エンティティ ID
• ディメンション：グループ化やフィルタリングに使うカテゴリ属性（ステータス、種類、地域、カテゴリ）
• 指標：測定に使う定量値（収益、件数、期間、スコア）
• 時間：日付とタイムスタンプ（created_at、updated_at、event_date）
• テキスト：自由形式のテキストフィールド（説明、メモ、名前）
• ブール値：真偽値フラグ
• 構造化データ：JSON、配列、ネスト構造

3. データプロファイルを生成する

次のプロファイリングチェックを実行します。

テーブルレベルの指標：

• 行の総数
• 列数と型の内訳
• テーブルのおおよそのサイズ（メタデータから取得可能な場合）
• 日付範囲（日時列の最小値／最大値）

すべての列：

• NULL の件数と割合
• 個別値の件数とカーディナリティ比（個別値の数／合計数）
• 最も一般的な値（頻度付きで上位 5～10 件）
• 最も一般的でない値（異常値を見つけるための下位 5 件）

数値列（指標）：

min, max, mean, median (p50)
standard deviation
percentiles: p1, p5, p25, p75, p95, p99
zero count
negative count (if unexpected)

文字列列（ディメンション、テキスト）：

min length, max length, avg length
empty string count
pattern analysis (do values follow a format?)
case consistency (all upper, all lower, mixed?)
leading/trailing whitespace count

日付／タイムスタンプ列：

min date, max date
null dates
future dates (if unexpected)
distribution by month/week
gaps in time series

ブール値列：

true count, false count, null count
true rate

プロファイルは、列の型（ディメンション、指標、日付、ID）ごとにまとめた、見やすい要約テーブルとして提示します。

4. データ品質の問題を特定する

以下の品質評価フレームワークを適用し、潜在的な問題にフラグを付けます。

• NULL 率が高い：NULL が 5% を超える列（警告）、20% を超える列（アラート）
• 想定外の低カーディナリティ：高カーディナリティであるべき列のカーディナリティが低い（例：user_id の個別値が 50 件しかない）
• 想定外の高カーディナリティ：カテゴリ列であるべき列の個別値が多すぎる
• 疑わしい値：正の値だけが想定される項目の負の金額、過去データに含まれる未来の日付、明らかなプレースホルダー値（例：「N/A」、「TBD」、「test」、「999999」）
• 重複の検出：自然キーがあるか、また重複があるかを確認します
• 分布の偏り：平均値に影響する可能性のある、極端に偏った数値分布
• エンコーディングの問題：カテゴリ項目の大文字・小文字の混在、末尾の空白、一貫性のない形式

5. 関係とパターンを見つける

個々の列のプロファイリング後、次の項目を確認します。

• 外部キー候補：他のテーブルとの関連付けに使われる可能性のある ID 列
• 階層：自然なドリルダウン経路を構成する列（国 > 州 > 市）
• 相関関係：連動して変化する数値列
• 派生列：他の列から計算されているように見える列
• 冗長な列：同一またはほぼ同一の情報を持つ列

6. 興味深いディメンションと指標を提案する

列のプロファイルに基づいて、次の項目を提案します。

• 最適なディメンション列：データの切り分けに使える列（カーディナリティが適度なカテゴリ列、値が3～50個）
• 主要な指標列：測定に使える列（意味のある分布を持つ数値列）
• トレンド分析に適した時間列
• データから見て取れる自然なグループ分けや階層
• 他のテーブルとの結合に使える可能性があるキー（ID 列、外部キー）

7. 次に行う分析を提案する

ユーザーが次に実行できる具体的な分析を3～5件提案します。

• 「[metric] を [dimension] でグループ化し、[time_column] 別にトレンド分析する」
• 「外れ値の原因を把握するため、[skewed_column] の分布を詳しく分析する」
• 「[problematic_column] のデータ品質を調査する」
• 「[metric_a] と [metric_b] の相関を分析する」
• 「[date_column] と [status_column] を使ってコホート分析を行う」

出力形式

## Data Profile: [table_name]

### Overview
- Rows: 2,340,891
- Columns: 23 (8 dimensions, 6 metrics, 4 dates, 5 IDs)
- Date range: 2021-03-15 to 2024-01-22

### Column Details
[summary table]

### Data Quality Issues
[flagged issues with severity]

### Recommended Explorations
[numbered list of suggested follow-up analyses]

---

品質評価フレームワーク

完全性スコア

各列を評価します。

• 完全（null 以外が99%超）：緑
• おおむね完全（95～99%）：黄 — null 値を調査する
• 不完全（80～95%）：オレンジ — 理由と影響の有無を確認する
• 疎（80%未満）：赤 — 補完しないと使用できない可能性がある

一貫性チェック

次の点を確認します。

• 値の形式の不一致：同じ概念が異なる形式で表されている（「USA」、「US」、「United States」、「us」）
• 型の不一致：数値が文字列として格納されている、日付の形式が複数ある
• 参照整合性：一致する親レコードがない外部キー
• ビジネスルール違反：負の数量、終了日が開始日より前、100%を超える割合
• 列間の整合性：status = "completed" なのに completed_at が null

正確性の指標

正確性に問題があることを示す危険信号：

• プレースホルダー値：0、-1、999999、「N/A」、「TBD」、「test」、「xxx」
• デフォルト値：単一の値の頻度が不自然に高い
• 古いデータ：アクティブなシステムなのに、Updated_at に最近の変更が反映されていない
• あり得ない値：150歳を超える年齢、遠い未来の日付、負の期間
• 端数の偏り：すべての値が0または5で終わる（測定ではなく推定を示唆）

適時性の評価

• テーブルが最後に更新されたのはいつですか？
• 想定される更新頻度はどのくらいですか？
• イベント時刻とロード時刻の間に遅延はありますか？
• 時系列に欠落はありますか？

パターン発見の手法

分布分析

数値列について、分布の特徴を把握します。

• 正規分布：平均値と中央値が近く、釣鐘型
• 右に歪んだ分布：大きな値が長い裾を引く（収益、セッション時間などでよく見られる）
• 左に歪んだ分布：小さな値が長い裾を引く（あまり一般的ではない）
• 二峰性：ピークが2つある（異なる2つの母集団を示唆）
• べき乗則：非常に大きな値は少なく、小さな値は多い（ユーザーのアクティビティでよく見られる）
• 一様分布：範囲全体で頻度がほぼ等しい（人工データやランダムデータでよく見られる）

時系列パターン

時系列データについて、次の点を確認します。

• トレンド：持続的な上昇または下降の動き
• 季節性：繰り返し現れるパターン（週次、月次、四半期、年次）
• 曜日の影響：平日と週末の違い
• 祝日の影響：既知の祝日の前後に見られる減少や急増
• 変化点：水準やトレンドの急激な変化
• 異常値：パターンから外れる個々のデータ点

セグメントの発見

次の方法で自然なセグメントを特定します。

• 異なる値が3～20個あるカテゴリ列を見つける
• セグメントの値ごとに指標の分布を比較する
• 挙動が大きく異なるセグメントを探す
• セグメントが均質か、サブセグメントを含むかを検証する

相関の探索

数値列間で次の分析を行います。

• すべての指標ペアについて相関行列を計算する
• 強い相関（|r| > 0.7）を調査対象として示す
• 注意：相関は因果関係を意味するものではありません — この点を明示します
• 非線形の関係（例：二次関数、対数関数）を確認する

スキーマの理解とドキュメント化

スキーマドキュメントのテンプレート

チームで使用するデータセットをドキュメント化する場合：

## Table: [schema.table_name]

**Description**: [What this table represents]
**Grain**: [One row per...]
**Primary Key**: [column(s)]
**Row Count**: [approximate, with date]
**Update Frequency**: [real-time / hourly / daily / weekly]
**Owner**: [team or person responsible]

### Key Columns

| Column | Type | Description | Example Values | Notes |
|--------|------|-------------|----------------|-------|
| user_id | STRING | Unique user identifier | "usr_abc123" | FK to users.id |
| event_type | STRING | Type of event | "click", "view", "purchase" | 15 distinct values |
| revenue | DECIMAL | Transaction revenue in USD | 29.99, 149.00 | Null for non-purchase events |
| created_at | TIMESTAMP | When the event occurred | 2024-01-15 14:23:01 | Partitioned on this column |

### Relationships
- Joins to `users` on `user_id`
- Joins to `products` on `product_id`
- Parent of `event_details` (1:many on event_id)

### Known Issues
- [List any known data quality issues]
- [Note any gotchas for analysts]

### Common Query Patterns
- [Typical use cases for this table]

スキーマの確認クエリ

データウェアハウスに接続している場合は、次のパターンを使ってスキーマを確認します：

-- List all tables in a schema (PostgreSQL)
SELECT table_name, table_type
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

-- Column details (PostgreSQL)
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'my_table'
ORDER BY ordinal_position;

-- Table sizes (PostgreSQL)
SELECT relname, pg_size_pretty(pg_total_relation_size(relid))
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

-- Row counts for all tables (general pattern)
-- Run per-table: SELECT COUNT(*) FROM table_name

リネージと依存関係

見慣れないデータ環境を調べる場合：

1. 「出力」テーブルから始めます（レポートやダッシュボードが利用するテーブルです）
2. 上流をたどります：どのテーブルがそれらにデータを提供していますか？
3. raw／staging／mart レイヤーを特定します
4. raw データから分析テーブルまでの変換チェーンをマッピングします
5. データが拡充、フィルタリング、集計される箇所を記録します

ヒント

• 非常に大きなテーブル（1億行以上）では、プロファイリングクエリはデフォルトでサンプリングを使用します。正確な件数が必要な場合は、その旨を伝えてください
• 新しいデータセットを初めて調べる場合、このコマンドを使うと、具体的なクエリを書く前に全体像を把握できます
• 品質フラグはヒューリスティックです。すべてのフラグが実際の問題を示すわけではありませんが、どれも一度は確認する価値があります