gkneighb commented on code in PR #42070:
URL: https://github.com/apache/superset/pull/42070#discussion_r3605438250
##########
superset/mcp_service/chart/schemas.py:
##########
@@ -2009,6 +2009,105 @@ def validate_percentiles_and_dimensions(self) ->
"BoxPlotChartConfig":
return self
+class WaterfallChartConfig(UnknownFieldCheckMixin):
+ """Config for waterfall charts (viz_type ``waterfall``)."""
+
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+ chart_type: Literal["waterfall"] = "waterfall"
+ x_axis: ColumnRef = Field(
+ ...,
+ description="Category or period column along the x-axis (often "
+ "temporal, e.g. month); each value is one waterfall step",
+ )
+ metric: ColumnRef = Field(
+ ...,
+ description="Metric whose per-step change is plotted (use aggregate "
+ "e.g. SUM for ad-hoc, or saved_metric=True for a saved metric)",
+ )
+ breakdown: ColumnRef | None = Field(
+ None,
+ validation_alias=AliasChoices("breakdown", "groupby"),
+ description="Optional single category column that breaks each "
+ "x-axis period into per-category steps (form_data 'groupby'; the "
+ "frontend Breakdowns control is single-select)",
+ )
+ time_grain: TimeGrain | None = Field(
+ None,
+ description="Time bucket for a temporal x_axis (PT1H, P1D, P1W, "
+ "P1M, P1Y); each bucket becomes one waterfall step. Ignored for a "
+ "non-temporal x_axis.",
+ validation_alias=AliasChoices("time_grain", "time_grain_sqla"),
+ )
+ show_total: bool = Field(
+ True, description="Append a total bar per period (frontend default)"
+ )
+ show_legend: bool = Field(
+ False, description="Show the legend (frontend default: off)"
+ )
+ increase_label: str = Field("Increase", max_length=50)
+ decrease_label: str = Field("Decrease", max_length=50)
+ total_label: str = Field("Total", max_length=50)
+ x_axis_time_format: str = Field(
+ "smart_date",
+ description="Time format for a temporal x-axis (e.g. 'smart_date',
'%Y-%m-%d')",
+ max_length=50,
+ )
+ y_axis_format: str = Field("SMART_NUMBER", max_length=50)
+ currency_format: CurrencyFormat | None = Field(
+ None,
+ description="Currency symbol applied to the metric value",
+ )
+ filters: List[FilterConfig] | None = Field(
+ None,
+ description="Structured filters (column/op/value). "
+ "Do NOT use adhoc_filters or raw SQL expressions.",
+ )
+ row_limit: int = Field(
+ 10000,
+ description="Max grouped rows (frontend shared default)",
+ ge=1,
+ le=50000,
+ )
+
+ @model_validator(mode="before")
+ @classmethod
+ def unwrap_list_breakdown(cls, data: Any) -> Any:
+ """Accept the native form_data shape where ``groupby`` is a list.
+
+ The frontend Breakdowns control is single-select but stores its value
+ as a one-item list (e.g. ``["region"]``), so a config round-tripped
+ from existing waterfall form_data sends a list. Unwrap a length-1
+ list to the single value; reject longer lists rather than silently
+ dropping breakdowns.
+ """
+ if isinstance(data, dict):
+ for key in ("groupby", "breakdown"):
+ value = data.get(key)
+ if isinstance(value, list):
+ if len(value) > 1:
+ raise ValueError(
+ "waterfall breakdown is single-select; pass at "
+ "most one column"
+ )
+ data[key] = value[0] if value else None
Review Comment:
Already fixed in 573c819f35 (before this re-review): the coercion now wraps
bare strings to {'name': ...} for both list and scalar shapes, and this push
(10daf20775) extends it to x_axis. Tests cover string-list, scalar-string, and
x_axis-string.
##########
superset/mcp_service/chart/chart_utils.py:
##########
@@ -951,6 +952,37 @@ def map_box_plot_config(config: "BoxPlotChartConfig") ->
Dict[str, Any]:
return form_data
+def map_waterfall_config(config: WaterfallChartConfig) -> Dict[str, Any]:
+ """Map waterfall config to Superset form_data (viz_type waterfall).
+
+ Matches the frontend Waterfall buildQuery contract: a single ``x_axis``
+ column, an optional single-select ``groupby`` breakdown, and one
+ ``metric``; the query orders by the axis columns ascending, which the
+ frontend derives from these keys.
+ """
+ form_data: Dict[str, Any] = {
+ "viz_type": "waterfall",
+ "x_axis": config.x_axis.name,
+ "groupby": [config.breakdown.name] if config.breakdown else [],
+ "metric": create_metric_object(config.metric),
+ "show_total": config.show_total,
+ "show_legend": config.show_legend,
+ "increase_label": config.increase_label,
+ "decrease_label": config.decrease_label,
+ "total_label": config.total_label,
+ "x_axis_time_format": config.x_axis_time_format,
+ "y_axis_format": config.y_axis_format,
+ "row_limit": config.row_limit,
+ }
+ # Bucket a temporal x_axis; Superset ignores time_grain_sqla for
+ # non-temporal columns, matching the frontend control's behavior.
+ if config.time_grain:
+ form_data["time_grain_sqla"] = config.time_grain
Review Comment:
Already fixed in 573c819f35: when time_grain is set the mapper also sets
granularity_sqla to the x_axis column. Test asserts both fields.
##########
superset/mcp_service/chart/schemas.py:
##########
@@ -2009,6 +2009,112 @@ def validate_percentiles_and_dimensions(self) ->
"BoxPlotChartConfig":
return self
+class WaterfallChartConfig(UnknownFieldCheckMixin):
+ """Config for waterfall charts (viz_type ``waterfall``)."""
+
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+ chart_type: Literal["waterfall"] = "waterfall"
+ x_axis: ColumnRef = Field(
+ ...,
+ description="Category or period column along the x-axis (often "
+ "temporal, e.g. month); each value is one waterfall step",
+ )
+ metric: ColumnRef = Field(
+ ...,
+ description="Metric whose per-step change is plotted (use aggregate "
+ "e.g. SUM for ad-hoc, or saved_metric=True for a saved metric)",
+ )
+ breakdown: ColumnRef | None = Field(
+ None,
+ validation_alias=AliasChoices("breakdown", "groupby"),
+ description="Optional single category column that breaks each "
+ "x-axis period into per-category steps (form_data 'groupby'; the "
+ "frontend Breakdowns control is single-select)",
+ )
+ time_grain: TimeGrain | None = Field(
+ None,
+ description="Time bucket for a temporal x_axis (PT1H, P1D, P1W, "
+ "P1M, P1Y); each bucket becomes one waterfall step. Ignored for a "
+ "non-temporal x_axis.",
+ validation_alias=AliasChoices("time_grain", "time_grain_sqla"),
+ )
+ show_total: bool = Field(
+ True, description="Append a total bar per period (frontend default)"
+ )
+ show_legend: bool = Field(
+ False, description="Show the legend (frontend default: off)"
+ )
+ increase_label: str = Field("Increase", max_length=50)
+ decrease_label: str = Field("Decrease", max_length=50)
+ total_label: str = Field("Total", max_length=50)
+ x_axis_time_format: str = Field(
+ "smart_date",
+ description="Time format for a temporal x-axis (e.g. 'smart_date',
'%Y-%m-%d')",
+ max_length=50,
+ )
+ y_axis_format: str = Field("SMART_NUMBER", max_length=50)
+ currency_format: CurrencyFormat | None = Field(
+ None,
+ description="Currency symbol applied to the metric value",
+ )
+ filters: List[FilterConfig] | None = Field(
+ None,
+ description="Structured filters (column/op/value). "
+ "Do NOT use adhoc_filters or raw SQL expressions.",
+ )
+ row_limit: int = Field(
+ 10000,
+ description="Max grouped rows (frontend shared default)",
+ ge=1,
+ le=50000,
+ )
+
+ @model_validator(mode="before")
+ @classmethod
+ def unwrap_list_breakdown(cls, data: Any) -> Any:
+ """Accept the native form_data shape where ``groupby`` is a list.
+
+ The frontend Breakdowns control is single-select but stores its value
+ as a one-item list (e.g. ``["region"]``), so a config round-tripped
+ from existing waterfall form_data sends a list. Unwrap a length-1
+ list to the single value; reject longer lists rather than silently
+ dropping breakdowns. Native form_data also names physical columns as
+ bare strings, so a string is coerced to ``{"name": ...}``.
+ """
+
+ def _coerce(value: Any) -> Any:
+ if isinstance(value, list):
+ if len(value) > 1:
+ raise ValueError(
+ "waterfall breakdown is single-select; pass at most
one column"
+ )
+ value = value[0] if value else None
+ if isinstance(value, str):
+ return {"name": value}
+ return value
+
+ if isinstance(data, dict):
+ for key in ("groupby", "breakdown"):
+ if key in data:
+ data[key] = _coerce(data[key])
+ return data
Review Comment:
Fixed in 10daf20775 — x_axis bare strings are now coerced too, with a test.
##########
superset/mcp_service/chart/schemas.py:
##########
@@ -2019,13 +2125,14 @@ def validate_percentiles_and_dimensions(self) ->
"BoxPlotChartConfig":
| HandlebarsChartConfig
| BigNumberChartConfig
| HistogramChartConfig
- | BoxPlotChartConfig,
+ | BoxPlotChartConfig
+ | WaterfallChartConfig,
Review Comment:
Fixed in 10daf20775 — added 'waterfall' to _VIZ_CATEGORY. Gave it its own
category rather than folding into bar: waterfall's cumulative-flow semantics
are distinct (funnel/gauge/treemap likewise carry their own categories), so
recommending a bar chart alongside a waterfall isn't redundant. Test asserts
the entry.
##########
superset/mcp_service/chart/chart_utils.py:
##########
@@ -951,6 +952,41 @@ def map_box_plot_config(config: "BoxPlotChartConfig") ->
Dict[str, Any]:
return form_data
+def map_waterfall_config(config: WaterfallChartConfig) -> Dict[str, Any]:
+ """Map waterfall config to Superset form_data (viz_type waterfall).
+
+ Matches the frontend Waterfall buildQuery contract: a single ``x_axis``
+ column, an optional single-select ``groupby`` breakdown, and one
+ ``metric``; the query orders by the axis columns ascending, which the
+ frontend derives from these keys.
+ """
+ form_data: Dict[str, Any] = {
+ "viz_type": "waterfall",
+ "x_axis": config.x_axis.name,
+ "groupby": [config.breakdown.name] if config.breakdown else [],
+ "metric": create_metric_object(config.metric),
+ "show_total": config.show_total,
+ "show_legend": config.show_legend,
+ "increase_label": config.increase_label,
+ "decrease_label": config.decrease_label,
+ "total_label": config.total_label,
+ "x_axis_time_format": config.x_axis_time_format,
+ "y_axis_format": config.y_axis_format,
+ "row_limit": config.row_limit,
+ }
+ # Bucket a temporal x_axis: the grain (time_grain_sqla) needs the temporal
+ # column it applies to (granularity_sqla), mirroring the xy path's
+ # configure_temporal_handling and the frontend buildQuery's
+ # `x_axis || granularity_sqla`. Providing time_grain signals temporal
+ # intent; Superset ignores both for a non-temporal column.
+ if config.time_grain:
+ form_data["time_grain_sqla"] = config.time_grain
+ form_data["granularity_sqla"] = config.x_axis.name
Review Comment:
Fixed in 10daf20775 — added post_map_validate that rejects time_grain on a
non-temporal x_axis (via is_column_truly_temporal), mirroring the histogram
numeric-column check and the xy path's temporal handling. Tests cover both
directions.
##########
tests/unit_tests/mcp_service/chart/test_waterfall_chart.py:
##########
@@ -0,0 +1,257 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Tests for the waterfall chart type plugin.
+
+Schema validation, form_data mapping (matching the frontend Waterfall
+buildQuery/transformProps contract for viz_type ``waterfall``), native
+vocabulary aliases, and registry integration.
+"""
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from superset.mcp_service.chart.chart_utils import map_waterfall_config
+from superset.mcp_service.chart.schemas import ChartConfig,
WaterfallChartConfig
+
+
+class TestWaterfallChartConfigSchema:
+ """WaterfallChartConfig schema validation."""
+
+ def test_basic_waterfall_config(self) -> None:
+ config = WaterfallChartConfig(
Review Comment:
Declining, standing rationale: constants and inferable test locals are
unannotated across this codebase; mypy passes.
##########
tests/unit_tests/mcp_service/chart/test_waterfall_chart.py:
##########
@@ -0,0 +1,257 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Tests for the waterfall chart type plugin.
+
+Schema validation, form_data mapping (matching the frontend Waterfall
+buildQuery/transformProps contract for viz_type ``waterfall``), native
+vocabulary aliases, and registry integration.
+"""
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from superset.mcp_service.chart.chart_utils import map_waterfall_config
+from superset.mcp_service.chart.schemas import ChartConfig,
WaterfallChartConfig
+
+
+class TestWaterfallChartConfigSchema:
+ """WaterfallChartConfig schema validation."""
+
+ def test_basic_waterfall_config(self) -> None:
+ config = WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue_delta", "aggregate": "SUM"},
+ )
+ assert config.x_axis.name == "month"
+ assert config.breakdown is None
+ assert config.show_total is True # frontend controlPanel default
+
+ def test_waterfall_missing_x_axis(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ metric={"name": "revenue", "aggregate": "SUM"},
+ )
+
+ def test_waterfall_missing_metric(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(chart_type="waterfall", x_axis={"name":
"month"})
+
+ def test_waterfall_rejects_extra_fields(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ bogus=1,
+ )
+
+ def test_waterfall_breakdown_rejects_saved_metric(self) -> None:
+ """The breakdown is a dimension, not a metric."""
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ breakdown={"name": "count", "saved_metric": True},
+ )
+
+ def test_waterfall_x_axis_rejects_saved_metric(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "count", "saved_metric": True},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ )
+
+ def test_groupby_alias_for_breakdown(self) -> None:
+ """Superset-native 'groupby' is accepted for the breakdown field."""
+ config = WaterfallChartConfig.model_validate(
+ {
+ "chart_type": "waterfall",
+ "x_axis": {"name": "month"},
+ "metric": {"name": "revenue", "aggregate": "SUM"},
+ "groupby": {"name": "region"},
+ }
+ )
+ assert config.breakdown is not None
+ assert config.breakdown.name == "region"
+
+ def test_chart_config_union_dispatches_waterfall(self) -> None:
+ config = TypeAdapter(ChartConfig).validate_python(
+ {
+ "chart_type": "waterfall",
+ "x_axis": {"name": "month"},
+ "metric": {"name": "revenue", "aggregate": "SUM"},
+ }
+ )
+ assert isinstance(config, WaterfallChartConfig)
+
+
+class TestMapWaterfallConfig:
+ """form_data mapping must match the frontend Waterfall buildQuery."""
+
+ def test_basic_waterfall_form_data(self) -> None:
+ config = WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue_delta", "aggregate": "SUM"},
+ )
+ form_data = map_waterfall_config(config)
Review Comment:
Declining, standing rationale: constants and inferable test locals are
unannotated across this codebase; mypy passes.
##########
tests/unit_tests/mcp_service/chart/test_waterfall_chart.py:
##########
@@ -0,0 +1,257 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Tests for the waterfall chart type plugin.
+
+Schema validation, form_data mapping (matching the frontend Waterfall
+buildQuery/transformProps contract for viz_type ``waterfall``), native
+vocabulary aliases, and registry integration.
+"""
+
+import pytest
+from pydantic import TypeAdapter, ValidationError
+
+from superset.mcp_service.chart.chart_utils import map_waterfall_config
+from superset.mcp_service.chart.schemas import ChartConfig,
WaterfallChartConfig
+
+
+class TestWaterfallChartConfigSchema:
+ """WaterfallChartConfig schema validation."""
+
+ def test_basic_waterfall_config(self) -> None:
+ config = WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue_delta", "aggregate": "SUM"},
+ )
+ assert config.x_axis.name == "month"
+ assert config.breakdown is None
+ assert config.show_total is True # frontend controlPanel default
+
+ def test_waterfall_missing_x_axis(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ metric={"name": "revenue", "aggregate": "SUM"},
+ )
+
+ def test_waterfall_missing_metric(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(chart_type="waterfall", x_axis={"name":
"month"})
+
+ def test_waterfall_rejects_extra_fields(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ bogus=1,
+ )
+
+ def test_waterfall_breakdown_rejects_saved_metric(self) -> None:
+ """The breakdown is a dimension, not a metric."""
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ breakdown={"name": "count", "saved_metric": True},
+ )
+
+ def test_waterfall_x_axis_rejects_saved_metric(self) -> None:
+ with pytest.raises(ValidationError):
+ WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "count", "saved_metric": True},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ )
+
+ def test_groupby_alias_for_breakdown(self) -> None:
+ """Superset-native 'groupby' is accepted for the breakdown field."""
+ config = WaterfallChartConfig.model_validate(
+ {
+ "chart_type": "waterfall",
+ "x_axis": {"name": "month"},
+ "metric": {"name": "revenue", "aggregate": "SUM"},
+ "groupby": {"name": "region"},
+ }
+ )
+ assert config.breakdown is not None
+ assert config.breakdown.name == "region"
+
+ def test_chart_config_union_dispatches_waterfall(self) -> None:
+ config = TypeAdapter(ChartConfig).validate_python(
+ {
+ "chart_type": "waterfall",
+ "x_axis": {"name": "month"},
+ "metric": {"name": "revenue", "aggregate": "SUM"},
+ }
+ )
+ assert isinstance(config, WaterfallChartConfig)
+
+
+class TestMapWaterfallConfig:
+ """form_data mapping must match the frontend Waterfall buildQuery."""
+
+ def test_basic_waterfall_form_data(self) -> None:
+ config = WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue_delta", "aggregate": "SUM"},
+ )
+ form_data = map_waterfall_config(config)
+ assert form_data["viz_type"] == "waterfall"
+ assert form_data["x_axis"] == "month"
+ assert form_data["groupby"] == []
+ assert form_data["metric"]["label"] == "SUM(revenue_delta)"
+ assert form_data["show_total"] is True
+
+ def test_waterfall_form_data_with_breakdown_and_filters(self) -> None:
+ config = WaterfallChartConfig(
+ chart_type="waterfall",
+ x_axis={"name": "month"},
+ metric={"name": "revenue", "aggregate": "SUM"},
+ breakdown={"name": "region"},
+ filters=[{"column": "year", "op": "=", "value": 2026}],
+ show_total=False,
+ )
+ form_data = map_waterfall_config(config)
+ # single breakdown maps to the groupby list (frontend multi: false)
+ assert form_data["groupby"] == ["region"]
+ assert form_data["show_total"] is False
+ assert form_data["adhoc_filters"], "filters must map to adhoc_filters"
+
+
+class TestWaterfallPluginRegistry:
+ """Plugin registration and viz-type resolution."""
+
+ def test_waterfall_plugin_registered(self) -> None:
+ from superset.mcp_service.chart import registry
+
+ plugin = registry.get("waterfall")
+ assert plugin is not None
Review Comment:
Declining, standing rationale: constants and inferable test locals are
unannotated across this codebase; mypy passes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
