Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs: standardize supported dataframe backends across UI elements (#9583)

Myles Scolnick1c7c29a18197
diff --git a/docs/api/inputs/dataframe.md b/docs/api/inputs/dataframe.md
index 82ba25341e..a1deb9fe83 100644
--- a/docs/api/inputs/dataframe.md
+++ b/docs/api/inputs/dataframe.md
@@ -2,10 +2,9 @@
The dataframe UI element outputs a visual editor to apply "transforms" to a dataframe, such as filtering rows, applying group-bys and aggregations, and more. The transformed dataframe is shown below the transform editor. The UI output also includes the generated Python used to generate the resulting dataframe, which you can copy paste into a cell. You can programmatically access the resulting dataframe by accessing the element's `.value` attribute.
-!!! note "Pandas or Polars Required"
+!!! note "Dataframe library required"
- In order to use the dataframe UI element, you must have the `pandas` or `polars` package installed.
- You can install it with `pip install pandas` or `pip install polars`.
+ To use the dataframe UI element, you must have a supported dataframe library installed (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).
Supported transforms are:
diff --git a/marimo/_plugins/ui/_impl/altair_chart.py b/marimo/_plugins/ui/_impl/altair_chart.py
index c5edff4609..5e9af95ded 100644
--- a/marimo/_plugins/ui/_impl/altair_chart.py
+++ b/marimo/_plugins/ui/_impl/altair_chart.py
@@ -476,7 +476,7 @@ class altair_chart(UIElement[ChartSelection, ChartDataType]):
Use `mo.ui.altair_chart` to make Altair charts reactive: select chart data
with your cursor on the frontend, get them as a dataframe in Python!
- Supports polars, pandas, and arrow DataFrames.
+ Supports any dataframe (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).
Examples:
```python
diff --git a/marimo/_plugins/ui/_impl/data_editor.py b/marimo/_plugins/ui/_impl/data_editor.py
index eea0660936..3a8e17beb6 100644
--- a/marimo/_plugins/ui/_impl/data_editor.py
+++ b/marimo/_plugins/ui/_impl/data_editor.py
@@ -128,7 +128,7 @@ class data_editor(
https://github.com/marimo-team/marimo/issues.
The data can be supplied as:
- 1. a Pandas, Polars, or Pyarrow DataFrame
+ 1. an eager dataframe (e.g., Polars, Pandas, PyArrow)
2. a list of dicts, with one dict for each row, keyed by column names
3. a dict of lists, with each list representing a column
@@ -240,7 +240,14 @@ class data_editor(
self, value: DataEdits
) -> RowOrientedData | ColumnOrientedData | IntoDataFrame:
self._edits = value
- return apply_edits(deepcopy(self._data), value)
+ # list/dict edit paths mutate in place, so deepcopy first.
+ # The dataframe path constructs a new native frame via narwhals
+ # without mutating the input — and not all dataframes are picklable
+ # (e.g., DuckDBPyRelation), so skip the deepcopy in that case.
+ data = self._data
+ if isinstance(data, (list, dict)):
+ data = deepcopy(data)
+ return apply_edits(data, value)
def __hash__(self) -> int:
return id(self)
diff --git a/marimo/_plugins/ui/_impl/data_explorer.py b/marimo/_plugins/ui/_impl/data_explorer.py
index 9d99eed80a..8ef6420a56 100644
--- a/marimo/_plugins/ui/_impl/data_explorer.py
+++ b/marimo/_plugins/ui/_impl/data_explorer.py
@@ -30,7 +30,7 @@ class data_explorer(UIElement[dict[str, Any], dict[str, Any]]):
initial selections if provided via keyword arguments.
Args:
- df (IntoDataFrame): The DataFrame to visualize.
+ df (IntoDataFrame): The dataframe to visualize (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).
on_change (Callable[[dict[str, Any]], None], optional): Optional callback
to run when this element's value changes.
x (Optional[str]): Initial column for the x-axis. Defaults to None.
diff --git a/marimo/_plugins/ui/_impl/dataframes/dataframe.py b/marimo/_plugins/ui/_impl/dataframes/dataframe.py
index fc6c4de117..3703fa6bea 100644
--- a/marimo/_plugins/ui/_impl/dataframes/dataframe.py
+++ b/marimo/_plugins/ui/_impl/dataframes/dataframe.py
@@ -104,7 +104,7 @@ class GetDataFrameError(Exception):
class dataframe(UIElement[dict[str, Any], DataFrameType]):
"""Run transformations on a DataFrame or series.
- Currently supports Pandas, Polars, Ibis, Pyarrow, and DuckDB.
+ Supports any dataframe (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).
Examples:
```python
diff --git a/marimo/_plugins/ui/_impl/table.py b/marimo/_plugins/ui/_impl/table.py
index a165e37596..cae97c3874 100644
--- a/marimo/_plugins/ui/_impl/table.py
+++ b/marimo/_plugins/ui/_impl/table.py
@@ -319,10 +319,7 @@ class table(
1. a list of dicts, with one dict for each row, keyed by column names;
2. a list of values, representing a table with a single column;
- 3. a Pandas dataframe; or
- 4. a Polars dataframe; or
- 5. an Ibis dataframe; or
- 6. a PyArrow table.
+ 3. a dataframe (e.g., Polars, Pandas, PyArrow, Ibis, DuckDB).
Examples:
Create a table from a list of dicts, one for each row:
@@ -492,7 +489,7 @@ class table(
preload: bool = False,
) -> table:
"""
- Create a table from a Polars LazyFrame.
+ Create a table from a lazy dataframe (e.g., Polars LazyFrame, Ibis Table, DuckDB Relation).
This won't load the data into memory until requested by the user.
Once requested, only the first 10 rows will be loaded.
diff --git a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py b/tests/_plugins/ui/_impl/dataframes/test_dataframe.py
index 8d24d694ac..0703434795 100644
--- a/tests/_plugins/ui/_impl/dataframes/test_dataframe.py
+++ b/tests/_plugins/ui/_impl/dataframes/test_dataframe.py
@@ -1,7 +1,7 @@
from __future__ import annotations
import json
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from unittest.mock import Mock, patch
import narwhals.stable.v2 as nw
@@ -61,12 +61,22 @@ def is_not_narwhals_dataframe(df: IntoDataFrame | IntoLazyFrame) -> bool:
@pytest.mark.skipif(not HAS_DEPS, reason="optional dependencies not installed")
class TestDataframes:
+ @staticmethod
+ @pytest.mark.parametrize(
+ "df",
+ create_dataframes({"A": [1, 2, 3], "B": ["a", "a", "a"]}),
+ )
+ def test_dataframe_supports_dataframe_backends(df: Any) -> None:
+ subject = ui.dataframe(df)
+ # Construction should succeed and the value should round-trip to the
+ # original native type for each supported dataframe backend.
+ assert type(subject.value) is type(df)
+
@staticmethod
@pytest.mark.parametrize(
"df",
create_dataframes(
{"A": [1, 2, 3], "B": ["a", "a", "a"]},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe(df: IntoDataFrame) -> None:
@@ -82,6 +92,8 @@ class TestDataframes:
[["A", "integer", "int64"], ["B", "string", "string"]],
# pandas 3.x
[["A", "integer", "int64"], ["B", "string", "str"]],
+ # pyarrow / duckdb (via narwhals)
+ [["A", "integer", "Int64"], ["B", "string", "String"]],
]
assert subject._get_column_values(
GetColumnValuesArgs(column="A")
@@ -136,7 +148,6 @@ class TestDataframes:
"df",
create_dataframes(
{"1": [1, 2, 3], "2": ["a", "a", "a"]},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe_page_size(df: IntoDataFrame) -> None:
@@ -171,7 +182,6 @@ class TestDataframes:
"df",
create_dataframes(
{"A": [1, 2], "B": ["a", "b"]},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe_format_mapping(df: IntoDataFrame) -> None:
@@ -193,18 +203,15 @@ class TestDataframes:
[
*create_dataframes(
{"A": [], "B": []},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
), # Empty DataFrame
*create_dataframes(
{"A": [1], "B": ["a"]},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
), # Single row DataFrame
*create_dataframes(
{
"A": range(1, 1001),
"B": [f"value_{i}" for i in range(1, 1001)],
},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
), # Large DataFrame
],
)
@@ -236,7 +243,6 @@ class TestDataframes:
"df",
create_dataframes(
{"A": range(100), "B": ["a"] * 100},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe_with_custom_page_size(df: IntoDataFrame) -> None:
@@ -285,7 +291,6 @@ class TestDataframes:
"df",
create_dataframes(
{"A": range(1000), "B": ["a"] * 1000},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe_with_limit(df: IntoDataFrame) -> None:
@@ -474,7 +479,6 @@ class TestDataframes:
"df",
create_dataframes(
{"A": [1, 2, 3], "B": ["x", "y", "z"]},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe_download_different_backends(df) -> None:
@@ -541,7 +545,6 @@ class TestDataframes:
"df",
create_dataframes(
{"A": [1, 2, 3], "B": ["a", "b", "c"]},
- exclude=["pyarrow", "duckdb", "lazy-polars"],
),
)
def test_dataframe_error_handling(df: IntoDataFrame) -> None:
diff --git a/tests/_plugins/ui/_impl/test_data_editor.py b/tests/_plugins/ui/_impl/test_data_editor.py
index 6bdd62d088..101562bb32 100644
--- a/tests/_plugins/ui/_impl/test_data_editor.py
+++ b/tests/_plugins/ui/_impl/test_data_editor.py
@@ -15,6 +15,7 @@ from marimo._plugins.ui._impl.data_editor import (
_convert_value,
apply_edits,
)
+from tests._data.mocks import create_dataframes
data_editor = ui.data_editor
@@ -412,6 +413,27 @@ def test_data_editor_with_polars_dataframe():
assert df.equals(editor.data)
+ "df",
+ # data_editor uses narwhals with eager_only=True, so it only supports
+ # eager dataframe backends (pandas, polars, pyarrow), not lazy/relation
+ # types like Ibis and DuckDB.
+ create_dataframes(
+ {"A": [1, 2, 3], "B": ["a", "b", "c"]},
+ exclude=["lazy-polars", "ibis", "duckdb"],
+ ),
+)
+def test_data_editor_supports_dataframe_backends(df: Any) -> None:
+ editor = data_editor(data=df)
+ assert type(editor.data) is type(df)
+ # An applied edit should round-trip back to the same native type.
+ edits: DataEdits = {
+ "edits": [{"rowIdx": 1, "columnId": "B", "value": "x"}]
+ }
+ result = editor._convert_value(edits)
+ assert type(result) is type(df)
+
+
@pytest.mark.skipif(
not DependencyManager.polars.has(), reason="Polars not installed"
)
diff --git a/tests/_plugins/ui/_impl/test_table.py b/tests/_plugins/ui/_impl/test_table.py
index 8894545592..7fba3c5a2c 100644
--- a/tests/_plugins/ui/_impl/test_table.py
+++ b/tests/_plugins/ui/_impl/test_table.py
@@ -1012,7 +1012,7 @@ def test_show_column_summaries_modes():
class TestTableBinValues:
@pytest.mark.parametrize(
"df",
- create_dataframes({"a": [None] * 20}, exclude=["duckdb"]),
+ create_dataframes({"a": [None] * 20}),
)
def test_bin_values_all_nulls(self, df: Any) -> None:
table = ui.table(df)