nocobase-data-analysis

What this skill does

# Goal

Use NocoBase MCP tools to locate the right collection, query business data safely, and produce reliable summaries or grouped analysis.

# Prerequisite

- NocoBase MCP must already be reachable and authenticated.
- If MCP returns authentication errors such as `Auth required`, stop and ask the user to refresh MCP authentication before continuing.

# Default strategy

1. Inspect the data source path first.
2. Prefer the `main` data source.
3. If the target collection is not in `main`, inspect other enabled data sources.
4. Once the collection is located, use that `dataSource` explicitly in every subsequent `resource_*` call.
5. Prefer `resource_query` for counts and grouped analysis only after confirming the query parameter contract.
6. Fall back to `resource_list` plus manual counting when query results are suspicious or need cross-checking.

Useful references:

- `references/analysis-patterns.md` for common business analysis shapes
- `references/metric-checklist.md` for metric definition and scope checks
- `references/entity-mapping.md` for mapping business terms to collections and fields

# Data source discovery

- If the user explicitly names a data source, use it directly.
- Otherwise start with `main`.
- When the target collection is not found in `main`, call `data_sources:list_enabled` and inspect other enabled data sources one by one.
- If multiple data sources contain the same collection name:
  - default to `main` when `main` is one of them;
  - otherwise present the candidates and explain which one you are using.
- In the final answer, state which data source was used.

# Collection discovery

- If the user gives a collection name, verify it exists before querying.
- If the user uses business terms such as "leads", "users", "orders", or "opportunities", inspect collection metadata to map the business term to the actual collection name.
- Prefer `collections:listMeta` for a fast overview.
- Then use `collections:get` with `appends: ["fields"]` when you need exact field names, relation targets, or enum options.
- Use `references/entity-mapping.md` as a reusable heuristic for common business nouns and likely field categories.

# Query contract checks

Before using `resource_query`, verify the request shape matches the real backend contract:

- `measures[].aggregation`, not `aggregate`
- `orders[].order`, not `direction`
- `field` should usually be passed as a field path array such as `["id"]` or `["owner", "nickname"]`
- Use `alias` whenever the result will be referenced in output or `having`

Correct examples:

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

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

# Recommended workflow

## 1. Confirm reachability

- Use `auth:check`.
- If authentication fails, stop.

## 2. Find the collection

- First inspect `main`.
- If not found, inspect other enabled data sources.
- Read fields before querying if field names or relations are uncertain.

## 3. Start with simple counts

- Use `resource_query` with a single `count(id)` measure.
- Keep the first query minimal so you can validate the result shape quickly.

## 4. Add grouped analysis

Common grouped views:

- by status
- by owner
- by source
- by department
- by created date or month

For relation labels, use field paths such as:

- `["owner", "nickname"]`
- `["mainDepartment", "title"]`

## 5. Cross-check when needed

Re-check with `resource_list` when:

- the grouped rows look duplicated unexpectedly;
- the numeric result looks like record IDs instead of counts;
- totals do not match between summary and grouped output;
- the collection may be affected by ACL scope or hidden filters.

When cross-checking:

- fetch enough rows to cover the visible dataset or use pagination;
- count and group manually from the returned records;
- compare the manual result with `resource_query`.

## 6. Present the result

Report:

- the collection used;
- the data source used;
- the total count;
- the key grouped breakdowns;
- any caveat such as ACL scope, null values, or fallback to manual verification.

# Analysis entry points

Classify the user request before querying:

- `overview` for current totals and main distributions
- `distribution` for grouped counts by status, owner, source, team, or department
- `funnel` for stage-based business progression
- `trend` for date or month-based change over time
- `ranking` for top owners, sources, accounts, or products
- `quality-check` for missing values, null-heavy fields, suspicious statuses, or orphaned relations

Use `references/analysis-patterns.md` for the recommended query shapes for each pattern.

# Metric definition checks

Before returning an answer, verify the metric scope:

- what time range is included
- which time field drives the range
- whether the metric is total count, distinct count, sum, or average
- whether archived, inactive, null, or other terminal states should be included
- whether grouped totals reconcile with the grand total

Use `references/metric-checklist.md` when the user request is ambiguous or the metric may be interpreted in more than one way.

# Common pitfalls

- Do not assume the collection is in `main`; check `main` first, then search other enabled data sources.
- Do not omit `dataSource` after the collection has been located.
- Do not use `aggregate` in query measures; the backend expects `aggregation`.
- Do not use `direction` in query orders; the backend expects `order`.
- Do not assume suspicious aggregate output is correct.
- If a "count" result looks like `36`, `54`, `80`, or another plausible record ID, verify whether aggregation was actually applied.
- Relation label grouping requires the real relation path and target field, not guessed labels.

# Verification checklist

- MCP is authenticated.
- The collection exists in the chosen data source.
- The fields used in `dimensions`, `measures`, `orders`, and `filter` actually exist.
- `resource_query` uses `aggregation` and `order`.
- Summary totals match grouped totals, or any mismatch is explained.
- The final answer states the data source and any verification fallback used.