Python API#

介绍#

Polars SQL 接口有四个主要入口点，每个入口点在不同的粒度级别上操作。首先是 SQLContext 对象，一个顶层的 polars.sql() 函数，它在全局上下文中操作，框架级别的 DataFrame.sql() 和 LazyFrame.sql() 方法，以及 polars.sql_expr() 函数，它从 SQL 创建原生表达式。

查询#

SQL查询可以针对当前全局变量中的兼容数据结构、特定框架发出，或合并到表达式中。

全局SQL#

无论是 SQLContext 还是 polars.sql() 函数，都可以用于通过 Polars 执行引擎对 Polars 的 DataFrame、LazyFrame 和 Series 数据执行 SQL 查询，同时也可以对 Pandas 的 DataFrame 和 Series，以及 PyArrow 的 Table 和 RecordBatch 对象执行查询。非 Polars 对象在 SQL 查询中使用时会被隐式转换为 DataFrame；对于使用 PyArrow 数据类型的 PyArrow 和 Pandas 数据，如果底层数据能够清晰地映射到原生支持的数据类型，这种转换通常可以是零拷贝的。

示例：

import polars as pl
import pandas as pd

polars_df = pl.DataFrame({"a": [1, 2, 3, 4], "b": [4, 5, 6, 7]})
pandas_df = pd.DataFrame({"a": [3, 4, 5, 6], "b": [6, 7, 8, 9]})
polars_series = (polars_df["a"] * 2).rename("c")
pyarrow_table = polars_df.to_arrow()

pl.sql(
    """
    SELECT a, b, SUM(c) AS c_total FROM (
      SELECT * FROM polars_df                  -- polars frame
        UNION ALL SELECT * FROM pandas_df      -- pandas frame
        UNION ALL SELECT * FROM pyarrow_table  -- pyarrow table
    ) all_data
    INNER JOIN polars_series
      ON polars_series.c = all_data.b          -- polars series
    GROUP BY "a", "b"
    ORDER BY "a", "b"
    """
).collect()

# shape: (3, 3)
# ┌─────┬─────┬─────────┐
# │ a   ┆ b   ┆ c_total │
# │ --- ┆ --- ┆ ---     │
# │ i64 ┆ i64 ┆ i64     │
# ╞═════╪═════╪═════════╡
# │ 1   ┆ 4   ┆ 8       │
# │ 3   ┆ 6   ┆ 18      │
# │ 5   ┆ 8   ┆ 8       │
# └─────┴─────┴─────────┘

另请参阅

SQLContext

框架SQL#

直接针对特定的底层eager/lazy框架执行SQL，将其引用为“self”；返回一个表示查询结果的新框架。

示例：

import polars as pl

df = pl.DataFrame({
    "a": [1, 2, 3],
    "b": [4, 5, 6],
})
df.sql("""
  SELECT a::uint4, (b * b) AS bb
  FROM self WHERE a != 2
""")

# shape: (2, 2)
# ┌─────┬─────┐
# │ a   ┆ bb  │
# │ --- ┆ --- │
# │ u32 ┆ i64 │
# ╞═════╪═════╡
# │ 1   ┆ 16  │
# │ 3   ┆ 36  │
# └─────┴─────┘

表达式 SQL#

polars.sql_expr() 函数可用于从SQL片段创建本地的Polars表达式。

示例：

import polars as pl

df = pl.DataFrame({
    "a": [1, 2, 3],
    "b": [4, 5, 6],
})
df.with_columns(
    pl.sql_expr("(a * a) + (b::float / 2) AS expr1"),
    pl.sql_expr("CONCAT_WS(':',a,b) AS expr2")
)

# shape: (3, 4)
# ┌─────┬─────┬───────┬───────┐
# │ a   ┆ b   ┆ expr1 ┆ expr2 │
# │ --- ┆ --- ┆ ---   ┆ ---   │
# │ i64 ┆ i64 ┆ f64   ┆ str   │
# ╞═════╪═════╪═══════╪═══════╡
# │ 1   ┆ 4   ┆ 3.0   ┆ 1:4   │
# │ 2   ┆ 5   ┆ 6.5   ┆ 2:5   │
# │ 3   ┆ 6   ┆ 12.0  ┆ 3:6   │
# └─────┴─────┴───────┴───────┘

SQLContext#

Polars 提供了一个专用的类用于查询框架数据，该类提供了对表注册和状态管理的额外控制，并且也可以用作上下文管理器。这就是 SQLContext 对象，它提供了其他 SQL 函数所使用的所有核心功能。

class polars.SQLContext[source]#

对DataFrame/LazyFrame数据运行SQL查询。

__init__(

frames: Mapping[str, CompatibleFrameType | None] | None = None,

*,

register_globals: bool | int = False,

eager: bool = False,

**named_frames: CompatibleFrameType | None,

) → None[source]#

初始化一个新的 SQLContext。

Parameters:

frames: 一个{name:frame, ...}映射，可以包括Polars框架和pandas的DataFrames、Series以及pyarrow的Table和RecordBatch对象。
register_globals: 注册在全局变量中找到的兼容对象（polars DataFrame、LazyFrame 和 Series），自动将它们的变量名映射到表名。要注册其他对象（pandas/pyarrow 数据），请显式传递它们，或调用 execute_global 类方法。如果给定一个整数，则只注册找到的最新的“n”个对象。
eager: 如果为True，返回执行结果为DataFrame而不是LazyFrame。（请注意，查询本身始终以惰性模式执行；此参数影响execute()返回的是急切还是惰性的结果框架）。
**named_frames: 命名的急切/惰性框架，作为kwargs提供。

示例

>>> lf = pl.LazyFrame({"a": [1, 2, 3], "b": ["x", None, "z"]})
>>> res = pl.SQLContext(frame=lf).execute(
...     "SELECT b, a*2 AS two_a FROM frame WHERE b IS NOT NULL"
... )
>>> res.collect()
shape: (2, 2)
┌─────┬───────┐
│ b   ┆ two_a │
│ --- ┆ ---   │
│ str ┆ i64   │
╞═════╪═══════╡
│ x   ┆ 2     │
│ z   ┆ 6     │
└─────┴───────┘

注意： 也可以用作上下文管理器。

__enter__() → SQLContext[FrameType][source]#: 在进入作用域时跟踪当前注册的表；支持嵌套作用域。

__exit__( exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None, ) → None[source]#

在上下文退出时注销在给定范围内创建的任何表。

另请参阅

unregister

方法#

`SQLContext.execute`(query, *[, eager])	解析给定的SQL查询并在注册的框架数据上执行它。
`SQLContext.execute_global`(query, *[, eager])	立即执行SQL查询，自动注册框架全局变量。
`SQLContext.register`(name, frame)	使用给定的名称将单个帧注册为表。
`SQLContext.register_globals`([n, all_compatible])	注册在当前全局作用域中找到的所有框架（惰性或急切）。
`SQLContext.register_many`([frames])	使用关联的名称将多个急切/懒加载的帧注册为表格。
`SQLContext.tables`()	返回已注册表名的列表。
`SQLContext.unregister`(names)	通过名称注销一个或多个急切/懒加载框架。

示例：

import polars as pl

df1 = pl.DataFrame({"id": [1, 2, 3], "value": [0.1, 0.2, 0.3]})
df2 = pl.DataFrame({"id": [3, 2, 1], "value": [25.6, 53.4, 12.7]})

with pl.SQLContext(df_a=df1, df_b=df2, eager=True) as ctx:
    df = ctx.execute("""
      SELECT
        a.id,
        a.value AS value_a,
        b.value AS value_b
      FROM df_a AS a INNER JOIN df_b AS b USING (id)
      ORDER BY id
    """)

    # shape: (3, 3)
    # ┌─────┬─────────┬─────────┐
    # │ id  ┆ value_a ┆ value_b │
    # │ --- ┆ ---     ┆ ---     │
    # │ i64 ┆ f64     ┆ f64     │
    # ╞═════╪═════════╪═════════╡
    # │ 1   ┆ 0.1     ┆ 25.6    │
    # │ 2   ┆ 0.2     ┆ 53.4    │
    # │ 3   ┆ 0.3     ┆ 12.7    │
    # └─────┴─────────┴─────────┘

另请参阅

pl.sql