Polars · Module

.explain

Returns a string representation of a LazyFrame's query plan. It can show plain or tree output and expose optimized planning, engine selection, and optimization settings.

How it works

Call this method on a LazyFrame to obtain a textual representation of its query plan. You can choose plain or tree output, request the optimized or unoptimized plan, and select the execution engine; optimization flags further control which optimization passes are applied.

Syntax

LazyFrame.explain(*, format: ExplainFormat = 'plain', optimized: bool = True, engine: EngineType = 'auto', optimizations: QueryOptFlags = ()) -> str

Parameters

Name	Type	Description
`format`	`ExplainFormat = 'plain'`	Display format for the logical plan: `plain` or `tree`.
`optimized`	`bool = True`	Whether to return an optimized query plan; defaults to `True`.
`engine`	`EngineType = 'auto'`	Engine used to process the query; defaults to `auto`.
`optimizations`	`QueryOptFlags = ()`	Optimization passes to apply.

Returns

str

Key points

The method returns the query plan as a string, making it useful for inspecting lazy execution.
Optimization behavior is configurable rather than fixed.
Choose the display format for the logical plan with format.
Set optimized to control whether the displayed plan is optimized.
Use engine to choose how the query should be processed.

Common mistakes

When optimized is true, the optimization-related settings determine which optimization passes are applied.
The streaming engine processes data in batches, which can reduce memory pressure and may improve performance.

Example: Inspect an optimized lazy query plan

import polars as pl

lf = pl.LazyFrame({"group": ["a", "a", "b"], "value": [1, 2, 3]})
plan = (
    lf.group_by("group")
      .agg(pl.col("value").sum())
      .sort("group")
      .explain(format="tree", optimized=True)
)
print(plan)

Builds a lazy aggregation and prints its optimized query plan in tree form.

When to use it

Inspect query structure

Debugging lazy pipelines

Evaluate optimization effects

Comparing planner behavior

Assess engine choices

Managing large lazy workloads

Interview questions

QWhat does LazyFrame.explain return and what are its main defaults?

LazyFrame.explain returns a string containing the query plan. By default it requests an optimized plan and uses the automatic engine selection.

Follow-up: How would you make the plan easier to inspect structurally? Use format="tree" instead of the default plain format.

QHow do format and optimized affect the result?

The format argument controls whether the logical plan is displayed as plain or tree. The optimized argument controls whether the returned plan reflects optimization.

Follow-up: What happens when optimized=True? The optimization flags determine which optimization passes run.

QWhat is the purpose of the engine argument?

The engine argument selects the processing engine and defaults to auto. It also supports the in-memory and streaming engines.

Follow-up: When might streaming be useful? It processes queries in batches, helping reduce memory pressure for suitable workloads.

polars.LazyFrame
polars.LazyFrame.collect
polars.explain_all

Source: polars.LazyFrame.explain — Polars documentation. Checked 2026-10-15.