Implementation:Pola rs Polars LazyFrame Explain Show Graph

Overview

This implementation covers the concrete APIs for inspecting and visualizing query plans of a LazyFrame. The explain() method produces a human-readable text representation of the query plan, while show_graph() renders a graphical visualization using Graphviz. Both methods support viewing either the raw logical plan or the optimized physical plan.

APIs

• LazyFrame.explain(optimized: bool = True) -> str — Return a text representation of the query plan
• LazyFrame.show_graph(optimized: bool = True, show: bool = True, output_path: str = None) -> str — Render a Graphviz visualization of the query plan

Source Reference

• File: docs/source/src/python/user-guide/lazy/query-plan.py (Lines 1-51)
• Repository: Pola_rs_Polars

I/O Contract

Direction	Type	Description
Input	LazyFrame	A LazyFrame containing a query plan with one or more operations
Output (explain)	str	A multi-line string describing the query plan nodes from root to leaves
Output (show_graph)	str	A Graphviz DOT string; optionally renders to a PNG file or displays a window

Key Parameters

Parameter	Type	Default	Description
optimized	bool	True	If True, show the optimized physical plan; if False, show the raw logical plan
show	bool	True	If True, open a window displaying the graph (requires a display environment)
output_path	str	None	File path to save the rendered graph as a PNG image

Example Code

Text Plan Inspection

import polars as pl

q = (
    pl.scan_csv("data.csv")
    .filter(pl.col("value") > 5)
    .group_by("category")
    .agg(pl.col("value").mean())
)

# Print the optimized plan (default)
print(q.explain())

# Print the unoptimized logical plan
print(q.explain(optimized=False))

Graph Visualization

import polars as pl

q = (
    pl.scan_csv("data.csv")
    .filter(pl.col("value") > 5)
    .group_by("category")
    .agg(pl.col("value").mean())
)

# Save the optimized plan as a PNG
q.show_graph(show=False, output_path="query_plan.png")

# Save the unoptimized plan as a PNG
q.show_graph(optimized=False, show=False, output_path="logical_plan.png")

Comparing Optimized vs Unoptimized Plans

import polars as pl

q = (
    pl.scan_csv("data.csv")
    .select(pl.col("a"), pl.col("b"), pl.col("c"))
    .filter(pl.col("a") > 10)
)

print("=== LOGICAL PLAN ===")
print(q.explain(optimized=False))
# Shows: FILTER -> SELECT -> SCAN
# The filter is after the select in the logical plan

print("=== OPTIMIZED PLAN ===")
print(q.explain(optimized=True))
# Shows: SCAN with pushed-down predicate (a > 10) and projection [a, b, c]
# The optimizer pushed the filter and projection into the scan node

Import

import polars as pl

Behavior Notes

• explain() does not execute the query: It only computes the plan representation. No data is read or processed.
• Optimized plan shows pushdowns: In the optimized plan, predicates and projections that have been pushed down appear as annotations on the scan node rather than as separate plan nodes.
• show_graph() requires Graphviz: The graphviz Python package and the Graphviz system binary must be installed for graph rendering. Without them, the DOT string is returned but cannot be rendered.
• Plan text format: The text plan reads top-to-bottom, with the root (final output) at the top and leaf nodes (scans) at the bottom. Indentation indicates parent-child relationships.
• Non-destructive: Both methods return information without modifying the LazyFrame or its query plan.

Related Pages

• Principle:Pola_rs_Polars_Query_Plan_Inspection
• Implementation:Pola_rs_Polars_LazyFrame_Expression_Chaining
• Implementation:Pola_rs_Polars_LazyFrame_Collect

Metadata

Field	Value
Source Repository	Pola_rs_Polars
Source File	docs/source/src/python/user-guide/lazy/query-plan.py:L1-51
Domain	Data Engineering, Query Optimization, Debugging
Last Updated	2026-02-09 10:00 GMT