Implementation:Pola rs Polars Streaming Show Graph

Knowledge Sources	Polars Polars Docs
Domains	Data Engineering, Streaming
Last Updated	2026-02-09 10:00 GMT

Overview

Concrete methods for visualizing and inspecting the physical streaming query plan, including graphical rendering via show_graph and text-based inspection via explain.

Description

Polars provides two complementary methods for inspecting query plans:

• show_graph -- Renders the query plan as a visual graph. When configured with plan_stage="physical" and engine="streaming", it produces a graph showing the streaming-specific physical execution plan with operator annotations and data flow edges.
• explain -- Returns a text representation of the optimized query plan, showing the tree of operations and which optimizations (predicate pushdown, projection pushdown) have been applied.

The show_graph method can display the graph in an interactive window (show=True) or save it to a PNG file (output_path="file.png"). It returns the DOT-format string representation of the graph.

Usage

Use these methods whenever you need to:

• Visualize the physical streaming plan to verify streaming execution.
• Identify pipeline breakers in the execution graph.
• Inspect optimizer transformations applied to a query.
• Save plan visualizations for documentation or debugging.

Code Reference

Source Location

• Repository: Polars
• File: docs/source/src/python/user-guide/concepts/streaming.py (lines 46-51)

Signature

class LazyFrame:
    def show_graph(
        self,
        *,
        plan_stage: str = "logical",   # "logical" or "physical"
        engine: str = "cpu",           # "cpu" or "streaming"
        show: bool = True,             # display in interactive window
        output_path: str | None = None, # save to PNG file
    ) -> str: ...

    def explain(
        self,
        *,
        optimized: bool = True,  # show optimized plan (default) or unoptimized
    ) -> str: ...

Import

import polars as pl

I/O Contract

Inputs

Name	Type	Required	Description
plan_stage (show_graph)	str	No	Plan stage to visualize: "logical" or "physical". Use "physical" for streaming plans.
engine (show_graph)	str	No	Execution engine: "streaming" to see the streaming physical plan
show (show_graph)	bool	No	If True, open the graph in an interactive viewer window. Default is True.
output_path (show_graph)	None	No	File path to save the graph as a PNG image. If None, the graph is not saved.
optimized (explain)	bool	No	If True (default), show the optimized plan with pushdown annotations. If False, show the raw unoptimized plan.

Outputs

Name	Type	Description
result (show_graph)	str	DOT-format string representation of the query plan graph
result (explain)	str	Human-readable text representation of the query plan tree

Usage Examples

Visualize Streaming Physical Plan

import polars as pl

q = (
    pl.scan_csv("data.csv")
    .filter(pl.col("sepal_length") > 5)
    .group_by("species")
    .agg(
        mean_width=pl.col("sepal_width").mean(),
        mean_width2=pl.col("sepal_width").sum() / pl.col("sepal_length").count(),
    )
)

# Visualize streaming plan and save as PNG
q.show_graph(
    plan_stage="physical",
    engine="streaming",
    show=False,
    output_path="streaming_plan.png",
)

Text-Based Plan Inspection

import polars as pl

q = (
    pl.scan_csv("data.csv")
    .filter(pl.col("sepal_length") > 5)
    .group_by("species")
    .agg(pl.col("sepal_width").mean())
)

# Print the optimized plan
print(q.explain(optimized=True))

# Example output:
# AGGREGATE
#   [col("sepal_width").mean()] BY [col("species")]
#   FROM:
#     CSV SCAN data.csv
#       PROJECT 3/5 COLUMNS
#       SELECTION: [(col("sepal_length")) > (5.0)]

Compare Optimized vs Unoptimized Plans

import polars as pl

q = (
    pl.scan_parquet("dataset/*.parquet")
    .select("name", "age", "salary", "department")
    .filter(pl.col("age") > 30)
    .group_by("department")
    .agg(pl.col("salary").mean())
)

# Unoptimized plan -- filter after select
print("=== Unoptimized ===")
print(q.explain(optimized=False))

# Optimized plan -- filter pushed down to scan
print("=== Optimized ===")
print(q.explain(optimized=True))

Save Graph for Documentation

import polars as pl

q = (
    pl.scan_parquet("sales/*.parquet")
    .filter(pl.col("amount") > 0)
    .group_by("region")
    .agg(pl.col("amount").sum())
)

# Save both logical and physical streaming plans
dot_logical = q.show_graph(
    plan_stage="logical",
    show=False,
    output_path="logical_plan.png",
)

dot_physical = q.show_graph(
    plan_stage="physical",
    engine="streaming",
    show=False,
    output_path="physical_streaming_plan.png",
)

Related Pages

Implements Principle

• Principle:Pola_rs_Polars_Streaming_Plan_Profiling