feat(mcp): return the Big Number headline from chart and dashboard data

[aminghadersohi]

SUMMARY

get_dashboard_data returns only the first few sample rows of each chart, and get_chart_data returns the raw rows. A Big Number chart displays one headline number derived from its data, so an assistant asked "what is the total?" could only list sample rows and had no number to report. For example, a Big Number with trendline over SUM(ytd_sales), weekly grain, aggregation sum, 19 rows: the tool returned ten weekly values and no total.

This adds a typed headline object to ChartData (get_chart_data) and to each chart in get_dashboard_data, set for big_number and big_number_total and null for every other chart type. It is computed from the full executed result set, not the sample rows, with the same logic as the frontend (aggregationChoices in customControls.tsx, BigNumberWithTrendline/transformProps.ts, BigNumberTotal/transformProps.ts):

• big_number_total: the single metric value.
• big_number: metric values ordered by time descending, nulls dropped, then form_data.aggregation: LAST_VALUE (default) is the latest value; sum, mean, min, max, median are that statistic over all values. The aggregation name lookup is case-insensitive with a LAST_VALUE fallback, as in the frontend. raw ("Overall value") is read from the second, un-trended query layer, and only for the exact string raw, which is the only value for which the frontend adds that layer.

headline fields: value, aggregation, rows_used, reason. Rather than return a wrong number, value is null with a short reason when:

• the fetch hit the row limit (or the source reports more rows than were returned);
• aggregation is raw and no overall-value layer came back;
• a rolling window (rolling_type) is configured but the executed query has no rolling/cumulative step, so the returned rows do not reflect it;
• LAST_VALUE is requested but the rows have no usable time values to find the latest one;
• the result is empty, the metric column is missing, or every value is null.

The query path is unchanged, so permissions, RLS and dashboard filters apply exactly as they do for the existing chart query. The tool descriptions tell the model to report headline.value rather than derive a number from the rows.

Known difference from the frontend: when the raw overall-value query returns null, the chart falls back to showing the latest trend value; here that case returns no headline.

get_chart_data is included because the headline is computed inside the shared execute_chart_data core, which has the form data and the executed query, so it fit without extra plumbing.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A (MCP tool response change).

TESTING INSTRUCTIONS

pytest tests/unit_tests/mcp_service/chart/test_big_number_headline.py \
  tests/unit_tests/mcp_service/chart/tool/test_get_chart_data.py \
  tests/unit_tests/mcp_service/dashboard/tool/test_get_dashboard_data.py

Manually: call get_dashboard_data (or get_chart_data) on a dashboard with a Big Number with trendline chart using aggregation sum; headline.value should equal the number rendered in the chart, and match the total of all trend rows, not just the sample rows.

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API
• Removes existing feature or API

[codecov]

Codecov Report

❌ Patch coverage is 90.55556% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.33%. Comparing base (549508b) to head (a8cf46f).
⚠️ Report is 32 commits behind head on master.

Files with missing lines	Patch %	Lines
superset/mcp_service/chart/big_number_headline.py	89.63%	12 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #44948      +/-   ##
==========================================
+ Coverage   82.28%   82.33%   +0.04%     
==========================================
  Files        2996     2997       +1     
  Lines      185109   185509     +400     
  Branches    42834    42922      +88     
==========================================
+ Hits       152316   152730     +414     
+ Misses      30031    30021      -10     
+ Partials     2762     2758       -4     

Flag	Coverage Δ
hive	36.27% <24.44%> (-0.03%)	⬇️
mysql	55.22% <24.44%> (-0.11%)	⬇️
postgres	55.23% <24.44%> (-0.11%)	⬇️
presto	38.14% <24.44%> (-0.04%)	⬇️
python	86.30% <90.55%> (+0.07%)	⬆️
sqlite	54.95% <24.44%> (-0.11%)	⬇️
unit	79.33% <90.55%> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bito-code-review]

Code Review Agent Run #4a861d

Actionable Suggestions - 3

• superset/mcp_service/chart/tool/get_chart_data.py - 1

  • AttributeError on empty form_data · Line 1081-1081
• superset/mcp_service/chart/big_number_headline.py - 2

  • Missing docstring on new function · Line 73-74
  • OverflowError on huge ints · Line 120-121

Additional Suggestions - 6

• superset/mcp_service/chart/big_number_headline.py - 5

  • Untyped lambdas in aggregation map · Line 54-60
    The seven lambdas in `_AGGREGATIONS` are untyped lambda expressions; BITO.md adaptive rule 13350 asks for named helpers with explicit parameter/return hints. The dict's `Callable[[list[float]], float | None]` annotation gives mypy context, but named helpers (e.g. `_first_value`, `_mean`) would satisfy the rule and match the module's typed-function style.
  • Duplicated epoch-ms conversion · Line 107-109
    The naive-datetime -> UTC -> epoch-ms conversion is duplicated verbatim: `_parse_date_ms` (lines 107-109) and `_parse_metric_value`'s datetime branch (lines 123-125). Extracting one `_datetime_to_ms` helper keeps this JSON-safety conversion in a single place as the mirroring logic evolves.
  • Redundant timestamp parsing · Line 268-268
    When `newest_first` is False (sum/mean/min/max/median chosen in `compute_big_number_headline`), `_timestamp_ms` still parses every row's x-axis value, and the timestamps are discarded by the `not newest_first` return at line 270-271. Gate the parse on `newest_first` to skip the per-row `datetime.fromisoformat` work on large series.
  • Dynamically typed expression disallowed · Line 77-77
    `query_context` is typed as `Any` in `executed_query_facts`, which is disallowed by ANN401. Similar `Any` usages exist at lines 112 and 131 for `value` parameters. Consider defining a Protocol for the query context or adding `# noqa: ANN401` comments.
  • datetime called without tzinfo · Line 135-135
    `datetime(value.year, value.month, value.day)` is called without a `tzinfo` argument (DTZ001). Add `tzinfo=datetime.UTC`.
• tests/unit_tests/mcp_service/chart/tool/test_get_chart_data.py - 1

  • Missing test docstrings · Line 3626-3707
    BITO.md adaptive rule 12148 requires every new test function to carry a docstring; all six `TestBigNumberHeadline` test methods (and the `_chart`/`_headline`/`_query` helpers) have none, while 55 of 77 existing test functions in this file do. Add one-line docstrings stating scenario and expected outcome, e.g. for `test_headline_aggregates_every_row`: "Sum aggregation aggregates every returned row, not a sample."

Filtered by Review Rules

Bito filtered these suggestions based on rules created automatically for your feedback. Manage rules.

• superset/mcp_service/chart/big_number_headline.py - 1

  • rows_used misreports raw layer · Line 224-224

Review Details

• Files reviewed - 8 · Commit Range: 5b993d6..5b993d6

  • superset/mcp_service/chart/big_number_headline.py
  • superset/mcp_service/chart/schemas.py
  • superset/mcp_service/chart/tool/get_chart_data.py
  • superset/mcp_service/dashboard/schemas.py
  • superset/mcp_service/dashboard/tool/get_dashboard_data.py
  • tests/unit_tests/mcp_service/chart/test_big_number_headline.py
  • tests/unit_tests/mcp_service/chart/tool/test_get_chart_data.py
  • tests/unit_tests/mcp_service/dashboard/tool/test_get_dashboard_data.py
• Files skipped - 0
• Tools

  • MyPy (Static Code Analysis) - ✔︎ Successful
  • Astral Ruff (Static Code Analysis) - ✔︎ Successful
  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[netlify]

✅ Deploy Preview for superset-docs-preview ready!

Name	Link
🔨 Latest commit	1c3f0ef
🔍 Latest deploy log	https://app.netlify.com/projects/superset-docs-preview/deploys/6ac3f78da4556a0008b37749
😎 Deploy Preview	https://deploy-preview-44948--superset-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[aminghadersohi]

Verdict: FINDINGS — P2 fixed in 8ee4462; no remaining PR defects found.

Reviewed live 0cb0e41 against master. Saved-chart requests with unsaved visualization changes used the saved type for headline computation, returning a wrong or missing headline. Fixed to use the active form-data type; all four regression cases fail before the fix and pass afterward.

Verified the four fixes in 0cb0e41; the separate empty-dict finding is invalid. Existing edge-case regressions fail against the pre-fix implementation. Checked partial form data, trend/comparison behavior, query failures, and truncation.

Validation: 274 touched-file tests and 224 relevant tests pass; changed-file and staged pre-commit pass. Full suite at 0cb0e41: 6,948 passed, 4 skipped, 4 unrelated failures (three FastMCP caching incompatibilities; missing trino).

[aminghadersohi]

CLEAN — re-checked 0cb0e41..8ee4462. The prior P2 is closed: unsaved visualization changes determine the headline; saved-type fallback and empty form data remain safe. No new defects found; no changes needed.

Validation: 274 touched-file tests passed. Full MCP suite: 6,952 passed, 4 skipped, 4 unrelated failures (three FastMCP caching incompatibilities; missing trino). Pre-commit passed on all branch-changed files.

[bito-code-review]

Code Review Agent Run #34d03c

Actionable Suggestions - 1

• superset/mcp_service/chart/big_number_headline.py - 1

  • Unstable sort wrong headline · Line 295-305

Additional Suggestions - 1

• superset/mcp_service/chart/big_number_headline.py - 1

  • Unchecked aggregate label · Line 151-158
    The new SIMPLE branch formats `f"{metric.get('aggregate')}({column['columnName']})"` without checking `aggregate` is truthy. If a SIMPLE adhoc metric has a `columnName` but no `aggregate`, this returns the malformed label `None(ytd_sales)`, which will not match the result column and makes the headline unavailable. `get_metric_name` guards `if column and aggregate`; this branch should too.

Review Details

• Files reviewed - 5 · Commit Range: 5b993d6..8ee4462

  • docs/admin_docs/configuration/mcp-server.mdx
  • superset/mcp_service/chart/big_number_headline.py
  • tests/unit_tests/mcp_service/chart/test_big_number_headline.py
  • superset/mcp_service/chart/tool/get_chart_data.py
  • tests/unit_tests/mcp_service/chart/tool/test_get_chart_data.py
• Files skipped - 0
• Tools

  • MyPy (Static Code Analysis) - ✔︎ Successful
  • Astral Ruff (Static Code Analysis) - ✔︎ Successful
  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

Code Review Agent Run #51843f

Actionable Suggestions - 0

Review Details

• Files reviewed - 3 · Commit Range: 8ee4462..5a930fd

  • docs/admin_docs/configuration/mcp-server.mdx
  • superset/mcp_service/chart/big_number_headline.py
  • tests/unit_tests/mcp_service/chart/test_big_number_headline.py
• Files skipped - 0
• Tools

  • MyPy (Static Code Analysis) - ✔︎ Successful
  • Astral Ruff (Static Code Analysis) - ✔︎ Successful
  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[gabotorresruiz]

Hey @aminghadersohi, thanks for this one. I like the shape a lot: computing from the executed result instead of the sample rows is the right call, and returning value: null with a reason rather than a plausible number is exactly the contract an agent needs. I checked the refusal paths behave that way (empty result, all null series, missing metric column, null total all come back null with a reason, never 0) and that a denied principal gets a ChartError with no headline key at all, since the value is only computed after validate_chart_dataset and guest_scope.authorize_query, from rows the query already filtered. I am requesting changes on one thing only: the exactness guard covers rolling_type but not resample_*, and in that case the tool hands back a number the chart does not show. Details inline, plus a question about the undated timestamp path.

What I ran on 5a930fd:

• tests/unit_tests/mcp_service/chart and tests/unit_tests/mcp_service/dashboard: 3576 passed, 3 skipped.
• test_dashboard_scope.py, test_dashboard_scope_sql.py, test_rbac_tool_enforcement.py: 267 passed.
• The three new test files copied onto the parent commit 549508b: the two new modules do not import there, and all 10 TestBigNumberHeadline cases fail, so the regression tests are real rather than invariant pins.
• A list_tools schema dump on both commits with middleware on: 78 tools each, no tool renamed, no required entry, enum member, default or nullability lost. The only delta is the additive headline object on the get_chart_data and get_dashboard_data outputs.

CI is fully green on this head, 43 passing checks and no failures.

[bito-code-review]

Code Review Agent Run #fb3ebe

Actionable Suggestions - 0

Review Details

• Files reviewed - 5 · Commit Range: 5a930fd..1c3f0ef

  • docs/admin_docs/configuration/mcp-server.mdx
  • superset/mcp_service/chart/big_number_headline.py
  • superset/mcp_service/chart/tool/get_chart_data.py
  • tests/unit_tests/mcp_service/chart/test_big_number_headline.py
  • tests/unit_tests/mcp_service/chart/tool/test_get_chart_data.py
• Files skipped - 0
• Tools

  • MyPy (Static Code Analysis) - ✔︎ Successful
  • Astral Ruff (Static Code Analysis) - ✔︎ Successful
  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[gabotorresruiz]

Hey @aminghadersohi, this clears my change request. Thanks for turning both of those around so thoroughly, and for the Node run across the six orders.

I re-verified on 1c3f0eff. The resample guard mirrors resampleOperator exactly (both controls required, resample absent from the executed query), and I went after the mechanism rather than the one case: the trendline buildQuery only ever adds pivot, resample, rolling/cum and flatten, and the Advanced Analytics section of that control panel holds nothing else that changes the series, so with rolling_type and resample_* both guarded the family is covered. pivot and flatten cannot move a value here because the query groups by the x-axis, one row per timestamp. My four weekly rows of 70 now return value null with a reason, as do [[1000, 10], [null, 99], [3000, 30]]. I also cross-checked the module against a port of transformProps over 2500 random series (nulls, duplicate and negative timestamps, every aggregation): 1931 returned a value and all 1931 matched what the chart renders for the same row order, no divergence. Dumping all 78 tool schemas through the real middleware, head against the PR base, the only delta is the additive optional headline object on get_chart_data and on each chart in get_dashboard_data: nothing removed, no type or requiredness changed. tests/unit_tests/mcp_service/chart plus dashboard give 3650 passed, 3 skipped, and the new tests produce 119 failures against 5a930fd7, so they do pin the fix rather than an invariant.

CI is green on this commit, 43 checks passing with the frontend jobs skipped since no frontend files changed.

One non-blocking question inline about a legacy form data shape; nothing in it should hold up the merge.

[codeant-ai-for-open-source]

CodeAnt PR Risk: Low Risk

• The PR appears safe to merge; Big Number headlines use full query results and return null when truncation or unapplied chart transforms make the value uncertain.
• Regression tests cover aggregation, unsaved visualization changes, and timestamp edge cases, and dashboard responses pass through the headline.

Assessed commit: a8cf46fa8e50

[bito-code-review]

Code Review Agent Run #82d0bc

Actionable Suggestions - 0

Review Details

• Files reviewed - 2 · Commit Range: 1c3f0ef..a8cf46f

  • superset/mcp_service/chart/big_number_headline.py
  • tests/unit_tests/mcp_service/chart/test_big_number_headline.py
• Files skipped - 0
• Tools

  • MyPy (Static Code Analysis) - ✔︎ Successful
  • Astral Ruff (Static Code Analysis) - ✔︎ Successful
  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by