Polars · Module

df.lazy

Starts a lazy query from an existing DataFrame and returns a LazyFrame. Operations remain deferred until Polars executes or inspects the plan.

How it works

Calling df.lazy() converts the existing DataFrame into a LazyFrame query plan. Subsequent lazy operations are deferred, allowing Polars to optimize and parallelize the query before a trigger such as collect(), explain(), show_graph(), or collect_schema() executes or inspects it.

Syntax

DataFrame.lazy() → LazyFrame

Returns

LazyFrame

Key points

Use df.lazy() to begin a deferred query from an existing DataFrame.
The method's return value is a LazyFrame.
collect() executes the lazy query across the complete dataset.
explain() prints the query plan for inspection.
show_graph() presents the query plan as a Graphviz graph.
collect_schema() returns the schema expected after the lazy query.
Lazy operations enable query optimization and additional parallelism.

Common mistakes

Creating a LazyFrame does not run the query; an execution or inspection trigger is required.

Example: Create and execute a lazy query

import polars as pl

df = pl.DataFrame({"x": [1, 2, 3]})
result = (
    df.lazy()
    .filter(pl.col("x") > 1)
    .collect()
)
print(result)

Builds a lazy filter query and executes it with collect().

When to use it

Build optimized pipelines

Compose filters, projections, joins, and aggregations before execution so Polars can optimize the complete plan.

Review query plans

Inspect execution behavior before running a potentially expensive query.

Defer execution

Keep query construction separate from execution in reusable data-processing functions.

Interview questions

QWhat does DataFrame.lazy() return, and when is the query executed?

df.lazy() returns a LazyFrame that represents a deferred query plan rather than immediately producing a result. The plan runs when a trigger such as collect() is called.

Follow-up: How can the plan be inspected without materializing the result? Call explain(), or use show_graph() for a Graphviz representation.

QWhy use df.lazy() instead of applying eager operations immediately?

Lazy execution lets Polars optimize the complete query and can provide additional parallelism before execution. This is why lazy operations are recommended in the documentation.

Follow-up: Which trigger returns the final schema without collecting the data? Use collect_schema().

QWhich methods trigger or inspect a LazyFrame?

The lazy plan can be inspected or triggered with collect(), explain(), show_graph(), or collect_schema(). collect() runs the query on all data, while the other methods inspect or derive planning information.

Follow-up: What issue can arise when collecting several branches from one LazyFrame? Each branch may re-evaluate shared work; pl.collect_all can execute related plans together.

polars.LazyFrame
polars.LazyFrame.collect
polars.LazyFrame.explain
polars.LazyFrame.show_graph
polars.LazyFrame.collect_schema

Source: polars.DataFrame.lazy — Polars documentation. Checked 2026-10-15.