polars.SQLContext.execute_global

classmethod SQLContext.execute_global(

query: str,

*,

eager: bool = False,

) → DataFrame | LazyFrame

Immediately execute a SQL query, automatically registering frame globals.

Parameters:

query

A valid SQL query string.

eager

If True, returns execution results as DataFrame instead of LazyFrame. (Note that the query itself is always executed in lazy-mode).

Notes

• This convenience method automatically registers all compatible objects in the local stack that are referenced in the query, mapping their variable name to a table name. Note that in addition to polars DataFrame, LazyFrame, and Series this method also registers pandas DataFrame, Series, and pyarrow Table and RecordBatch objects.

• Instead of calling this classmethod you should consider using pl.sql, which will use this code internally.

Examples

>>> import pandas as pd
>>> df = pl.LazyFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
>>> df_pandas = pd.DataFrame({"a": [2, 3, 4], "c": [7, 8, 9]})

Join a polars LazyFrame with a pandas DataFrame (note use of the preferred pl.sql method, which is equivalent to SQLContext.execute_global):

>>> pl.sql("SELECT df.*, c FROM df JOIN df_pandas USING(a)").collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 2   ┆ 5   ┆ 7   │
│ 3   ┆ 6   ┆ 8   │
└─────┴─────┴─────┘