Standardizing formData / control key naming across viz plugins

[rusackas]

Problem

Our viz plugins have accumulated a lot of inconsistent names for the same underlying concepts in their formData/control panel keys. The clearest example: "a metric" is spelled at least 9 different ways depending on which plugin you're looking at (metric, metrics, secondary_metric, a metrics+_b suffix pattern, left_metric/right_metric, a dead unused metric_2, and a couple of plugins just reusing x/y/size as ad-hoc metrics). "Pick some columns to group by" has 9 spellings too (groupby, columns, series, entity, all_columns, all_columns_x/_y, and pivot-table's camelCase groupbyColumns/groupbyRows).

This isn't just cosmetic:

• It makes control panels harder to write/maintain (no consistent vocabulary to reach for).
• It makes the MCP chart-creation/editing tools harder to keep in sync with the UI (they maintain a separate ~2800-line schema file with per-viz-type field names, hand-mapped independently of the control panels).
• It makes it harder for new plugin authors to guess the "right" name.

Scope

Surveyed all 55 controlPanel configs across 17 plugin packages. Good news first: there's already a central sharedControls registry in @superset-ui/chart-controls that most plugins reference, so this isn't "every plugin reinvented its own controls" - it's "plugins each pick a different existing key (or roll a one-off) for the same concept."

• Metric-like fields: ~9-11 variants. Worst offender is "a second metric alongside the primary one" - 5 separate spellings across only 6 plugins.
• Groupby-like fields: 9 variants.
• Filters: already consistent (adhoc_filters everywhere) - not touching this.
• Limit/sort: a 3-way split (limit/row_limit/series_limit) - though partition genuinely needs two distinct limit concepts, so any consolidation has to preserve that rather than merge it away.
• Color scheme: low variance, skip.
• Time grain: legacy granularity_sqla lingers in just 2 plugins vs. modern time_grain_sqla in 7.
• One real type collision worth flagging on its own, unrelated to naming: point_radius is a fixed pixel number in the deckgl layers, but a string/"Auto"/column-name in point-cluster-map.

How deep does a rename actually go?

Splits cleanly into two tiers:

Tier 1 - frontend-only, shimmable. If nothing else in the codebase hardcodes the literal key, you can rename the control and translate old to new at runtime with no DB migration. There's already an established mechanism for exactly this: QueryObject's DEPRECATED_FIELDS shim (groupby->columns, granularity_sqla->granularity, etc.) in superset/common/query_object.py.

Tier 2 - needs a DB migration, and often an MCP schema update too. Kicks in once something hardcodes the literal key:

• Redux's exploreReducer has a controlName === 'metrics' branch that keeps column_config synced to metric labels.
• The MCP service (schemas.py plus per-viz-type to_form_data() mappers) hardcodes key names independently of the frontend control panel - it's agent-facing API surface, not just UI plumbing.
• Saved charts store params as an opaque, unvalidated JSON blob, so existing charts keep the old key forever unless migrated.

There's already a reusable migration pattern (MigrateViz base class with a rename_keys dict, in superset/migrations/shared/migrate_viz/base.py) and several precedent migrations to copy from. They're always scoped to one viz_type at a time, roughly 70-120 lines, and conventionally irreversible (no real downgrade path).

Proposed approach

Rather than a big-bang rename, do this as a series of small, independent PRs, each handling one concept end-to-end (control panel + buildQuery/transformProps + migration if needed + MCP schema update if needed). Smallest blast radius first, to prove out the pattern before touching anything as load-bearing as metric/groupby themselves:

1. Second-metric family (secondary_metric / metrics+_b suffix / left_metric+right_metric / dead metric_2) -> one consistent name. 6 plugins, self-contained to plugin-chart-echarts, likely Tier 1 or close to it.
2. Legacy time grain (granularity_sqla -> time_grain_sqla) in calendar/horizon. Small and bounded.
3. Limit/sort consolidation (limit/row_limit/series_limit) - needs care to keep partition's two distinct limit concepts intact.
4. Groupby/columns/series/entity/all_columns* family - the bigger one, Tier 2, migrations plus MCP updates.
5. metric/metrics core consolidation, if still worth it after the above - the deepest one (Redux hardcoding + the heaviest MCP footprint).

Each PR would include the control panel change, a DEPRECATED_FIELDS-style shim or MigrateViz migration as needed, and a matching MCP schema/plugin update so the AI-facing tool surface doesn't drift from the UI.

Curious whether this is worth tracking as a real effort, whether anyone's already poked at parts of it (the MCP schemas in particular feel like they could use their own pass regardless of this), and any thoughts on sequencing or on using MigrateViz-style generic tooling vs. one-off migrations each time.

[CherylZ4]

Hi, my team from the UTSC D01 course would like to work on this!

[rusackas]

Welcome, and thanks for considering this! We left some back and forth comments with @villebro on this, and it's a bit of a minefield, I was more trying to document some thoughts/approaches here, mainly.

If you DO want to chip away at it, I'd start with the second-metric family (step 1 in the list), since it's self-contained to plugin-chart-echarts and good for proving out the shim/migration pattern. Keep each PR to one concept, and feel free to drop a note here before you start so nobody doubles up. We want it all to be well-tested with no breaking changes along the way. Migrations will likely be needed.

It's a whole slew of little changes, and they may compete with OR be done in tandem with the control panel revamp work @villebro is investigating. If that first task turns out to be reasonable as a first-cut, maybe we can keep cutting!