Implementation:Pola rs Polars SQLContext Constructor

Overview

Concrete API usage for creating and configuring a Polars SQLContext instance. This implementation covers the constructor signatures, parameter options, and initialization patterns for establishing an SQL execution environment over Polars DataFrames and LazyFrames.

Metadata

Field	Value
Namespace	Pola_rs_Polars
Workflow	SQL_Query_Interface
Implementation_ID	Pola_rs_Polars_SQLContext_Constructor
Type	Implementation
Category	Data Access / Query Interface
Stage	Context Initialization
last_updated	2026-02-09 10:00 GMT
Source_Repository	https://github.com/pola-rs/polars
Source_File	docs/source/src/python/user-guide/sql/intro.py:L6-21
Documentation	https://docs.pola.rs

API Signatures

Primary Constructor

pl.SQLContext(eager=False, **frames) -> SQLContext

With Global Registration

pl.SQLContext(register_globals=False, eager=False) -> SQLContext

With Dictionary Registration

pl.SQLContext(frames=dict) -> SQLContext

Key Parameters

Parameter	Type	Default	Description
eager	bool	False	When True, execute() returns a DataFrame (immediate materialization). When False (default), execute() returns a LazyFrame (deferred evaluation).
register_globals	bool	False	When True, automatically registers all DataFrames and LazyFrames found in the caller's global scope as named tables.
frames	dict	None	A dictionary mapping table name strings to DataFrame or LazyFrame objects.
**frames	keyword args	—	Frames passed as keyword arguments are registered with the keyword as the table name.

I/O Contract

Direction	Type	Description
Input	DataFrame / LazyFrame	Data sources passed via kwargs, frames dict, or global registration
Input	bool (eager)	Controls whether execute() returns DataFrame or LazyFrame
Input	bool (register_globals)	Auto-register all frames in caller scope
Output	SQLContext	Fully configured SQL execution context

Implementation Examples

Empty Context

import polars as pl

# Create an empty context with no registered tables
ctx = pl.SQLContext()

With Explicit Frames via Dictionary

import polars as pl

df = pl.DataFrame({"a": [1, 2, 3]})
lf = pl.LazyFrame({"b": [4, 5, 6]})

# Register frames using a dictionary mapping names to frames
ctx = pl.SQLContext(frames={"table_one": df, "table_two": lf})

With Keyword Arguments

import polars as pl

df = pl.DataFrame({"a": [1, 2, 3]})
lf = pl.LazyFrame({"b": [4, 5, 6]})

# Register frames using keyword arguments (keyword becomes table name)
ctx = pl.SQLContext(df=df, lf=lf)

Auto-Register Globals

import polars as pl

# All DataFrames and LazyFrames in the caller's global scope
# are automatically registered as tables
ctx = pl.SQLContext(register_globals=True)

Eager Mode

import polars as pl

df = pl.DataFrame({"a": [1, 2, 3]})

# Eager mode: all execute() calls return DataFrame directly
ctx = pl.SQLContext(eager=True, my_table=df)

Behavioral Notes

When both frames (dict) and keyword arguments are provided, all sources are registered. If a name conflict occurs, the keyword argument takes precedence.
DataFrames passed to the context are implicitly converted to LazyFrames for query planning purposes. The original DataFrame is not modified.
The eager flag sets the default materialization behavior. It can be overridden on a per-query basis by passing eager=True or eager=False to the execute() method.
register_globals inspects the caller's frame for variables that are DataFrame or LazyFrame instances and registers them using the variable name as the table name.

Relationships

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment