feat: add show_statistics, analyze_level, and analyze_categories to explain

Expose the remaining upstream ExplainOption fields as keywords on
DataFrame.explain. Each defaults to None, which falls back to the
matching datafusion.explain.* session setting, so existing calls are
unaffected. New ExplainAnalyzeLevel and ExplainMetricCategory enums sit
beside ExplainFormat.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: timsaucer

crates/core/src/dataframe.rs

@@ -844,13 +844,24 @@ impl PyDataFrame {
     }
 
     /// Print the query plan
-    #[pyo3(signature = (verbose=false, analyze=false, format=None))]
+    #[pyo3(signature = (
+        verbose=false,
+        analyze=false,
+        format=None,
+        show_statistics=None,
+        analyze_level=None,
+        analyze_categories=None
+    ))]
+    #[allow(clippy::too_many_arguments)]
     fn explain(
         &self,
         py: Python,
         verbose: bool,
         analyze: bool,
         format: Option<&str>,
+        show_statistics: Option<bool>,
+        analyze_level: Option<&str>,
+        analyze_categories: Option<Vec<String>>,
     ) -> PyDataFusionResult<()> {
         let explain_format = match format {
             Some(f) => f
@@ -860,10 +871,24 @@ impl PyDataFrame {
                 })?,
             None => datafusion::common::format::ExplainFormat::Indent,
         };
+        let analyze_level = analyze_level
+            .map(|l| l.parse::<datafusion::common::format::MetricType>())
+            .transpose()?;
+        let analyze_categories = analyze_categories
+            .map(|cats| {
+                cats.iter()
+                    .map(|c| c.parse::<datafusion::common::format::MetricCategory>())
+                    .collect::<datafusion::common::Result<Vec<_>>>()
+                    .map(datafusion::common::format::ExplainAnalyzeCategories::Only)
+            })
+            .transpose()?;
         let opts = datafusion::logical_expr::ExplainOption::default()
             .with_verbose(verbose)
             .with_analyze(analyze)
-            .with_format(explain_format);
+            .with_format(explain_format)
+            .with_show_statistics(show_statistics)
+            .with_analyze_level(analyze_level)
+            .with_analyze_categories(analyze_categories);
         let df = self.df.as_ref().clone().explain_with_options(opts)?;
         print_dataframe(py, df)
     }

python/datafusion/__init__.py

@@ -85,7 +85,9 @@
 from .dataframe import (
     DataFrame,
     DataFrameWriteOptions,
+    ExplainAnalyzeLevel,
     ExplainFormat,
+    ExplainMetricCategory,
     InsertOp,
     ParquetColumnOptions,
     ParquetWriterOptions,
@@ -126,7 +128,9 @@
     "DataFrame",
     "DataFrameWriteOptions",
     "ExecutionPlan",
+    "ExplainAnalyzeLevel",
     "ExplainFormat",
+    "ExplainMetricCategory",
     "Expr",
     "InsertOp",
     "LogicalPlan",

python/datafusion/dataframe.py

@@ -108,6 +108,32 @@ class ExplainFormat(Enum):
     """Graphviz DOT format for graph rendering."""
 
 
+class ExplainAnalyzeLevel(Enum):
+    """Which metrics :py:meth:`DataFrame.explain` reports when ``analyze=True``."""
+
+    SUMMARY = "summary"
+    """Common metrics for finding which operator is slow."""
+
+    DEV = "dev"
+    """All metrics, including those for deep operator-level introspection."""
+
+
+class ExplainMetricCategory(Enum):
+    """Category of metric reported by :py:meth:`DataFrame.explain` with ``analyze``."""
+
+    ROWS = "rows"
+    """Row counts, such as ``output_rows``."""
+
+    BYTES = "bytes"
+    """Byte sizes, such as ``output_bytes``."""
+
+    TIMING = "timing"
+    """Elapsed times, such as ``elapsed_compute``."""
+
+    UNCATEGORIZED = "uncategorized"
+    """Metrics that declare no category."""
+
+
 # excerpt from deltalake
 # https://github.com/apache/datafusion-python/pull/981#discussion_r1905619163
 class Compression(Enum):
@@ -1207,6 +1233,9 @@ def explain(
         verbose: bool = False,
         analyze: bool = False,
         format: ExplainFormat | None = None,
+        show_statistics: bool | None = None,
+        analyze_level: ExplainAnalyzeLevel | None = None,
+        analyze_categories: Iterable[ExplainMetricCategory] | None = None,
     ) -> None:
         """Print an explanation of the DataFrame's plan so far.
 
@@ -1217,6 +1246,13 @@ def explain(
             analyze: If ``True``, the plan will run and metrics reported.
             format: Output format for the plan. Defaults to
                 :py:attr:`ExplainFormat.INDENT`.
+            show_statistics: If ``True``, include each operator's statistics.
+                ``None`` uses the ``datafusion.explain.show_statistics`` setting.
+            analyze_level: Which metrics to report with ``analyze``. ``None``
+                uses the ``datafusion.explain.analyze_level`` setting.
+            analyze_categories: Report only metrics in these categories with
+                ``analyze``; an empty iterable reports none. ``None`` uses the
+                ``datafusion.explain.analyze_categories`` setting.
 
         Examples:
             Show the plan in tree format:
@@ -1229,9 +1265,22 @@ def explain(
             Show plan with runtime metrics:
 
             >>> df.explain(analyze=True)  # doctest: +SKIP
+
+            Show only row-count metrics:
+
+            >>> from datafusion import ExplainMetricCategory
+            >>> df.explain(
+            ...     analyze=True, analyze_categories=[ExplainMetricCategory.ROWS]
+            ... )  # doctest: +SKIP
         """
         fmt = format.value if format is not None else None
-        self.df.explain(verbose, analyze, fmt)
+        level = analyze_level.value if analyze_level is not None else None
+        categories = (
+            [c.value for c in analyze_categories]
+            if analyze_categories is not None
+            else None
+        )
+        self.df.explain(verbose, analyze, fmt, show_statistics, level, categories)
 
     def logical_plan(self) -> LogicalPlan:
         """Return the unoptimized ``LogicalPlan``.

python/tests/test_dataframe.py

@@ -29,7 +29,9 @@
 import pytest
 from datafusion import (
     DataFrame,
+    ExplainAnalyzeLevel,
     ExplainFormat,
+    ExplainMetricCategory,
     InsertOp,
     ParquetColumnOptions,
     ParquetWriterOptions,
@@ -3871,6 +3873,57 @@ def test_explain_with_format(capsys, fmt, verbose, analyze, expected_substring):
         assert expected_substring in captured.out
 
 
+def _explain_output(capsys, **kwargs):
+    ctx = SessionContext()
+    df = ctx.from_pydict({"a": [1, 2]}).filter(column("a") > literal(1))
+    df.explain(**kwargs)
+    return capsys.readouterr().out
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "present", "absent"),
+    [
+        pytest.param({}, [], ["statistics="], id="default_no_statistics"),
+        pytest.param(
+            {"show_statistics": True}, ["statistics=[Rows="], [], id="show_statistics"
+        ),
+        pytest.param(
+            {"analyze": True, "analyze_level": ExplainAnalyzeLevel.DEV},
+            ["output_rows=", "output_batches="],
+            [],
+            id="analyze_level_dev",
+        ),
+        pytest.param(
+            {"analyze": True, "analyze_level": ExplainAnalyzeLevel.SUMMARY},
+            ["output_rows="],
+            ["output_batches="],
+            id="analyze_level_summary",
+        ),
+        pytest.param(
+            {
+                "analyze": True,
+                "analyze_categories": [ExplainMetricCategory.ROWS],
+            },
+            ["output_rows="],
+            ["elapsed_compute=", "output_bytes="],
+            id="analyze_categories_rows",
+        ),
+        pytest.param(
+            {"analyze": True, "analyze_categories": []},
+            ["FilterExec: a@0 > 1, metrics=[]"],
+            ["output_rows="],
+            id="analyze_categories_empty_suppresses_metrics",
+        ),
+    ],
+)
+def test_explain_options(capsys, kwargs, present, absent):
+    out = _explain_output(capsys, **kwargs)
+    for text in present:
+        assert text in out
+    for text in absent:
+        assert text not in out
+
+
 @pytest.mark.parametrize(
     ("window_exprs", "expected_columns"),
     [