polars.Series.sql#

Series.sql(query: str_, *, table_name: str_ = 'self') → DataFrame[source]#

Execute a SQL query against the Series.

Added in version 1.37.0.

Warning

This functionality is considered unstable, although it is close to being considered stable. It may be changed at any point without it being considered a breaking change.

Parameters:
query

SQL query to execute.

table_name

Optionally provide an explicit name for the table that represents the calling frame (defaults to “self”).

See also

SQLContext

Notes

  • The calling Series is automatically registered as a table in the SQLContext under the name “self”. If you want access to the DataFrames, LazyFrames, and other Series found in the current globals, use pl.sql.

  • More control over registration and execution behaviour is available by using the SQLContext object.

  • The SQL query executes in lazy mode before being collected and returned as a DataFrame.

  • It is recommended to name your Series for use with SQL, otherwise the default Series name (an empty string) is used; while "" is valid, it is awkward.

Examples

>>> from datetime import date
>>> s = pl.Series(
...     name="dt",
...     values=[date(1999, 12, 31), date(2099, 2, 14), date(2026, 3, 5)],
... )

Query the Series using SQL:

>>> s.sql('''
...     SELECT
...       EXTRACT('year',dt) AS y,
...       EXTRACT('month',dt) AS m,
...       EXTRACT('day',dt) AS d,
...     FROM self
...     WHERE dt > '2020-01-01'
...     ORDER BY dt DESC
... ''')
shape: (2, 3)
┌──────┬─────┬─────┐
│ y    ┆ m   ┆ d   │
│ ---  ┆ --- ┆ --- │
│ i32  ┆ i8  ┆ i8  │
╞══════╪═════╪═════╡
│ 2099 ┆ 2   ┆ 14  │
│ 2026 ┆ 3   ┆ 5   │
└──────┴─────┴─────┘

While you can refer to an unnamed Series column using the default empty string, it is not recommended:

>>> s = pl.Series([1, 2, 3])
>>> s.sql('SELECT "" AS x, "" * 2 AS "2x" FROM self')
shape: (3, 2)
┌─────┬─────┐
│ x   ┆ 2x  │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 2   │
│ 2   ┆ 4   │
│ 3   ┆ 6   │
└─────┴─────┘
On this page