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.

enhacement: improve DuckDB EXPLAIN rendering to show clean query plan text (#8487)

Myles Scolnick51c1a8265147
diff --git a/marimo/_smoke_tests/sql/explain.py b/marimo/_smoke_tests/sql/explain.py
new file mode 100644
index 0000000000..f49fdb56ae
--- /dev/null
+++ b/marimo/_smoke_tests/sql/explain.py
@@ -0,0 +1,87 @@
+import marimo
+
+__generated_with = "0.20.2"
+app = marimo.App(width="medium", auto_download=["html"], sql_output="native")
+
+
+def _():
+ import marimo as mo
+ import duckdb as db
+
+ return db, mo
+
+
+def _(db):
+ connection = db.connect(":memory:")
+ connection.sql(f"""
+ CREATE OR REPLACE TABLE fake_data (
+ id INTEGER,
+ name VARCHAR,
+ value INTEGER
+ );
+
+ INSERT INTO fake_data (id, name, value) VALUES
+ (1, 'Alice', 100),
+ (2, 'Bob', 150),
+ (3, 'Charlie', 200),
+ (4, 'David', 120),
+ (5, 'Eve', 180);
+ """)
+ return (connection,)
+
+
+def _(connection, mo):
+ _df = mo.sql(
+ f"""
+ CREATE OR REPLACE TABLE students (name VARCHAR, sid INTEGER);
+ CREATE OR REPLACE TABLE exams (eid INTEGER, subject VARCHAR, sid INTEGER);
+ INSERT INTO students VALUES ('Mark', 1), ('Joe', 2), ('Matthew', 3);
+ INSERT INTO exams VALUES (10, 'Physics', 1), (20, 'Chemistry', 2), (30, 'Literature', 3);
+ """,
+ engine=connection,
+ )
+ return
+
+
+def _(connection, mo):
+ _df = mo.sql(
+ f"""
+ EXPLAIN ANALYZE
+ SELECT name
+ FROM students
+ JOIN exams USING (sid)
+ WHERE name LIKE 'Ma%';
+ """,
+ engine=connection,
+ )
+ return
+
+
+def _(mo):
+ import duckdb
+
+ mo.plain_text(repr(duckdb.sql("explain select 1").pl()))
+ return
+
+
+def _(connection):
+ connection.sql("explain select * from fake_data")
+ return
+
+
+def _(connection, mo):
+ mo.md(f"""
+ {connection.sql("explain select * from fake_data")}
+ """)
+ return
+
+
+if __name__ == "__main__":
+ app.run()
diff --git a/marimo/_sql/utils.py b/marimo/_sql/utils.py
index e1138c930b..8860d9a261 100644
--- a/marimo/_sql/utils.py
+++ b/marimo/_sql/utils.py
@@ -284,23 +284,23 @@ def extract_explain_content(df: Any) -> str:
"""Extract all content from a DataFrame for EXPLAIN queries.
Args:
- df: DataFrame (pandas or polars). If not pandas / polars, return repr(df).
+ df: DataFrame (pandas or polars). If not pandas / polars / duckdb relation, return repr(df).
Returns:
String containing content of dataframe
"""
try:
- if DependencyManager.polars.has():
+ if DependencyManager.polars.imported():
import polars as pl
if isinstance(df, pl.LazyFrame):
df = df.collect()
if isinstance(df, pl.DataFrame):
# Display full strings without truncation
- with pl.Config(fmt_str_lengths=1000):
+ with pl.Config(fmt_str_lengths=10000):
return str(df)
- if DependencyManager.pandas.has():
+ if DependencyManager.pandas.imported():
import pandas as pd
if isinstance(df, pd.DataFrame):
@@ -308,6 +308,13 @@ def extract_explain_content(df: Any) -> str:
all_values = df.values.flatten().tolist()
return "\n".join(str(val) for val in all_values)
+ if DependencyManager.duckdb.imported():
+ import duckdb
+
+ if isinstance(df, duckdb.DuckDBPyRelation):
+ rows = df.fetchall()
+ return "\n".join(str(val) for row in rows for val in row)
+
# Fallback to repr for other types
return repr(df)
diff --git a/tests/_sql/test_sql.py b/tests/_sql/test_sql.py
index ddfaa8adb3..138c728f6a 100644
--- a/tests/_sql/test_sql.py
+++ b/tests/_sql/test_sql.py
@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING
from unittest.mock import MagicMock, patch
import pytest
+from inline_snapshot import snapshot
from marimo._dependencies.dependencies import DependencyManager
from marimo._output.formatting import Plain
@@ -471,6 +472,31 @@ logical_plan
└─────────────────────────────────────┘"""
)
+ @pytest.mark.skipif(not HAS_DUCKDB, reason="DuckDB not installed")
+ def test_extract_explain_content_duckdb_relation(self):
+ """Test extract_explain_content with a DuckDB relation."""
+ import duckdb
+
+ conn = duckdb.connect(":memory:")
+ conn.sql("CREATE TABLE t AS SELECT * FROM range(5) tbl(id)")
+ relation = conn.sql("EXPLAIN SELECT * FROM t")
+ result = extract_explain_content(relation)
+
+ assert result == snapshot("""\
+physical_plan
+┌───────────────────────────┐
+│ SEQ_SCAN │
+│ ──────────────────── │
+│ Table: t │
+│ Type: Sequential Scan │
+│ Projections: id │
+│ │
+│ ~5 rows │
+└───────────────────────────┘
+""")
+
+ conn.close()
+
def test_extract_explain_content_fallback(self):
"""Test extract_explain_content fallback for non-DataFrame objects."""
# Test with non-DataFrame object