Polars · Module

.collect

Executes a LazyFrame query and materializes its result as a DataFrame. It supports configurable engines, optimization controls, streaming execution, and optional background execution.

How it works

Call collect on a LazyFrame to execute its deferred query plan and produce a concrete result. The method can use different execution engines, run in the background, and accept optimization settings; streaming execution processes the query in batches to reduce memory pressure.

Syntax

LazyFrame.collect(*, engine: EngineType = 'auto', background: bool = False, optimizations: QueryOptFlags = (), **_kwargs: Any) → DataFrame | InProcessQuery

Parameters

Name	Type	Description
`engine`	`EngineType = 'auto'`	Execution engine to use; defaults to `"auto"`. Supported names include `"auto"`, `"in-memory"`, `"streaming"`, and `"gpu"`.
`background`	`bool = False`	Run asynchronously in the background and return an in-process query handle.
`optimizations`	`QueryOptFlags = ()`	Query optimization flags controlling enabled optimizations.
`_kwargs`	`Any`	Additional keyword arguments accepted by the method.

Returns

DataFrame when executed normally; an InProcessQuery handle when background=True.

Key points

Calling collect turns deferred LazyFrame operations into an eagerly available DataFrame.
Collection uses the optimizer by default, so the lazy plan is optimized before execution.
The engine parameter controls which execution backend processes the query.
With the default engine selection, Polars falls back to the streaming engine when no affinity setting overrides it.
Background collection returns a handle that supports retrieving the result or cancelling execution.

Common mistakes

Streaming can reduce memory pressure, but it is an execution choice rather than an automatic guarantee that every query uses less memory.
With background=True, the return value is a query handle rather than the completed DataFrame.

Example: Collect a lazy query

import polars as pl

lf = pl.LazyFrame({"value": [1, 2, 3]})
result = (
    lf.filter(pl.col("value") > 1)
    .select((pl.col("value") * 10).alias("scaled"))
    .collect()
)
print(result)

Builds a lazy query, then materializes its optimized result as a DataFrame.

When to use it

Materialize lazy results

Run a deferred transformation pipeline and obtain a concrete DataFrame for analysis or output.

Stream execution

Process queries in batches when the in-memory execution path creates excessive memory pressure.

Background collection

Start a long-running query without blocking the calling workflow.

Interview questions

QWhat does LazyFrame.collect do?

collect materializes a LazyFrame into a DataFrame. Lazy operations remain deferred until this call, allowing Polars to optimize the query before execution.

Follow-up: How would you lower memory pressure? Use engine="streaming", which executes the query in batches.

QWhich execution engines can collect use?

The default engine is "auto". Other documented choices include "in-memory", "streaming", and "gpu"; the GPU engine requires an Nvidia GPU and cudf-polars.

Follow-up: When is the GPU engine unsuitable? It is unsuitable when the required CUDA and cuDF-based Polars setup is unavailable.

QHow does optimization interact with collection?

By default, query optimizations are enabled. The optimizations argument lets callers disable individual optimizations through query optimization flags.

Follow-up: How can the evaluated plan be inspected? Use the related explain method to print the query plan evaluated by collect.

polars.LazyFrame.explain
polars.LazyFrame.profile
polars.collect_all
polars.LazyFrame.collect_async

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