Implementation:Eventual Inc Daft DataFrame Explain
| Knowledge Sources | |
|---|---|
| Domains | Data_Engineering, Query_Optimization |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Concrete tool for printing the logical and physical execution plans of a DataFrame query provided by the Daft library.
Description
The explain method on Daft's DataFrame class prints the query plans that will be used to execute the DataFrame. By default, it shows only the unoptimized logical plan. With show_all=True, it additionally shows the optimized logical plan and the physical execution plan. It supports ASCII text output and Mermaid diagram format for graphical rendering. The method is aware of cached results and will indicate when computation will be skipped.
Usage
Use df.explain() to inspect how a DataFrame query will be executed. This is a method on DataFrame instances useful during development for performance tuning and understanding query behavior.
Code Reference
Source Location
- Repository: Daft
- File:
daft/dataframe/dataframe.py - Lines: L223-324
Signature
def explain(
self,
show_all: bool = False,
format: str = "ascii",
simple: bool = False,
file: io.IOBase | None = None,
) -> Any
Import
import daft
# Method on DataFrame - no separate import needed
df.explain()
df.explain(show_all=True)
df.explain(format="mermaid")
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| show_all | bool | No | Whether to show the optimized logical plan and physical plan in addition to the unoptimized plan. Defaults to False. |
| format | str | No | Output format: "ascii" for text tree or "mermaid" for diagram. Defaults to "ascii". |
| simple | bool | No | Whether to show only operation types without configuration details. Defaults to False. |
| file | io.IOBase or None | No | File object to write output to. Defaults to None (stdout). |
Outputs
| Name | Type | Description |
|---|---|---|
| return | None, str, or MermaidFormatter | For "ascii" format: None (prints to stdout/file). For "mermaid" in notebook: MermaidFormatter instance. For "mermaid" outside notebook: string representation. |
Usage Examples
Basic Usage
import daft
df = daft.from_pydict({"x": [1, 2, 3]})
df = df.where(daft.col("x") > 1).select("x")
# Show unoptimized logical plan
df.explain()
# Output:
# == Unoptimized Logical Plan ==
# * Project: col(x)
# |
# * Filter: col(x) > 1
# |
# * Source: ...
Full Plan with Optimizations
import daft
df = daft.from_pydict({"x": [1, 2, 3]})
df = df.where(daft.col("x") > 1).select("x")
# Show all plan stages including physical plan
df.explain(show_all=True)