nocobase-data-analysis

目標

NocoBase MCP ツールを使用して適切なコレクションを特定し、ビジネスデータを安全にクエリして、信頼できる要約やグループ別分析を作成します。

前提条件

• NocoBase MCP に接続でき、認証済みである必要があります。
• Auth required などの認証エラーが MCP から返された場合は、処理を中止し、続行する前に MCP の認証を更新するようユーザーに依頼してください。

デフォルトの方針

1. まずデータソースのパスを確認します。
2. main データソースを優先します。
3. 対象のコレクションが main にない場合は、ほかの有効なデータソースを調べます。
4. コレクションを特定したら、それ以降のすべての resource_* 呼び出しで、その dataSource を明示的に指定します。
5. クエリのパラメーター仕様を確認してから、件数やグループ別分析には resource_query を優先して使用します。
6. クエリ結果に疑わしい点がある場合や、照合が必要な場合は、resource_list に切り替えて手動で集計します。

参考資料：

• 一般的なビジネス分析の形式については references/analysis-patterns.md
• 指標の定義と対象範囲の確認については references/metric-checklist.md
• ビジネス用語とコレクションおよびフィールドの対応付けについては references/entity-mapping.md

データソースの特定

• ユーザーがデータソースを明示した場合は、それを直接使用します。
• それ以外の場合は、main から開始します。
• 対象のコレクションが main に見つからない場合は、data_sources:list_enabled を呼び出し、有効なほかのデータソースを1つずつ確認します。
• 同じコレクション名が複数のデータソースにある場合：
  • main がそのうちの1つであれば、デフォルトで main を使用します。
  • そうでない場合は、候補を提示し、使用するデータソースを説明します。
• 最終回答では、使用したデータソースを明記します。

コレクションの特定

• ユーザーがコレクション名を指定した場合は、クエリを実行する前に、存在を確認します。
• 「見込み客」「ユーザー」「注文」「商談」などのビジネス用語が使われている場合は、コレクションのメタデータを調べて、実際のコレクション名を特定します。
• すばやく概要を把握するには、collections:listMeta を優先して使用します。
• 正確なフィールド名、リレーションの参照先、または列挙型の選択肢が必要な場合は、appends: ["fields"] を指定して collections:get を使用します。
• 一般的なビジネス用語と、想定されるフィールドのカテゴリを対応付ける際は、再利用可能なヒューリスティックとして references/entity-mapping.md を使用します。

クエリ仕様の確認

resource_query を使用する前に、リクエストの形式が実際のバックエンド仕様に合っていることを確認します。

• aggregate ではなく measures[].aggregation
• direction ではなく orders[].order
• field には、通常、["id"] や ["owner", "nickname"] などのフィールドパス配列を渡します。
• 結果を出力や having で参照する場合は、必ず alias を使用します。

正しい例：

{
  "resource": "lead",
  "dataSource": "main",
  "measures": [
    { "aggregation": "count", "field": ["id"], "alias": "lead_count" }
  ]
}

{
  "resource": "lead",
  "dataSource": "main",
  "dimensions": [
    { "field": ["status"], "alias": "status" }
  ],
  "measures": [
    { "aggregation": "count", "field": ["id"], "alias": "lead_count" }
  ],
  "orders": [
    { "field": ["status"], "alias": "status", "order": "asc" }
  ]
}

推奨ワークフロー

1. 接続を確認する

• auth:check を使用します。
• 認証に失敗した場合は、処理を中止します。

2. コレクションを特定する

• まず main を確認します。
• 見つからない場合は、有効なほかのデータソースを確認します。
• フィールド名やリレーションが不明な場合は、クエリを実行する前にフィールドを確認します。

3. 簡単な件数確認から始める

• count(id) のメジャーを1つ指定して resource_query を使用します。
• 最初のクエリは最小限にして、結果の形式をすばやく検証できるようにします。

4. グループ別分析を追加する

一般的なグループ別表示：

• ステータス別
• 担当者別
• ソース別
• 部門別
• 作成日別または月別

リレーションのラベルには、次のようなフィールドパスを使用します。

• ["owner", "nickname"]
• ["mainDepartment", "title"]

5. 必要に応じて照合する

次の場合は resource_list で再確認します。

• グループ化した行が予期せず重複している。
• 数値結果が件数ではなくレコード ID のように見える。
• 概要とグループ別の出力で合計が一致しない。
• コレクションが ACL の対象範囲や非表示のフィルターの影響を受けている可能性がある。

照合する場合：

• 表示されているデータセットを網羅できるだけの行を取得するか、ページネーションを使用します。
• 返されたレコードから手動で件数を数え、グループ分けします。
• 手動での結果と resource_query を比較します。

6. 結果を提示する

次の内容を報告します。

• 使用したコレクション
• 使用したデータソース
• 合計件数
• 主なグループ別内訳
• ACL の対象範囲、null 値、または手動検証への切り替えなどの注意点

分析の入り口

クエリを実行する前に、ユーザーのリクエストを分類してください。

• overview：現在の合計と主な分布
• distribution：ステータス、担当者、ソース、チーム、部門ごとのグループ別件数
• funnel：段階に基づくビジネスの進捗
• trend：日付または月ごとの経時的な変化
• ranking：担当者、ソース、アカウント、製品の上位
• quality-check：欠損値、null が多いフィールド、不審なステータス、孤立した関連

各パターンで推奨されるクエリ形式については、references/analysis-patterns.md を使用してください。

指標の定義チェック

回答を返す前に、指標の範囲を確認してください。

• 対象となる期間
• 期間の基準となる日付フィールド
• 指標が合計件数、ユニーク件数、合計値、平均値のいずれか
• アーカイブ済み、非アクティブ、null、その他の最終状態を含めるべきか
• グループ別の合計が総合計と一致するか

ユーザーのリクエストが曖昧な場合や、指標が複数の意味に解釈できる場合は、references/metric-checklist.md を使用してください。

よくある落とし穴

• コレクションが main にあると決めつけないでください。まず main を確認し、その後、他の有効なデータソースを検索してください。
• コレクションが見つかった後は、dataSource を省略しないでください。
• クエリのメジャーで aggregate を使用しないでください。バックエンドが想定しているのは aggregation です。
• クエリの orders で direction を使用しないでください。バックエンドが想定しているのは order です。
• 不審な集計結果を正しいと決めつけないでください。
• 「count」の結果が 36、54、80、またはその他の妥当そうなレコード ID のように見える場合は、集計が実際に適用されたかどうかを確認してください。
• 関連ラベルでグループ化するには、推測したラベルではなく、実際の関連パスと対象フィールドが必要です。

検証チェックリスト

• MCP が認証済みである。
• 選択したデータソースにコレクションが存在する。
• dimensions、measures、orders、filter で使用するフィールドが実際に存在する。
• resource_query で aggregation と order を使用している。
• 概要の合計とグループ別の合計が一致している。または、不一致の理由が説明されている。
• 最終回答にデータソースと、検証時に使用したフォールバックが記載されている。