LazyFrame#

本页面提供了所有公共LazyFrame方法的概述。

class polars.LazyFrame( data: FrameInitTypes | None = None, schema: SchemaDefinition | None = None, *, schema_overrides: SchemaDict | None = None, strict: bool = True, orient: Orientation | None = None, infer_schema_length: int | None = 100, nan_to_null: bool = False, )[source]

表示针对DataFrame的惰性计算图/查询。

这允许在并行性之外进行整个查询优化，并且是polars的首选（也是最高性能的）操作模式。

Parameters:

datadict, Sequence, ndarray, Series, or pandas.DataFrame

二维数据以各种形式存在；字典输入必须包含序列、生成器或range。序列可能包含系列或其他序列。

schemaSequence of str, (str,DataType) pairs, or a {str:DataType,} dict

LazyFrame 的模式可以通过几种方式声明：

作为一个{名称:类型}对的字典；如果类型为None，它将自动推断。
作为列名的列表；在这种情况下，类型会自动推断。
作为（名称，类型）对的列表；这等同于字典形式。

如果您提供的列名列表与基础数据中的名称不匹配，此处提供的名称将覆盖它们。模式中提供的名称数量应与基础数据的维度相匹配。

schema_overridesdict, default None

支持类型指定或覆盖一个或多个列；请注意，从schema参数推断出的任何dtypes将被覆盖。

模式中的条目数量应与基础数据的维度相匹配，除非传递的是字典序列，在这种情况下可以声明部分模式以防止加载特定字段。

strictbool, default True

如果任何data值与给定或推断的列数据类型不完全匹配，则抛出错误。如果设置为False，不匹配数据类型的值将被强制转换为该数据类型，或者如果无法转换，则设置为null。

orient{‘col’, ‘row’}, default None

是否将二维数据解释为列或行。如果为None，则通过匹配列和数据维度来推断方向。如果这没有产生确定性的结果，则使用列方向。

infer_schema_lengthint or None

用于模式推断的最大扫描行数。如果设置为None，可能会扫描完整数据（这可能会很慢）。此参数仅适用于输入数据为行序列或生成器的情况；其他输入将按原样读取。

nan_to_nullbool, default False

如果数据来自一个或多个numpy数组，可以选择将输入数据中的np.nan值转换为null。对于所有其他输入数据，此操作无效。

注释

直接初始化 LazyFrame(...) 等同于 DataFrame(...).lazy()。

示例

直接从字典构建一个LazyFrame：

>>> data = {"a": [1, 2], "b": [3, 4]}
>>> lf = pl.LazyFrame(data)
>>> lf.collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

请注意，dtypes 自动推断为 Polars Int64：

>>> lf.collect_schema().dtypes()
[Int64, Int64]

要指定更详细/具体的框架模式，您可以提供schema参数，该参数是一个包含（名称，数据类型）对的字典…

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> lf2 = pl.LazyFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> lf2.collect()
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

…一系列（名称，数据类型）对…

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> lf3 = pl.LazyFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> lf3.collect()
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

…或一个类型化Series的列表。

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> lf4 = pl.LazyFrame(data)
>>> lf4.collect()
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

从numpy ndarray构建一个LazyFrame，指定列名：

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> lf5 = pl.LazyFrame(data, schema=["a", "b"], orient="col")
>>> lf5.collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

从列表的列表中构建一个LazyFrame，指定行方向：

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> lf6 = pl.LazyFrame(data, schema=["a", "b", "c"], orient="row")
>>> lf6.collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

方法:

`approx_n_unique`	唯一值的近似计数。
`bottom_k`	返回`k`个最小的行。
`cache`	一旦物理计划的执行到达此节点，就缓存结果。
`cast`	将LazyFrame列转换为指定的数据类型。
`clear`	创建一个当前LazyFrame的空副本，行数为零到'n'。
`clone`	创建此 LazyFrame 的副本。
`collect`	将此LazyFrame具体化为DataFrame。
`collect_async`	在线程池中异步收集DataFrame。
`collect_schema`	解析此LazyFrame的模式。
`count`	返回每列中非空元素的数量。
`describe`	创建一个LazyFrame的统计摘要，返回一个DataFrame。
`deserialize`	从文件中读取逻辑计划以构建LazyFrame。
`drop`	从DataFrame中移除列。
`drop_nans`	删除包含一个或多个NaN值的所有行。
`drop_nulls`	删除包含一个或多个空值的所有行。
`explain`	创建查询计划的字符串表示。
`explode`	将DataFrame通过展开给定列来转换为长格式。
`fetch`	收集少量行用于调试目的。
`fill_nan`	填充浮点数的NaN值。
`fill_null`	使用指定的值或策略填充空值。
`filter`	根据谓词表达式过滤LazyFrame中的行。
`first`	获取DataFrame的第一行。
`gather_every`	在LazyFrame中每隔n行取一行，并返回一个新的LazyFrame。
`group_by`	开始一个分组操作。
`group_by_dynamic`	基于时间值（或类型为Int32、Int64的索引值）进行分组。
`head`	获取前`n`行。
`inspect`	检查计算图中的一个节点。
`interpolate`	插值中间值。
`join`	向逻辑计划中添加一个连接操作。
`join_asof`	执行一个asof连接。
`join_where`	基于一个或多个（不）等式谓词执行连接。
`last`	获取DataFrame的最后一行。
`lazy`	返回惰性表示，即其本身。
`limit`	获取前`n`行。
`map_batches`	应用自定义函数。
`max`	将LazyFrame中的列聚合到它们的最大值。
`mean`	将LazyFrame中的列聚合为其平均值。
`median`	将LazyFrame中的列聚合到它们的中位数。
`melt`	将DataFrame从宽格式转换为长格式。
`merge_sorted`	取两个已排序的DataFrame并按排序键合并它们。
`min`	将LazyFrame中的列聚合为其最小值。
`null_count`	将LazyFrame中的列聚合为它们的空值计数的总和。
`pipe`	提供了一种结构化的方式来应用一系列用户定义的函数（UDFs）。
`profile`	分析一个LazyFrame。
`quantile`	将LazyFrame中的列聚合到它们的分位数值。
`rename`	重命名列名。
`reverse`	反转DataFrame。
`rolling`	基于时间或整数列创建滚动组。
`select`	从这个LazyFrame中选择列。
`select_seq`	从这个LazyFrame中选择列。
`serialize`	将此LazyFrame的逻辑计划序列化为JSON格式的文件或字符串。
`set_sorted`	指示一个或多个列已排序。
`shift`	将值按给定的索引数进行移动。
`show_graph`	显示查询计划的图表。
`sink_csv`	在流模式下评估查询并将结果写入CSV文件。
`sink_ipc`	在流模式下评估查询并将结果写入IPC文件。
`sink_ndjson`	在流模式下评估查询并将结果写入NDJSON文件。
`sink_parquet`	在流模式下评估查询并将结果写入Parquet文件。
`slice`	获取此DataFrame的一个切片。
`sort`	按给定的列对LazyFrame进行排序。
`sql`	对LazyFrame执行SQL查询。
`std`	将LazyFrame中的列聚合为其标准差值。
`sum`	将LazyFrame中的列聚合为其总和值。
`tail`	获取最后 `n` 行。
`top_k`	返回`k`个最大的行。
`unique`	从这个DataFrame中删除重复的行。
`unnest`	将结构体列分解为每个字段的单独列。
`unpivot`	将DataFrame从宽格式转换为长格式。
`update`	使用`other`中的值更新此`LazyFrame`中的值。
`var`	将LazyFrame中的列聚合为其方差值。
`with_columns`	向此LazyFrame添加列。
`with_columns_seq`	向此LazyFrame添加列。
`with_context`	向计算图添加外部上下文。
`with_row_count`	在第0列添加一个用于计算行数的列。
`with_row_index`	在LazyFrame中添加一行索引作为第一列。

属性：

`columns`	获取列名。
`dtypes`	获取列数据类型。
`schema`	获取列名到其数据类型的有序映射。
`width`	获取列数。

approx_n_unique() → LazyFrame[source]

唯一值的近似计数。

自版本0.20.11起已弃用：请改用select(pl.all().approx_n_unique())。

这是使用HyperLogLog++算法进行基数估计的。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.approx_n_unique().collect()  
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ u32 ┆ u32 │
╞═════╪═════╡
│ 4   ┆ 2   │
└─────┴─────┘

bottom_k( k: int, *, by: IntoExpr | Iterable[IntoExpr], reverse: bool | Sequence[bool] = False, ) → LazyFrame[source]

返回k个最小的行。

非空元素总是优先于空元素，无论reverse的值如何。输出不保证按任何特定顺序排列，如果您希望输出排序，请在此函数后调用sort()。

Parameters:

k: 返回的行数。
by: 用于确定底部行的列。接受表达式输入。字符串被解析为列名。
reverse: 考虑by列中的k个最大元素（而不是k个最小元素）。可以通过传递一个布尔值序列来为每列指定这一点。

另请参阅

top_k

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [2, 1, 1, 3, 2, 1],
...     }
... )

获取包含列b中4个最小值的行。

>>> lf.bottom_k(4, by="b").collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 1   │
│ a   ┆ 1   │
│ c   ┆ 1   │
│ a   ┆ 2   │
└─────┴─────┘

获取在列a和b上排序时包含4个最小值的行。

>>> lf.bottom_k(4, by=["a", "b"]).collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 1   │
│ a   ┆ 2   │
│ b   ┆ 1   │
│ b   ┆ 2   │
└─────┴─────┘

cache() → LazyFrame[source]

一旦物理计划的执行到达此节点，就缓存结果。

不建议使用此方法，因为优化器可能能够做得更好。

cast( dtypes: Mapping[ColumnNameOrSelector | PolarsDataType, PolarsDataType | PythonDataType] | PolarsDataType, *, strict: bool = True, ) → LazyFrame[source]

将LazyFrame列转换为指定的数据类型。

Parameters:

dtypes: 列名（或选择器）到数据类型的映射，或所有列将被转换的单一数据类型。
strict: 如果无法进行转换（例如，由于溢出），则抛出错误。

示例

>>> from datetime import date
>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": [date(2020, 1, 2), date(2021, 3, 4), date(2022, 5, 6)],
...     }
... )

将特定的帧列转换为指定的数据类型：

>>> lf.cast({"foo": pl.Float32, "bar": pl.UInt8}).collect()
shape: (3, 3)
┌─────┬─────┬────────────┐
│ foo ┆ bar ┆ ham        │
│ --- ┆ --- ┆ ---        │
│ f32 ┆ u8  ┆ date       │
╞═════╪═════╪════════════╡
│ 1.0 ┆ 6   ┆ 2020-01-02 │
│ 2.0 ┆ 7   ┆ 2021-03-04 │
│ 3.0 ┆ 8   ┆ 2022-05-06 │
└─────┴─────┴────────────┘

将所有匹配一种数据类型（或数据类型组）的框架列转换为另一种数据类型：

>>> lf.cast({pl.Date: pl.Datetime}).collect()
shape: (3, 3)
┌─────┬─────┬─────────────────────┐
│ foo ┆ bar ┆ ham                 │
│ --- ┆ --- ┆ ---                 │
│ i64 ┆ f64 ┆ datetime[μs]        │
╞═════╪═════╪═════════════════════╡
│ 1   ┆ 6.0 ┆ 2020-01-02 00:00:00 │
│ 2   ┆ 7.0 ┆ 2021-03-04 00:00:00 │
│ 3   ┆ 8.0 ┆ 2022-05-06 00:00:00 │
└─────┴─────┴─────────────────────┘

使用选择器来定义要转换的列：

>>> import polars.selectors as cs
>>> lf.cast({cs.numeric(): pl.UInt32, cs.temporal(): pl.String}).collect()
shape: (3, 3)
┌─────┬─────┬────────────┐
│ foo ┆ bar ┆ ham        │
│ --- ┆ --- ┆ ---        │
│ u32 ┆ u32 ┆ str        │
╞═════╪═════╪════════════╡
│ 1   ┆ 6   ┆ 2020-01-02 │
│ 2   ┆ 7   ┆ 2021-03-04 │
│ 3   ┆ 8   ┆ 2022-05-06 │
└─────┴─────┴────────────┘

将所有框架列转换为指定的数据类型：

>>> lf.cast(pl.String).collect().to_dict(as_series=False)
{'foo': ['1', '2', '3'],
 'bar': ['6.0', '7.0', '8.0'],
 'ham': ['2020-01-02', '2021-03-04', '2022-05-06']}

clear(n: int = 0) → LazyFrame[source]

创建一个当前LazyFrame的空副本，行数为零到'n'行。

返回一个具有相同模式但没有数据的副本。

Parameters:

n: 返回清除框架中的（空）行数。

另请参阅

clone: 便宜的深拷贝/克隆。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> lf.clear().collect()
shape: (0, 3)
┌─────┬─────┬──────┐
│ a   ┆ b   ┆ c    │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ f64 ┆ bool │
╞═════╪═════╪══════╡
└─────┴─────┴──────┘

>>> lf.clear(2).collect()
shape: (2, 3)
┌──────┬──────┬──────┐
│ a    ┆ b    ┆ c    │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ f64  ┆ bool │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ null ┆ null ┆ null │
└──────┴──────┴──────┘

clone() → LazyFrame[source]

创建此 LazyFrame 的副本。

这是一个不复制数据的廉价操作。

另请参阅

clear: 创建一个当前LazyFrame的空副本，具有相同的模式但没有数据。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> lf.clone()  
<LazyFrame at ...>

collect(

*,

type_coercion: bool = True,

_type_check: bool = True,

predicate_pushdown: bool = True,

projection_pushdown: bool = True,

simplify_expression: bool = True,

slice_pushdown: bool = True,

comm_subplan_elim: bool = True,

comm_subexpr_elim: bool = True,

cluster_with_columns: bool = True,

collapse_joins: bool = True,

no_optimization: bool = False,

streaming: bool = False,

engine: EngineType = 'cpu',

background: bool = False,

_check_order: bool = True,

_eager: bool = False,

**_kwargs: Any,

) → DataFrame | InProcessQuery[source]

将此LazyFrame具体化为DataFrame。

默认情况下，所有查询优化都已启用。可以通过将相应的参数设置为False来禁用个别优化。

Parameters:

type_coercion: 进行类型强制优化。
predicate_pushdown: 执行谓词下推优化。
projection_pushdown: 执行投影下推优化。
simplify_expression: 运行简化表达式优化。
slice_pushdown: 切片下推优化。
comm_subplan_elim: 将尝试缓存出现在自连接或联合上的分支子计划。
comm_subexpr_elim: 常见的子表达式将被缓存并重复使用。
cluster_with_columns: 将连续的独立调用合并到with_columns
collapse_joins: 将连接和过滤器合并为更快的连接
no_optimization: 关闭（某些）优化。
streaming: 分批处理查询以处理大于内存的数据。如果设置为False（默认值），则整个查询将在单个批次中处理。

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

注意

使用 explain() 来查看 Polars 是否可以在流模式下处理查询。
engine: 选择用于处理查询的引擎，可选。如果设置为 "cpu"（默认），则使用 polars CPU 引擎运行查询。如果设置为 "gpu"，则使用 GPU 引擎。通过提供具有配置选项的 GPUEngine 对象，可以对 GPU 引擎进行细粒度控制，例如在具有多个设备的系统上使用哪个设备。

注意

GPU模式被认为是不稳定的。并非所有查询都能在GPU上成功运行，但是，如果不支持执行，它们应该会透明地回退到默认引擎。

使用POLARS_VERBOSE=1运行将提供查询回退的信息（以及原因）。

注意

GPU引擎不支持流式处理或在后台运行。如果启用了其中任何一个功能，则GPU执行将被关闭。
background: 在后台运行查询并获取查询的句柄。此句柄可用于获取结果或取消查询。

警告

后台模式被认为是不稳定的。它可能会在任何时候被更改，而不被视为破坏性更改。

Returns:

DataFrame

另请参阅

explain: 打印使用collect评估的查询计划。
profile: 收集LazyFrame并计算图中每个节点的时间。
polars.collect_all: 同时收集多个LazyFrames。
polars.Config.set_streaming_chunk_size: 设置流批处理的大小。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a").agg(pl.all().sum()).collect()  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

以流模式收集

>>> lf.group_by("a").agg(pl.all().sum()).collect(
...     streaming=True
... )  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

在GPU模式下收集

>>> lf.group_by("a").agg(pl.all().sum()).collect(engine="gpu")  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 11  ┆ 10  │
│ a   ┆ 4   ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

控制使用的设备

>>> lf.group_by("a").agg(pl.all().sum()).collect(
...     engine=pl.GPUEngine(device=1)
... )  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 11  ┆ 10  │
│ a   ┆ 4   ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

collect_async( *, gevent: bool = False, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, no_optimization: bool = False, slice_pushdown: bool = True, comm_subplan_elim: bool = True, comm_subexpr_elim: bool = True, cluster_with_columns: bool = True, collapse_joins: bool = True, streaming: bool = False, _check_order: bool = True, ) → Awaitable[DataFrame] | _GeventDataFrameResult[DataFrame][source]

在线程池中异步收集DataFrame。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

收集到一个DataFrame中（类似于collect()），但不是直接返回一个DataFrame，而是安排在线程池中进行收集，而此方法几乎立即返回。

如果您使用gevent或asyncio，并且希望在收集LazyFrames时将控制权释放给其他greenlets/tasks，这可能很有用。

Parameters:

gevent: 返回包装器到 gevent.event.AsyncResult 而不是 Awaitable
type_coercion: 进行类型强制优化。
predicate_pushdown: 执行谓词下推优化。
projection_pushdown: 执行投影下推优化。
simplify_expression: 运行简化表达式优化。
no_optimization: 关闭（某些）优化。
slice_pushdown: 切片下推优化。
comm_subplan_elim: 将尝试缓存出现在自连接或联合上的分支子计划。
comm_subexpr_elim: 常见的子表达式将被缓存并重复使用。
cluster_with_columns: 将连续的独立调用合并到with_columns
collapse_joins: 将连接和过滤器合并为更快的连接
streaming: 分批处理查询以处理大于内存的数据。如果设置为False（默认值），则整个查询将在单个批次中处理。

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

注意

使用 explain() 来查看 Polars 是否可以在流模式下处理查询。

Returns:

If gevent=False (default) then returns an awaitable.
If gevent=True then returns wrapper that has a
.get(block=True, timeout=None) method.

另请参阅

polars.collect_all: 同时收集多个LazyFrames。
polars.collect_all_async: 同时懒加载多个LazyFrames。

注释

在发生错误的情况下，set_exception 被用于 asyncio.Future/gevent.event.AsyncResult 并且会被它们重新抛出。

示例

>>> import asyncio
>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> async def main():
...     return await (
...         lf.group_by("a", maintain_order=True)
...         .agg(pl.all().sum())
...         .collect_async()
...     )
>>> asyncio.run(main())
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 4   ┆ 10  │
│ b   ┆ 11  ┆ 10  │
│ c   ┆ 6   ┆ 1   │
└─────┴─────┴─────┘

collect_schema() → Schema[source]

解析此LazyFrame的模式。

示例

确定模式。

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.collect_schema()
Schema({'foo': Int64, 'bar': Float64, 'ham': String})

访问模式的各种属性。

>>> schema = lf.collect_schema()
>>> schema["bar"]
Float64
>>> schema.names()
['foo', 'bar', 'ham']
>>> schema.dtypes()
[Int64, Float64, String]
>>> schema.len()
3

property columns: list[str][source]

获取列名。

Returns:

list of str: 包含每列名称的列表，按顺序排列。

警告

确定LazyFrame的列名需要解析其模式，这可能是一个昂贵的操作。使用collect_schema()是解析模式的惯用方法。此属性仅存在于与DataFrame类的对称性。

另请参阅

collect_schema
Schema.names

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... ).select("foo", "bar")
>>> lf.columns  
['foo', 'bar']

count() → LazyFrame[source]

返回每列中非空元素的数量。

示例

>>> lf = pl.LazyFrame(
...     {"a": [1, 2, 3, 4], "b": [1, 2, 1, None], "c": [None, None, None, None]}
... )
>>> lf.count().collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 4   ┆ 3   ┆ 0   │
└─────┴─────┴─────┘

describe( percentiles: Sequence[float] | float | None = (0.25, 0.5, 0.75), *, interpolation: RollingInterpolationMethod = 'nearest', ) → DataFrame[source]

创建一个LazyFrame的统计摘要，返回一个DataFrame。

Parameters:

percentiles: 要包含在汇总统计中的一个或多个百分位数。所有值必须在[0, 1]范围内。
interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’}: 计算百分位数时使用的插值方法。

Returns:

DataFrame

警告

此方法不会保持框架的惰性，并且会collect最终结果。这可能是一个昂贵的操作。
我们不保证describe的输出是稳定的。它将显示我们认为有信息量的统计信息，并且可能会在未来更新。因此，不建议以编程方式使用describe（相对于交互式探索）。

注释

默认情况下，中位数作为50%百分位数被包含在内。

示例

>>> from datetime import date, time
>>> lf = pl.LazyFrame(
...     {
...         "float": [1.0, 2.8, 3.0],
...         "int": [40, 50, None],
...         "bool": [True, False, True],
...         "str": ["zz", "xx", "yy"],
...         "date": [date(2020, 1, 1), date(2021, 7, 5), date(2022, 12, 31)],
...         "time": [time(10, 20, 30), time(14, 45, 50), time(23, 15, 10)],
...     }
... )

显示默认帧统计信息：

>>> lf.describe()
shape: (9, 7)
┌────────────┬──────────┬──────────┬──────────┬──────┬─────────────────────┬──────────┐
│ statistic  ┆ float    ┆ int      ┆ bool     ┆ str  ┆ date                ┆ time     │
│ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
│ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
│ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
│ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
│ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
│ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
│ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
│ 25%        ┆ 2.8      ┆ 40.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 50%        ┆ 2.8      ┆ 50.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 75%        ┆ 3.0      ┆ 50.0     ┆ null     ┆ null ┆ 2022-12-31          ┆ 23:15:10 │
│ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
└────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘

自定义显示的百分位数，应用线性插值：

>>> with pl.Config(tbl_rows=12):
...     lf.describe(
...         percentiles=[0.1, 0.3, 0.5, 0.7, 0.9],
...         interpolation="linear",
...     )
shape: (11, 7)
┌────────────┬──────────┬──────────┬──────────┬──────┬─────────────────────┬──────────┐
│ statistic  ┆ float    ┆ int      ┆ bool     ┆ str  ┆ date                ┆ time     │
│ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
│ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
│ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
│ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
│ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
│ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
│ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
│ 10%        ┆ 1.36     ┆ 41.0     ┆ null     ┆ null ┆ 2020-04-20          ┆ 11:13:34 │
│ 30%        ┆ 2.08     ┆ 43.0     ┆ null     ┆ null ┆ 2020-11-26          ┆ 12:59:42 │
│ 50%        ┆ 2.8      ┆ 45.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 70%        ┆ 2.88     ┆ 47.0     ┆ null     ┆ null ┆ 2022-02-07          ┆ 18:09:34 │
│ 90%        ┆ 2.96     ┆ 49.0     ┆ null     ┆ null ┆ 2022-09-13          ┆ 21:33:18 │
│ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
└────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘

classmethod deserialize( source: str | Path | IOBase, *, format: SerializationFormat = 'binary', ) → LazyFrame[source]

从文件中读取逻辑计划以构建LazyFrame。

Parameters:

source

文件路径或类文件对象（类文件对象指的是具有read()方法的对象，例如文件句柄（如通过内置的open函数）或BytesIO）。

format

LazyFrame 被序列化的格式。选项：

"binary": 从二进制格式（字节）反序列化。这是默认设置。
"json": 从JSON格式（字符串）反序列化。

警告

如果逻辑计划包含Python UDFs，此函数将使用pickle，因此继承了相关的安全影响。反序列化可以执行任意代码，因此应仅在受信任的数据上尝试。

另请参阅

LazyFrame.serialize

注释

序列化在Polars版本之间不稳定：在一个Polars版本中序列化的LazyFrame可能无法在另一个Polars版本中反序列化。

示例

>>> import io
>>> lf = pl.LazyFrame({"a": [1, 2, 3]}).sum()
>>> bytes = lf.serialize()
>>> pl.LazyFrame.deserialize(io.BytesIO(bytes)).collect()
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 6   │
└─────┘

drop( *columns: ColumnNameOrSelector | Iterable[ColumnNameOrSelector], strict: bool = True, ) → LazyFrame[source]

从DataFrame中移除列。

Parameters:

*columns: 应从数据框中删除的列名。接受列选择器输入。
strict: 验证当前模式中是否存在所有列名，如果不存在则抛出异常。

示例

通过传递列的名称来删除单个列。

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.drop("ham").collect()
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 6.0 │
│ 2   ┆ 7.0 │
│ 3   ┆ 8.0 │
└─────┴─────┘

通过传递选择器删除多个列。

>>> import polars.selectors as cs
>>> lf.drop(cs.numeric()).collect()
shape: (3, 1)
┌─────┐
│ ham │
│ --- │
│ str │
╞═════╡
│ a   │
│ b   │
│ c   │
└─────┘

使用位置参数来删除多个列。

>>> lf.drop("foo", "ham").collect()
shape: (3, 1)
┌─────┐
│ bar │
│ --- │
│ f64 │
╞═════╡
│ 6.0 │
│ 7.0 │
│ 8.0 │
└─────┘

drop_nans( subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None, ) → LazyFrame[source]

删除包含一个或多个NaN值的所有行。

剩余行的原始顺序保持不变。

Parameters:

subset: 考虑NaN值的列名；如果设置为None（默认），则使用所有列（注意只有浮点数列可以包含NaN）。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [-20.5, float("nan"), 80.0],
...         "bar": [float("nan"), 110.0, 25.5],
...         "ham": ["xxx", "yyy", None],
...     }
... )

此方法的默认行为是删除行中任何单个值为NaN的行：

>>> lf.drop_nans().collect()
shape: (1, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ f64  ┆ f64  ┆ str  │
╞══════╪══════╪══════╡
│ 80.0 ┆ 25.5 ┆ null │
└──────┴──────┴──────┘

这种行为可以被限制为仅考虑由名称定义的列的子集，或者使用选择器。例如，仅在“bar”列中存在NaN时删除行：

>>> lf.drop_nans(subset=["bar"]).collect()
shape: (2, 3)
┌──────┬───────┬──────┐
│ foo  ┆ bar   ┆ ham  │
│ ---  ┆ ---   ┆ ---  │
│ f64  ┆ f64   ┆ str  │
╞══════╪═══════╪══════╡
│ NaN  ┆ 110.0 ┆ yyy  │
│ 80.0 ┆ 25.5  ┆ null │
└──────┴───────┴──────┘

只有当所有值都是NaN时，才删除一行，这需要不同的公式：

>>> lf = pl.LazyFrame(
...     {
...         "a": [float("nan"), float("nan"), float("nan"), float("nan")],
...         "b": [10.0, 2.5, float("nan"), 5.25],
...         "c": [65.75, float("nan"), float("nan"), 10.5],
...     }
... )
>>> lf.filter(~pl.all_horizontal(pl.all().is_nan())).collect()
shape: (3, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ f64 ┆ f64  ┆ f64   │
╞═════╪══════╪═══════╡
│ NaN ┆ 10.0 ┆ 65.75 │
│ NaN ┆ 2.5  ┆ NaN   │
│ NaN ┆ 5.25 ┆ 10.5  │
└─────┴──────┴───────┘

drop_nulls( subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None, ) → LazyFrame[source]

删除包含一个或多个空值的所有行。

剩余行的原始顺序保持不变。

Parameters:

subset: 考虑空值的列名。如果设置为None（默认），则使用所有列。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, None, 8],
...         "ham": ["a", "b", None],
...     }
... )

此方法的默认行为是删除行中任何单个值为空的行：

>>> lf.drop_nulls().collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

这种行为可以被限制为仅考虑由名称或选择器定义的列的子集。例如，如果任何整数列中存在空值，则删除行：

>>> import polars.selectors as cs
>>> lf.drop_nulls(subset=cs.integer()).collect()
shape: (2, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ i64 ┆ str  │
╞═════╪═════╪══════╡
│ 1   ┆ 6   ┆ a    │
│ 3   ┆ 8   ┆ null │
└─────┴─────┴──────┘

只有当所有值都为null时，删除一行需要不同的公式：

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, None, None, None],
...         "b": [1, 2, None, 1],
...         "c": [1, None, None, 1],
...     }
... )
>>> lf.filter(~pl.all_horizontal(pl.all().is_null())).collect()
shape: (3, 3)
┌──────┬─────┬──────┐
│ a    ┆ b   ┆ c    │
│ ---  ┆ --- ┆ ---  │
│ null ┆ i64 ┆ i64  │
╞══════╪═════╪══════╡
│ null ┆ 1   ┆ 1    │
│ null ┆ 2   ┆ null │
│ null ┆ 1   ┆ 1    │
└──────┴─────┴──────┘

property dtypes: list[DataType][source]

获取列数据类型。

Returns:

list of DataType: 一个包含每列数据类型的列表，按顺序排列。

警告

确定LazyFrame的数据类型需要解析其模式，这可能是一项昂贵的操作。使用collect_schema()是解析模式的惯用方法。此属性仅存在于与DataFrame类的对称性中。

另请参阅

collect_schema
Schema.dtypes

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.dtypes  
[Int64, Float64, String]

explain( *, format: ExplainFormat = 'plain', optimized: bool = True, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, comm_subplan_elim: bool = True, comm_subexpr_elim: bool = True, cluster_with_columns: bool = True, collapse_joins: bool = True, streaming: bool = False, tree_format: bool | None = None, _check_order: bool = True, ) → str[source]

创建查询计划的字符串表示。

可以开启或关闭不同的优化。

Parameters:

format{‘plain’, ‘tree’}: 用于显示逻辑计划的格式。
optimized: 返回一个优化的查询计划。默认为 True。如果设置为 True，后续的优化标志将控制哪些优化运行。
type_coercion: 进行类型强制优化。
predicate_pushdown: 执行谓词下推优化。
projection_pushdown: 执行投影下推优化。
simplify_expression: 运行简化表达式优化。
slice_pushdown: 切片下推优化。
comm_subplan_elim: 将尝试缓存出现在自连接或联合上的分支子计划。
comm_subexpr_elim: 常见的子表达式将被缓存并重复使用。
cluster_with_columns: 将连续的独立调用合并到with_columns
collapse_joins: 将连接和过滤器合并为更快的连接
streaming: 以流式方式运行查询的部分内容（此功能处于alpha状态）

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。
tree_format: 将输出格式化为树形结构。

自版本0.20.30起已弃用：请改用format="tree"。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).explain()  

explode( columns: str | Expr | Sequence[str | Expr], *more_columns: str | Expr, ) → LazyFrame[source]

将DataFrame通过展开给定列来转换为长格式。

Parameters:

columns: 列名、表达式或定义它们的选择器。被展开的底层列必须是List或Array数据类型。
*more_columns: 要展开的额外列名，指定为位置参数。

示例

>>> lf = pl.LazyFrame(
...     {
...         "letters": ["a", "a", "b", "c"],
...         "numbers": [[1], [2, 3], [4, 5], [6, 7, 8]],
...     }
... )
>>> lf.explode("numbers").collect()
shape: (8, 2)
┌─────────┬─────────┐
│ letters ┆ numbers │
│ ---     ┆ ---     │
│ str     ┆ i64     │
╞═════════╪═════════╡
│ a       ┆ 1       │
│ a       ┆ 2       │
│ a       ┆ 3       │
│ b       ┆ 4       │
│ b       ┆ 5       │
│ c       ┆ 6       │
│ c       ┆ 7       │
│ c       ┆ 8       │
└─────────┴─────────┘

fetch( n_rows: int = 500, *, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, no_optimization: bool = False, slice_pushdown: bool = True, comm_subplan_elim: bool = True, comm_subexpr_elim: bool = True, cluster_with_columns: bool = True, collapse_joins: bool = True, streaming: bool = False, ) → DataFrame[source]

收集少量行用于调试目的。

自版本1.0起已弃用：请改用collect()，并结合调用head()。

警告

这严格来说是一个实用函数，可以帮助使用较少的行数来调试查询，并且不应该在生产代码中使用。

注释

这类似于collect()操作，但它会覆盖每次扫描操作读取的行数。请注意，fetch并不保证DataFrame中的最终行数。过滤器、连接操作以及扫描数据中可用的行数较少都会影响最终的行数（连接操作尤其容易受到此影响，如果n_rows太小，连接键可能不存在，可能会返回无数据）。

fill_nan(value: int | float | Expr | None) → LazyFrame[source]

填充浮点数的NaN值。

Parameters:

value: 用于填充NaN值的值。

警告

请注意，浮点数的NaN（非数字）不是缺失值。要替换缺失值，请使用 fill_null()。

另请参阅

fill_null

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1.5, 2, float("nan"), 4],
...         "b": [0.5, 4, float("nan"), 13],
...     }
... )
>>> lf.fill_nan(99).collect()
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ f64  ┆ f64  │
╞══════╪══════╡
│ 1.5  ┆ 0.5  │
│ 2.0  ┆ 4.0  │
│ 99.0 ┆ 99.0 │
│ 4.0  ┆ 13.0 │
└──────┴──────┘

fill_null( value: Any | Expr | None = None, strategy: FillNullStrategy | None = None, limit: int | None = None, *, matches_supertype: bool = True, ) → LazyFrame[source]

使用指定的值或策略填充空值。

Parameters:

value: 用于填充空值的值。
strategy{None, ‘forward’, ‘backward’, ‘min’, ‘max’, ‘mean’, ‘zero’, ‘one’}: 用于填充空值的策略。
limit: 使用‘forward’或‘backward’策略时，要填充的连续空值的数量。
matches_supertype: 填充所有匹配的超类型的填充 value 字面量。

另请参阅

fill_nan

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, None, 4],
...         "b": [0.5, 4, None, 13],
...     }
... )
>>> lf.fill_null(99).collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 99  ┆ 99.0 │
│ 4   ┆ 13.0 │
└─────┴──────┘
>>> lf.fill_null(strategy="forward").collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 2   ┆ 4.0  │
│ 4   ┆ 13.0 │
└─────┴──────┘

>>> lf.fill_null(strategy="max").collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 4   ┆ 13.0 │
│ 4   ┆ 13.0 │
└─────┴──────┘

>>> lf.fill_null(strategy="zero").collect()
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 0   ┆ 0.0  │
│ 4   ┆ 13.0 │
└─────┴──────┘

filter(

*predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any, Any],

**constraints: Any,

) → LazyFrame[source]

根据谓词表达式过滤LazyFrame中的行。

剩余行的原始顺序保持不变。

过滤器未评估为True的行将被丢弃，包括空值。

Parameters:

predicates: 计算结果为布尔系列的表达式。
constraints: 列过滤器；使用 name = value 通过提供的值过滤列。每个约束的行为将与 pl.col(name).eq(value) 相同，并且将使用 & 隐式地与其他过滤条件连接。

注释

如果您正在从pandas过渡并根据两列或多列的比较执行过滤操作，请注意在Polars中，任何涉及空值的比较都将始终导致空值。因此，这些行将被过滤掉。请确保适当处理空值，以避免意外的过滤（请参见下面的示例）。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3, None, 4, None, 0],
...         "bar": [6, 7, 8, None, None, 9, 0],
...         "ham": ["a", "b", "c", None, "d", "e", "f"],
...     }
... )

根据一个条件进行筛选：

>>> lf.filter(pl.col("foo") > 1).collect()
shape: (3, 3)
┌─────┬──────┬─────┐
│ foo ┆ bar  ┆ ham │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ i64  ┆ str │
╞═════╪══════╪═════╡
│ 2   ┆ 7    ┆ b   │
│ 3   ┆ 8    ┆ c   │
│ 4   ┆ null ┆ d   │
└─────┴──────┴─────┘

根据多个条件进行筛选：

>>> lf.filter((pl.col("foo") < 3) & (pl.col("ham") == "a")).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

使用*args语法提供多个过滤器：

>>> lf.filter(
...     pl.col("foo") == 1,
...     pl.col("ham") == "a",
... ).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

使用**kwargs语法提供多个过滤器：

>>> lf.filter(foo=1, ham="a").collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

基于OR条件进行过滤：

>>> lf.filter((pl.col("foo") == 1) | (pl.col("ham") == "c")).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

通过比较两列进行筛选

>>> lf.filter(pl.col("foo") == pl.col("bar")).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 0   ┆ 0   ┆ f   │
└─────┴─────┴─────┘

>>> lf.filter(pl.col("foo") != pl.col("bar")).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

注意带有None值的行是如何被过滤掉的。为了保持与pandas相同的行为，请使用：

>>> lf.filter(pl.col("foo").ne_missing(pl.col("bar"))).collect()
shape: (5, 3)
┌──────┬──────┬─────┐
│ foo  ┆ bar  ┆ ham │
│ ---  ┆ ---  ┆ --- │
│ i64  ┆ i64  ┆ str │
╞══════╪══════╪═════╡
│ 1    ┆ 6    ┆ a   │
│ 2    ┆ 7    ┆ b   │
│ 3    ┆ 8    ┆ c   │
│ 4    ┆ null ┆ d   │
│ null ┆ 9    ┆ e   │
└──────┴──────┴─────┘

first() → LazyFrame[source]

获取DataFrame的第一行。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.first().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 2   │
└─────┴─────┘

gather_every(n: int, offset: int = 0) → LazyFrame[source]

在LazyFrame中每隔n行取一行，并返回一个新的LazyFrame。

Parameters:

n: 收集每n行。
offset: 起始索引。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [5, 6, 7, 8],
...     }
... )
>>> lf.gather_every(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 5   │
│ 3   ┆ 7   │
└─────┴─────┘
>>> lf.gather_every(2, offset=1).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 6   │
│ 4   ┆ 8   │
└─────┴─────┘

group_by(

*by: IntoExpr | Iterable[IntoExpr],

maintain_order: bool = False,

**named_by: IntoExpr,

) → LazyGroupBy[source]

开始一个分组操作。

Parameters:

*by: 用于分组的列。接受表达式输入。字符串被解析为列名。
maintain_order: 确保组的顺序与输入数据一致。这比默认的分组操作要慢。将此设置为 True 会阻止在流式引擎上运行的可能性。
**named_by: 用于分组的额外列，指定为关键字参数。这些列将被重命名为所使用的关键字。

示例

按一列分组并调用 agg 来计算另一列的分组总和。

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "c"],
...         "b": [1, 2, 1, 3, 3],
...         "c": [5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a").agg(pl.col("b").sum()).collect()  
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 2   │
│ b   ┆ 5   │
│ c   ┆ 3   │
└─────┴─────┘

设置 maintain_order=True 以确保组的顺序与输入一致。

>>> lf.group_by("a", maintain_order=True).agg(pl.col("c")).collect()
shape: (3, 2)
┌─────┬───────────┐
│ a   ┆ c         │
│ --- ┆ ---       │
│ str ┆ list[i64] │
╞═════╪═══════════╡
│ a   ┆ [5, 3]    │
│ b   ┆ [4, 2]    │
│ c   ┆ [1]       │
└─────┴───────────┘

通过传递列名列表来按多列分组。

>>> lf.group_by(["a", "b"]).agg(pl.max("c")).collect()  
shape: (4, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 5   │
│ b   ┆ 2   ┆ 4   │
│ b   ┆ 3   ┆ 2   │
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘

或者使用位置参数以相同的方式按多列分组。表达式也被接受。

>>> lf.group_by("a", pl.col("b") // 2).agg(
...     pl.col("c").mean()
... ).collect()  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ f64 │
╞═════╪═════╪═════╡
│ a   ┆ 0   ┆ 4.0 │
│ b   ┆ 1   ┆ 3.0 │
│ c   ┆ 1   ┆ 1.0 │
└─────┴─────┴─────┘

group_by_dynamic( index_column: IntoExpr, *, every: str | timedelta, period: str | timedelta | None = None, offset: str | timedelta | None = None, include_boundaries: bool = False, closed: ClosedInterval = 'left', label: Label = 'left', group_by: IntoExpr | Iterable[IntoExpr] | None = None, start_by: StartBy = 'window', ) → LazyGroupBy[source]

基于时间值（或类型为Int32、Int64的索引值）进行分组。

时间窗口被计算并且行被分配到窗口。与普通的分组不同，一行可以是多个组的成员。默认情况下，窗口看起来像：

[开始, 开始 + 周期)
[开始 + 每次, 开始 + 每次 + 周期)
[开始 + 2*每, 开始 + 2*每 + 周期)
…

其中 start 由 start_by, offset, every 和最早的数据点决定。详情请参见 start_by 参数描述。

警告

索引列必须按升序排序。如果传递了group_by，则每个组内的索引列必须按升序排序。

Parameters:

index_column

用于基于时间窗口进行分组的列。通常为日期/日期时间类型。此列必须按升序排序（或者，如果指定了group_by，则必须在每个组内按升序排序）。

在对索引进行动态分组的情况下，dtype 需要是 {Int32, Int64} 之一。请注意，Int32 会暂时转换为 Int64，因此如果性能很重要，请使用 Int64 列。

every

窗口的间隔

period

窗口的长度，如果为None，则等于‘every’

offset

窗口的偏移量，如果start_by是'datapoint'则不生效。默认为零。

include_boundaries

将窗口的下限和上限添加到“_lower_boundary”和“_upper_boundary”列中。这会影响性能，因为并行化更加困难。

closed{‘left’, ‘right’, ‘both’, ‘none’}

定义时间间隔的哪些边是闭合的（包含的）。

label{‘left’, ‘right’, ‘datapoint’}

定义用于窗口的标签：

‘left’: 窗口的下边界
‘right’: 窗口的上边界
‘datapoint’：给定窗口中索引列的第一个值。如果您不需要标签位于边界之一，请选择此选项以获得最佳性能

group_by

同时按此列/这些列分组

start_by{‘window’, ‘datapoint’, ‘monday’, ‘tuesday’, ‘wednesday’, ‘thursday’, ‘friday’, ‘saturday’, ‘sunday’}

确定第一个窗口开始的策略。

‘window’：首先获取最早的时间戳，使用every进行截断，然后添加offset。请注意，每周的窗口从周一开始。
‘datapoint’: 从遇到的第一个数据点开始。
一周中的某一天（仅在every包含'w'时生效）：
- ‘monday’: 在第一个数据点之前的星期一开始窗口。
- ‘tuesday’: 在第一个数据点之前的星期二开始窗口。
- …
- ‘sunday’: 在第一个数据点之前的星期日开始窗口。
然后将结果窗口向后移动，直到最早的数据点位于其中或在其前面。

Returns:

LazyGroupBy: 你可以调用.agg来按组进行聚合的对象，其结果将按index_column排序（但请注意，如果传递了group_by列，它只会在每个组内排序）。

另请参阅

rolling

注释

如果你来自pandas，那么
```
# polars
df.group_by_dynamic("ts", every="1d").agg(pl.col("value").sum())
```
等同于
```
# pandas
df.set_index("ts").resample("D")["value"].sum().reset_index()
```
尽管请注意，与pandas不同，polars不会为空的窗口添加额外的行。如果你需要index_column均匀分布，那么请结合使用DataFrame.upsample()。
every、period 和 offset 参数是使用以下字符串语言创建的：
- 1纳秒 (1 纳秒)
- 1微秒 (1 微秒)
- 1毫秒 (1 毫秒)
- 1秒 (1 秒)
- 1分钟 (1 minute)
- 1小时 (1小时)
- 1d (1个日历日)
- 1w (1个日历周)
- 1个月 (1个日历月)
- 1q (1个日历季度)
- 1年 (1个日历年)
- 1i (1 索引计数)
或者将它们组合起来： “3d12h4m25s” # 3天，12小时，4分钟，25秒

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

在对整数列进行group_by_dynamic操作时，窗口由以下定义：
- “1i” # 长度 1
- “10i” # 长度 10

示例

>>> from datetime import datetime
>>> lf = pl.LazyFrame(
...     {
...         "time": pl.datetime_range(
...             start=datetime(2021, 12, 16),
...             end=datetime(2021, 12, 16, 3),
...             interval="30m",
...             eager=True,
...         ),
...         "n": range(7),
...     }
... )
>>> lf.collect()
shape: (7, 2)
┌─────────────────────┬─────┐
│ time                ┆ n   │
│ ---                 ┆ --- │
│ datetime[μs]        ┆ i64 │
╞═════════════════════╪═════╡
│ 2021-12-16 00:00:00 ┆ 0   │
│ 2021-12-16 00:30:00 ┆ 1   │
│ 2021-12-16 01:00:00 ┆ 2   │
│ 2021-12-16 01:30:00 ┆ 3   │
│ 2021-12-16 02:00:00 ┆ 4   │
│ 2021-12-16 02:30:00 ┆ 5   │
│ 2021-12-16 03:00:00 ┆ 6   │
└─────────────────────┴─────┘

按1小时的时间窗口进行分组。

>>> lf.group_by_dynamic("time", every="1h", closed="right").agg(
...     pl.col("n")
... ).collect()
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-15 23:00:00 ┆ [0]       │
│ 2021-12-16 00:00:00 ┆ [1, 2]    │
│ 2021-12-16 01:00:00 ┆ [3, 4]    │
│ 2021-12-16 02:00:00 ┆ [5, 6]    │
└─────────────────────┴───────────┘

窗口边界也可以添加到聚合结果中

>>> lf.group_by_dynamic(
...     "time", every="1h", include_boundaries=True, closed="right"
... ).agg(pl.col("n").mean()).collect()
shape: (4, 4)
┌─────────────────────┬─────────────────────┬─────────────────────┬─────┐
│ _lower_boundary     ┆ _upper_boundary     ┆ time                ┆ n   │
│ ---                 ┆ ---                 ┆ ---                 ┆ --- │
│ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        ┆ f64 │
╞═════════════════════╪═════════════════════╪═════════════════════╪═════╡
│ 2021-12-15 23:00:00 ┆ 2021-12-16 00:00:00 ┆ 2021-12-15 23:00:00 ┆ 0.0 │
│ 2021-12-16 00:00:00 ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 00:00:00 ┆ 1.5 │
│ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ 3.5 │
│ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ 5.5 │
└─────────────────────┴─────────────────────┴─────────────────────┴─────┘

当 closed=”left” 时，窗口不包括区间的右端： [lower_bound, upper_bound)

>>> lf.group_by_dynamic("time", every="1h", closed="left").agg(
...     pl.col("n")
... ).collect()
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-16 00:00:00 ┆ [0, 1]    │
│ 2021-12-16 01:00:00 ┆ [2, 3]    │
│ 2021-12-16 02:00:00 ┆ [4, 5]    │
│ 2021-12-16 03:00:00 ┆ [6]       │
└─────────────────────┴───────────┘

当 closed="both" 时，窗口边界的时间值属于2个组。

>>> lf.group_by_dynamic("time", every="1h", closed="both").agg(
...     pl.col("n")
... ).collect()
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-16 00:00:00 ┆ [0, 1, 2] │
│ 2021-12-16 01:00:00 ┆ [2, 3, 4] │
│ 2021-12-16 02:00:00 ┆ [4, 5, 6] │
│ 2021-12-16 03:00:00 ┆ [6]       │
└─────────────────────┴───────────┘

动态分组也可以与普通键上的分组结合使用

>>> lf = lf.with_columns(groups=pl.Series(["a", "a", "a", "b", "b", "a", "a"]))
>>> lf.collect()
shape: (7, 3)
┌─────────────────────┬─────┬────────┐
│ time                ┆ n   ┆ groups │
│ ---                 ┆ --- ┆ ---    │
│ datetime[μs]        ┆ i64 ┆ str    │
╞═════════════════════╪═════╪════════╡
│ 2021-12-16 00:00:00 ┆ 0   ┆ a      │
│ 2021-12-16 00:30:00 ┆ 1   ┆ a      │
│ 2021-12-16 01:00:00 ┆ 2   ┆ a      │
│ 2021-12-16 01:30:00 ┆ 3   ┆ b      │
│ 2021-12-16 02:00:00 ┆ 4   ┆ b      │
│ 2021-12-16 02:30:00 ┆ 5   ┆ a      │
│ 2021-12-16 03:00:00 ┆ 6   ┆ a      │
└─────────────────────┴─────┴────────┘
>>> lf.group_by_dynamic(
...     "time",
...     every="1h",
...     closed="both",
...     group_by="groups",
...     include_boundaries=True,
... ).agg(pl.col("n")).collect()
shape: (6, 5)
┌────────┬─────────────────────┬─────────────────────┬─────────────────────┬───────────┐
│ groups ┆ _lower_boundary     ┆ _upper_boundary     ┆ time                ┆ n         │
│ ---    ┆ ---                 ┆ ---                 ┆ ---                 ┆ ---       │
│ str    ┆ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        ┆ list[i64] │
╞════════╪═════════════════════╪═════════════════════╪═════════════════════╪═══════════╡
│ a      ┆ 2021-12-16 00:00:00 ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 00:00:00 ┆ [0, 1, 2] │
│ a      ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ [2]       │
│ a      ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ [5, 6]    │
│ a      ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 04:00:00 ┆ 2021-12-16 03:00:00 ┆ [6]       │
│ b      ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ [3, 4]    │
│ b      ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ [4]       │
└────────┴─────────────────────┴─────────────────────┴─────────────────────┴───────────┘

在索引列上进行动态分组

>>> lf = pl.LazyFrame(
...     {
...         "idx": pl.int_range(0, 6, eager=True),
...         "A": ["A", "A", "B", "B", "B", "C"],
...     }
... )
>>> lf.group_by_dynamic(
...     "idx",
...     every="2i",
...     period="3i",
...     include_boundaries=True,
...     closed="right",
... ).agg(pl.col("A").alias("A_agg_list")).collect()
shape: (4, 4)
┌─────────────────┬─────────────────┬─────┬─────────────────┐
│ _lower_boundary ┆ _upper_boundary ┆ idx ┆ A_agg_list      │
│ ---             ┆ ---             ┆ --- ┆ ---             │
│ i64             ┆ i64             ┆ i64 ┆ list[str]       │
╞═════════════════╪═════════════════╪═════╪═════════════════╡
│ -2              ┆ 1               ┆ -2  ┆ ["A", "A"]      │
│ 0               ┆ 3               ┆ 0   ┆ ["A", "B", "B"] │
│ 2               ┆ 5               ┆ 2   ┆ ["B", "B", "C"] │
│ 4               ┆ 7               ┆ 4   ┆ ["C"]           │
└─────────────────┴─────────────────┴─────┴─────────────────┘

head(n: int = 5) → LazyFrame[source]

获取前n行。

Parameters:

n: 返回的行数。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.head().collect()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
└─────┴─────┘
>>> lf.head(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
└─────┴─────┘

inspect(fmt: str = '{}') → LazyFrame[source]

检查计算图中的一个节点。

打印计算图中此节点评估的值并传递该值。

示例

>>> lf = pl.LazyFrame({"foo": [1, 1, -2, 3]})
>>> (
...     lf.with_columns(pl.col("foo").cum_sum().alias("bar"))
...     .inspect()  # print the node before the filter
...     .filter(pl.col("bar") == pl.col("foo"))
... )  
<LazyFrame at ...>

interpolate() → LazyFrame[source]

插值中间值。插值方法是线性的。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, None, 9, 10],
...         "bar": [6, 7, 9, None],
...         "baz": [1, None, None, 9],
...     }
... )
>>> lf.interpolate().collect()
shape: (4, 3)
┌──────┬──────┬──────────┐
│ foo  ┆ bar  ┆ baz      │
│ ---  ┆ ---  ┆ ---      │
│ f64  ┆ f64  ┆ f64      │
╞══════╪══════╪══════════╡
│ 1.0  ┆ 6.0  ┆ 1.0      │
│ 5.0  ┆ 7.0  ┆ 3.666667 │
│ 9.0  ┆ 9.0  ┆ 6.333333 │
│ 10.0 ┆ null ┆ 9.0      │
└──────┴──────┴──────────┘

向逻辑计划中添加一个连接操作。

Parameters:

other

要连接的惰性DataFrame。

on

两个DataFrame的连接列。如果设置了，left_on 和 right_on 应为 None。

how{‘inner’, ‘left’, ‘right’, ‘full’, ‘semi’, ‘anti’, ‘cross’}

连接策略。

inner
返回在两个表中具有匹配值的行
left
返回左表中的所有行，以及右表中的匹配行
right
返回右表中的所有行，以及左表中的匹配行
full
当左表或右表中有匹配时返回所有行
cross
返回两个表中行的笛卡尔积
semi
返回左表中与右表匹配的行。
anti
返回左表中没有与右表匹配的行。

left_on

左侧DataFrame的连接列。

right_on

右侧DataFrame的连接列。

suffix

为具有重复名称的列附加的后缀。

validate: {‘m:m’, ‘m:1’, ‘1:m’, ‘1:1’}

检查连接是否为指定类型。

many_to_many
“m:m”：默认情况下，不会导致检查

one_to_one
“1:1”：检查连接键在左右数据集中是否唯一

one_to_many
“1:m”：检查连接键在左侧数据集中是否唯一

many_to_one
“m:1”：检查连接键在右侧数据集中是否唯一

注意

目前流式引擎不支持此功能。

join_nulls

在空值上进行连接。默认情况下，空值永远不会产生匹配。

coalesce

合并行为（连接列的合并）。

无： -> 加入特定。
True: -> 始终合并连接列。
False: -> 从不合并连接列。

注意

在除了col之外的任何其他表达式上进行连接将关闭合并。

maintain_order{‘none’, ‘left’, ‘right’, ‘left_right’, ‘right_left’}

保留哪个DataFrame的行顺序（如果有的话）。如果没有明确设置此参数，请不要依赖任何观察到的顺序，因为您的代码可能会在未来的版本中中断。不指定任何顺序可以提高性能支持内连接、左连接、右连接和全连接

none
不需要特定的排序。排序可能会在不同的Polars版本之间甚至在不同的运行之间有所不同。
left
保留左侧DataFrame的顺序。
right
保留右侧DataFrame的顺序。
left_right
首先保留左侧DataFrame的顺序，然后是右侧。
right_left
首先保留右侧DataFrame的顺序，然后是左侧。

allow_parallel

允许物理计划选择性地并行评估两个DataFrames直到连接的计算。

force_parallel

强制物理计划并行评估两个DataFrames的计算，直到连接操作。

另请参阅

join_asof

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> other_lf = pl.LazyFrame(
...     {
...         "apple": ["x", "y", "z"],
...         "ham": ["a", "b", "d"],
...     }
... )
>>> lf.join(other_lf, on="ham").collect()
shape: (2, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
└─────┴─────┴─────┴───────┘
>>> lf.join(other_lf, on="ham", how="full").collect()
shape: (4, 5)
┌──────┬──────┬──────┬───────┬───────────┐
│ foo  ┆ bar  ┆ ham  ┆ apple ┆ ham_right │
│ ---  ┆ ---  ┆ ---  ┆ ---   ┆ ---       │
│ i64  ┆ f64  ┆ str  ┆ str   ┆ str       │
╞══════╪══════╪══════╪═══════╪═══════════╡
│ 1    ┆ 6.0  ┆ a    ┆ x     ┆ a         │
│ 2    ┆ 7.0  ┆ b    ┆ y     ┆ b         │
│ null ┆ null ┆ null ┆ z     ┆ d         │
│ 3    ┆ 8.0  ┆ c    ┆ null  ┆ null      │
└──────┴──────┴──────┴───────┴───────────┘
>>> lf.join(other_lf, on="ham", how="left", coalesce=True).collect()
shape: (3, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
│ 3   ┆ 8.0 ┆ c   ┆ null  │
└─────┴─────┴─────┴───────┘
>>> lf.join(other_lf, on="ham", how="semi").collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6.0 ┆ a   │
│ 2   ┆ 7.0 ┆ b   │
└─────┴─────┴─────┘
>>> lf.join(other_lf, on="ham", how="anti").collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

执行一个asof连接。

这与左连接类似，不同之处在于我们匹配的是最接近的键而不是相等的键。

两个DataFrame必须按照on键排序（如果指定了by组，则在每个组内排序）。

对于左侧DataFrame中的每一行：

“向后”搜索选择右侧DataFrame中‘on’键小于或等于左侧键的最后一行。

“前向”搜索选择右侧DataFrame中‘on’键大于或等于左侧键的第一行。

“最近”搜索选择右侧DataFrame中值最接近左侧键的最后一行。目前不支持对字符串键进行最近搜索。

默认是“backward”。

Parameters:

other

要连接的惰性DataFrame。

left_on

左侧DataFrame的连接列。

right_on

右侧DataFrame的连接列。

on

两个DataFrame的连接列。如果设置了，left_on 和 right_on 应为 None。

by

在进行asof连接之前，先在这些列上进行连接。

by_left

在进行asof连接之前，先在这些列上进行连接。

by_right

在进行asof连接之前，先在这些列上进行连接。

strategy{‘backward’, ‘forward’, ‘nearest’}

连接策略。

suffix

为具有重复名称的列附加的后缀。

tolerance

数值容差。通过设置此值，只有当接近的键在此距离内时才会进行连接。如果在类型为“Date”、“Datetime”、“Duration”或“Time”的列上进行asof连接，请使用datetime.timedelta对象或以下字符串语言：

1纳秒 (1 纳秒)

1微秒 (1 微秒)

1毫秒 (1 毫秒)

1秒 (1 秒)

1分钟 (1 minute)

1小时 (1小时)

1d (1个日历日)

1w (1个日历周)

1个月 (1个日历月)

1q (1个日历季度)

1年 (1个日历年)

或者将它们组合起来： “3d12h4m25s” # 3天，12小时，4分钟，25秒

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

allow_parallel

允许物理计划选择性地并行评估两个DataFrames直到连接的计算。

force_parallel

强制物理计划并行评估两个DataFrames的计算，直到连接操作。

coalesce

合并行为（合并on / left_on / right_on列）：

True: -> 始终合并连接列。
False: -> 从不合并连接列。

请注意，在col以外的任何其他表达式上进行连接将关闭合并。

示例

>>> from datetime import date
>>> gdp = pl.LazyFrame(
...     {
...         "date": pl.date_range(
...             date(2016, 1, 1),
...             date(2020, 1, 1),
...             "1y",
...             eager=True,
...         ),
...         "gdp": [4164, 4411, 4566, 4696, 4827],
...     }
... )
>>> gdp.collect()
shape: (5, 2)
┌────────────┬──────┐
│ date       ┆ gdp  │
│ ---        ┆ ---  │
│ date       ┆ i64  │
╞════════════╪══════╡
│ 2016-01-01 ┆ 4164 │
│ 2017-01-01 ┆ 4411 │
│ 2018-01-01 ┆ 4566 │
│ 2019-01-01 ┆ 4696 │
│ 2020-01-01 ┆ 4827 │
└────────────┴──────┘

>>> population = pl.LazyFrame(
...     {
...         "date": [date(2016, 3, 1), date(2018, 8, 1), date(2019, 1, 1)],
...         "population": [82.19, 82.66, 83.12],
...     }
... ).sort("date")
>>> population.collect()
shape: (3, 2)
┌────────────┬────────────┐
│ date       ┆ population │
│ ---        ┆ ---        │
│ date       ┆ f64        │
╞════════════╪════════════╡
│ 2016-03-01 ┆ 82.19      │
│ 2018-08-01 ┆ 82.66      │
│ 2019-01-01 ┆ 83.12      │
└────────────┴────────────┘

注意日期并不完全匹配。如果我们使用 join_asof 和 strategy='backward' 进行连接，那么 population 中没有完全匹配的每个日期将与 gdp 中最接近的较早日期匹配：

>>> population.join_asof(gdp, on="date", strategy="backward").collect()
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 4566 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

注意以下几点：

日期 2016-03-01 来自 population 与 2016-01-01 来自 gdp 相匹配;
日期 2018-08-01 来自 population 与 2018-01-01 来自 gdp 相匹配。

你可以通过传递 coalesce=False 来验证这一点：

>>> population.join_asof(
...     gdp, on="date", strategy="backward", coalesce=False
... ).collect()
shape: (3, 4)
┌────────────┬────────────┬────────────┬──────┐
│ date       ┆ population ┆ date_right ┆ gdp  │
│ ---        ┆ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ date       ┆ i64  │
╞════════════╪════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 2016-01-01 ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 2018-01-01 ┆ 4566 │
│ 2019-01-01 ┆ 83.12      ┆ 2019-01-01 ┆ 4696 │
└────────────┴────────────┴────────────┴──────┘

如果我们改为使用 strategy='forward'，那么 population 中没有精确匹配的每个日期将与 gdp 中最接近的较晚日期匹配：

>>> population.join_asof(gdp, on="date", strategy="forward").collect()
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4411 │
│ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

注意以下几点：

日期 2016-03-01 来自 population 与 2017-01-01 来自 gdp 相匹配；
日期 2018-08-01 来自 population 与 2019-01-01 来自 gdp 相匹配。

最后，strategy='nearest' 给出了上述两种结果的混合，因为每个来自 population 的日期如果没有精确匹配，则会与来自 gdp 的最接近日期匹配，无论它是早还是晚：

>>> population.join_asof(gdp, on="date", strategy="nearest").collect()
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

注意以下几点：

日期 2016-03-01 来自 population 与 2016-01-01 来自 gdp 相匹配;
日期 2018-08-01 来自 population 与 2019-01-01 来自 gdp 相匹配。

他们 by 参数允许在asof连接之前先连接另一列。在这个例子中，我们首先通过 country 连接，然后按日期进行asof连接，如上所述。

>>> gdp_dates = pl.date_range(  # fmt: skip
...     date(2016, 1, 1), date(2020, 1, 1), "1y", eager=True
... )
>>> gdp2 = pl.LazyFrame(
...     {
...         "country": ["Germany"] * 5 + ["Netherlands"] * 5,
...         "date": pl.concat([gdp_dates, gdp_dates]),
...         "gdp": [4164, 4411, 4566, 4696, 4827, 784, 833, 914, 910, 909],
...     }
... ).sort("country", "date")
>>>
>>> gdp2.collect()
shape: (10, 3)
┌─────────────┬────────────┬──────┐
│ country     ┆ date       ┆ gdp  │
│ ---         ┆ ---        ┆ ---  │
│ str         ┆ date       ┆ i64  │
╞═════════════╪════════════╪══════╡
│ Germany     ┆ 2016-01-01 ┆ 4164 │
│ Germany     ┆ 2017-01-01 ┆ 4411 │
│ Germany     ┆ 2018-01-01 ┆ 4566 │
│ Germany     ┆ 2019-01-01 ┆ 4696 │
│ Germany     ┆ 2020-01-01 ┆ 4827 │
│ Netherlands ┆ 2016-01-01 ┆ 784  │
│ Netherlands ┆ 2017-01-01 ┆ 833  │
│ Netherlands ┆ 2018-01-01 ┆ 914  │
│ Netherlands ┆ 2019-01-01 ┆ 910  │
│ Netherlands ┆ 2020-01-01 ┆ 909  │
└─────────────┴────────────┴──────┘
>>> pop2 = pl.LazyFrame(
...     {
...         "country": ["Germany"] * 3 + ["Netherlands"] * 3,
...         "date": [
...             date(2016, 3, 1),
...             date(2018, 8, 1),
...             date(2019, 1, 1),
...             date(2016, 3, 1),
...             date(2018, 8, 1),
...             date(2019, 1, 1),
...         ],
...         "population": [82.19, 82.66, 83.12, 17.11, 17.32, 17.40],
...     }
... ).sort("country", "date")
>>>
>>> pop2.collect()
shape: (6, 3)
┌─────────────┬────────────┬────────────┐
│ country     ┆ date       ┆ population │
│ ---         ┆ ---        ┆ ---        │
│ str         ┆ date       ┆ f64        │
╞═════════════╪════════════╪════════════╡
│ Germany     ┆ 2016-03-01 ┆ 82.19      │
│ Germany     ┆ 2018-08-01 ┆ 82.66      │
│ Germany     ┆ 2019-01-01 ┆ 83.12      │
│ Netherlands ┆ 2016-03-01 ┆ 17.11      │
│ Netherlands ┆ 2018-08-01 ┆ 17.32      │
│ Netherlands ┆ 2019-01-01 ┆ 17.4       │
└─────────────┴────────────┴────────────┘
>>> pop2.join_asof(gdp2, by="country", on="date", strategy="nearest").collect()
shape: (6, 4)
┌─────────────┬────────────┬────────────┬──────┐
│ country     ┆ date       ┆ population ┆ gdp  │
│ ---         ┆ ---        ┆ ---        ┆ ---  │
│ str         ┆ date       ┆ f64        ┆ i64  │
╞═════════════╪════════════╪════════════╪══════╡
│ Germany     ┆ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ Germany     ┆ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ Germany     ┆ 2019-01-01 ┆ 83.12      ┆ 4696 │
│ Netherlands ┆ 2016-03-01 ┆ 17.11      ┆ 784  │
│ Netherlands ┆ 2018-08-01 ┆ 17.32      ┆ 910  │
│ Netherlands ┆ 2019-01-01 ┆ 17.4       ┆ 910  │
└─────────────┴────────────┴────────────┴──────┘

join_where( other: LazyFrame, *predicates: Expr | Iterable[Expr], suffix: str = '_right', ) → LazyFrame[source]

基于一个或多个（不）等式谓词执行连接。

这执行了一个内连接，因此只有所有谓词都为真的行才会包含在结果中，并且来自任一DataFrame的行可能会在结果中出现多次。

注意

输入DataFrames的行顺序不会被保留。

警告

此功能是实验性的。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

other: 要连接的DataFrame。
*predicates: 用于连接两个表的（不）等式条件。当一个列名在两个表中都出现时，必须在谓词中应用适当的后缀。
suffix: 为具有重复名称的列附加的后缀。

示例

>>> east = pl.LazyFrame(
...     {
...         "id": [100, 101, 102],
...         "dur": [120, 140, 160],
...         "rev": [12, 14, 16],
...         "cores": [2, 8, 4],
...     }
... )
>>> west = pl.LazyFrame(
...     {
...         "t_id": [404, 498, 676, 742],
...         "time": [90, 130, 150, 170],
...         "cost": [9, 13, 15, 16],
...         "cores": [4, 2, 1, 4],
...     }
... )
>>> east.join_where(
...     west,
...     pl.col("dur") < pl.col("time"),
...     pl.col("rev") < pl.col("cost"),
... ).collect()
shape: (5, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

last() → LazyFrame[source]

获取DataFrame的最后一行。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 5, 3],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.last().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 6   │
└─────┴─────┘

lazy() → LazyFrame[source]

返回惰性表示，即其本身。

对于期望接收DataFrame或LazyFrame的代码编写非常有用。在LazyFrame上，这是一个无操作，并返回相同的对象。

Returns:

LazyFrame

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> lf.lazy()  
<LazyFrame at ...>

limit(n: int = 5) → LazyFrame[source]

获取前n行。

LazyFrame.head() 的别名。

Parameters:

n: 返回的行数。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.limit().collect()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
└─────┴─────┘
>>> lf.limit(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
└─────┴─────┘

map_batches( function: Callable[[DataFrame], DataFrame], *, predicate_pushdown: bool = True, projection_pushdown: bool = True, slice_pushdown: bool = True, no_optimizations: bool = False, schema: None | SchemaDict = None, validate_output_schema: bool = True, streamable: bool = False, ) → LazyFrame[source]

应用自定义函数。

重要的是该函数返回一个Polars DataFrame。

Parameters:

function: 要应用的Lambda/函数。
predicate_pushdown: 允许谓词下推优化通过此节点。
projection_pushdown: 允许投影下推优化通过此节点。
slice_pushdown: 允许切片下推优化通过此节点。
no_optimizations: 关闭此点之后的所有优化。
schema: 函数的输出模式，如果设置为None，我们假设模式在应用函数后将保持不变。
validate_output_schema: 确保polars的模式正确至关重要。此标志将确保此函数的输出模式将与预期模式进行检查。将其设置为False将不会进行此检查，但可能会导致难以调试的错误。
streamable: 给定的函数是否有资格与流式引擎一起运行。这意味着无论是以批处理方式执行还是在完整数据集上执行，函数都必须产生相同的结果。

警告

LazyFrame 的 schema 必须始终正确。确保这一不变性由该函数的调用者负责。

优化标志的正确性非常重要。例如，如果自定义函数对某一列进行聚合操作，则不应允许predicate_pushdown，因为这会导致行被剪裁，从而影响聚合结果。

示例

>>> lf = (  
...     pl.LazyFrame(
...         {
...             "a": pl.int_range(-100_000, 0, eager=True),
...             "b": pl.int_range(0, 100_000, eager=True),
...         }
...     )
...     .map_batches(lambda x: 2 * x, streamable=True)
...     .collect(streaming=True)
... )
shape: (100_000, 2)
┌─────────┬────────┐
│ a       ┆ b      │
│ ---     ┆ ---    │
│ i64     ┆ i64    │
╞═════════╪════════╡
│ -200000 ┆ 0      │
│ -199998 ┆ 2      │
│ -199996 ┆ 4      │
│ -199994 ┆ 6      │
│ …       ┆ …      │
│ -8      ┆ 199992 │
│ -6      ┆ 199994 │
│ -4      ┆ 199996 │
│ -2      ┆ 199998 │
└─────────┴────────┘

max() → LazyFrame[source]

将LazyFrame中的列聚合到它们的最大值。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.max().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 4   ┆ 2   │
└─────┴─────┘

mean() → LazyFrame[source]

将LazyFrame中的列聚合为其平均值。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.mean().collect()
shape: (1, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ f64 ┆ f64  │
╞═════╪══════╡
│ 2.5 ┆ 1.25 │
└─────┴──────┘

median() → LazyFrame[source]

将LazyFrame中的列聚合到它们的中位数。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.median().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 2.5 ┆ 1.0 │
└─────┴─────┘

将DataFrame从宽格式转换为长格式。

可选地保留标识符设置。

此函数有助于将DataFrame整理成一种格式，其中一列或多列是标识变量（id_vars），而所有其他列，被视为测量变量（value_vars），被“逆透视”到行轴，只留下两个非标识列，‘variable’和‘value’。

自版本1.0.0起已弃用：请改用unpivot()。

Parameters:

id_vars: 用作标识符变量的列或选择器。
value_vars: 用作值变量的列或选择器；如果value_vars为空，则所有不在id_vars中的列将被使用。
variable_name: 为variable列指定的名称。默认为“variable”
value_name: 为value列指定的名称。默认为“value”
streamable: 允许此节点在流式引擎中运行。如果在流式环境中运行，取消透视操作的输出将不会有稳定的顺序。

merge_sorted( other: LazyFrame, key: str, ) → LazyFrame[source]

取两个已排序的DataFrame并按排序键合并它们。

此操作的输出也将被排序。调用者有责任确保帧按该键排序，否则输出将没有意义。

两个LazyFrame的模式必须相同。

Parameters:

other: 必须合并的其他DataFrame
key: 被排序的键。

示例

>>> df0 = pl.LazyFrame(
...     {"name": ["steve", "elise", "bob"], "age": [42, 44, 18]}
... ).sort("age")
>>> df0.collect()
shape: (3, 2)
┌───────┬─────┐
│ name  ┆ age │
│ ---   ┆ --- │
│ str   ┆ i64 │
╞═══════╪═════╡
│ bob   ┆ 18  │
│ steve ┆ 42  │
│ elise ┆ 44  │
└───────┴─────┘
>>> df1 = pl.LazyFrame(
...     {"name": ["anna", "megan", "steve", "thomas"], "age": [21, 33, 42, 20]}
... ).sort("age")
>>> df1.collect()
shape: (4, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
└────────┴─────┘
>>> df0.merge_sorted(df1, key="age").collect()
shape: (7, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ bob    ┆ 18  │
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
│ steve  ┆ 42  │
│ elise  ┆ 44  │
└────────┴─────┘

min() → LazyFrame[source]

将LazyFrame中的列聚合为其最小值。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.min().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 1   │
└─────┴─────┘

null_count() → LazyFrame[source]

将LazyFrame中的列聚合为它们的空值计数的总和。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, None, 3],
...         "bar": [6, 7, None],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.null_count().collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 1   ┆ 1   ┆ 0   │
└─────┴─────┴─────┘

pipe(

function: Callable[Concatenate[LazyFrame, P], T],

*args: P.args,

**kwargs: P.kwargs,

) → T[source]

提供了一种结构化的方式来应用一系列用户定义的函数（UDFs）。

Parameters:

function: 可调用的；将接收帧作为第一个参数，后面跟随任何给定的args/kwargs。
*args: 传递给UDF的参数。
**kwargs: 传递给UDF的关键字参数。

示例

>>> def cast_str_to_int(lf: pl.LazyFrame, col_name: str) -> pl.LazyFrame:
...     return lf.with_columns(pl.col(col_name).cast(pl.Int64))
>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": ["10", "20", "30", "40"],
...     }
... )
>>> lf.pipe(cast_str_to_int, col_name="b").collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 10  │
│ 2   ┆ 20  │
│ 3   ┆ 30  │
│ 4   ┆ 40  │
└─────┴─────┘

>>> lf = pl.LazyFrame(
...     {
...         "b": [1, 2],
...         "a": [3, 4],
...     }
... )
>>> lf.collect()
shape: (2, 2)
┌─────┬─────┐
│ b   ┆ a   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘
>>> lf.pipe(lambda lf: lf.select(sorted(lf.collect_schema()))).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 1   │
│ 4   ┆ 2   │
└─────┴─────┘

profile( *, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, no_optimization: bool = False, slice_pushdown: bool = True, comm_subplan_elim: bool = True, comm_subexpr_elim: bool = True, cluster_with_columns: bool = True, collapse_joins: bool = True, show_plot: bool = False, truncate_nodes: int = 0, figsize: tuple[int, int] = (18, 8), streaming: bool = False, _check_order: bool = True, ) → tuple[DataFrame, DataFrame][source]

分析一个LazyFrame。

这将运行查询并返回一个元组，其中包含物化的DataFrame和一个包含每个执行节点的分析信息的DataFrame。

计时单位是微秒。

Parameters:

type_coercion: 进行类型强制优化。
predicate_pushdown: 执行谓词下推优化。
projection_pushdown: 执行投影下推优化。
simplify_expression: 运行简化表达式优化。
no_optimization: 关闭（某些）优化。
slice_pushdown: 切片下推优化。
comm_subplan_elim: 将尝试缓存出现在自连接或联合上的分支子计划。
comm_subexpr_elim: 常见的子表达式将被缓存并重复使用。
cluster_with_columns: 将连续的独立调用合并到with_columns
collapse_joins: 将连接和过滤器合并为更快的连接
show_plot: 显示分析结果的甘特图
truncate_nodes: 将甘特图中的标签长度截断为此字符数。
figsize: matplotlib 分析图的 figsize
streaming: 以流式方式运行查询的部分内容（此功能处于alpha状态）

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).profile()  
(shape: (3, 3)
 ┌─────┬─────┬─────┐
 │ a   ┆ b   ┆ c   │
 │ --- ┆ --- ┆ --- │
 │ str ┆ i64 ┆ i64 │
 ╞═════╪═════╪═════╡
 │ a   ┆ 4   ┆ 10  │
 │ b   ┆ 11  ┆ 10  │
 │ c   ┆ 6   ┆ 1   │
 └─────┴─────┴─────┘,
 shape: (3, 3)
 ┌─────────────────────────┬───────┬──────┐
 │ node                    ┆ start ┆ end  │
 │ ---                     ┆ ---   ┆ ---  │
 │ str                     ┆ u64   ┆ u64  │
 ╞═════════════════════════╪═══════╪══════╡
 │ optimization            ┆ 0     ┆ 5    │
 │ group_by_partitioned(a) ┆ 5     ┆ 470  │
 │ sort(a)                 ┆ 475   ┆ 1964 │
 └─────────────────────────┴───────┴──────┘)

quantile( quantile: float | Expr, interpolation: RollingInterpolationMethod = 'nearest', ) → LazyFrame[source]

将LazyFrame中的列聚合到它们的分位数值。

Parameters:

quantile: 分位数在0.0到1.0之间。
interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’}: 插值方法。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.quantile(0.7).collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 3.0 ┆ 1.0 │
└─────┴─────┘

rename( mapping: dict[str, str] | Callable[[str], str], *, strict: bool = True, ) → LazyFrame[source]

重命名列名。

Parameters:

mapping: 从旧名称映射到新名称的键值对，或者一个以旧名称为输入并返回新名称的函数。
strict: 验证当前模式中是否存在所有列名，如果不存在则抛出异常。（请注意，当传递函数给mapping时，此参数无效）。

注释

如果现有的名称被交换（例如，‘A’指向‘B’且‘B’指向‘A’）， polars将在此节点阻止投影和谓词下推。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.rename({"foo": "apple"}).collect()
shape: (3, 3)
┌───────┬─────┬─────┐
│ apple ┆ bar ┆ ham │
│ ---   ┆ --- ┆ --- │
│ i64   ┆ i64 ┆ str │
╞═══════╪═════╪═════╡
│ 1     ┆ 6   ┆ a   │
│ 2     ┆ 7   ┆ b   │
│ 3     ┆ 8   ┆ c   │
└───────┴─────┴─────┘
>>> lf.rename(lambda column_name: "c" + column_name[1:]).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ coo ┆ car ┆ cam │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

reverse() → LazyFrame[source]

反转DataFrame。

示例

>>> lf = pl.LazyFrame(
...     {
...         "key": ["a", "b", "c"],
...         "val": [1, 2, 3],
...     }
... )
>>> lf.reverse().collect()
shape: (3, 2)
┌─────┬─────┐
│ key ┆ val │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ c   ┆ 3   │
│ b   ┆ 2   │
│ a   ┆ 1   │
└─────┴─────┘

基于时间或整数列创建滚动组。

与group_by_dynamic不同，窗口现在由各个值确定，而不是固定间隔。对于固定间隔，请使用LazyFrame.group_by_dynamic()。

如果你有一个时间序列 t_1, ..., t_n>，那么默认创建的窗口将是

(t_0 - 周期, t_0]

(t_1 - 周期, t_1]

…

(t_n - 周期, t_n]

而如果你传递一个非默认的 offset，那么窗口将会是

(t_0 + offset, t_0 + offset + period]

(t_1 + offset, t_1 + offset + period]

…

(t_n + offset, t_n + offset + period]

period 和 offset 参数可以通过 timedelta 创建，或者使用以下字符串语言创建：

1纳秒 (1 纳秒)
1微秒 (1 微秒)
1毫秒 (1 毫秒)
1秒 (1 秒)
1分钟 (1 minute)
1小时 (1小时)
1d (1个日历日)
1w (1个日历周)
1个月 (1个日历月)
1q (1个日历季度)
1年 (1个日历年)
1i (1 索引计数)

或者将它们组合起来： “3d12h4m25s” # 3天，12小时，4分钟，25秒

“日历日”指的是第二天的相应时间（由于夏令时，可能不是24小时）。同样适用于“日历周”、“日历月”、“日历季度”和“日历年”。

Parameters:

index_column

用于基于时间窗口进行分组的列。通常为日期/日期时间类型。此列必须按升序排序（或者，如果指定了group_by，则必须在每个组内按升序排序）。

在对索引进行滚动分组的情况下，dtype 需要是 {UInt32, UInt64, Int32, Int64} 之一。请注意，前三个会暂时转换为 Int64，因此如果性能很重要，请使用 Int64 列。

period

窗口的长度 - 必须为非负数。

offset

窗口的偏移量。默认是 -period。

closed{‘right’, ‘left’, ‘both’, ‘none’}

定义时间间隔的哪些边是闭合的（包含的）。

group_by

同时按此列/这些列分组

Returns:

LazyGroupBy: 你可以调用.agg来按组进行聚合的对象，其结果将按index_column排序（但请注意，如果传递了group_by列，则仅在每个组内排序）。

另请参阅

group_by_dynamic

示例

>>> dates = [
...     "2020-01-01 13:45:48",
...     "2020-01-01 16:42:13",
...     "2020-01-01 16:45:09",
...     "2020-01-02 18:12:48",
...     "2020-01-03 19:45:32",
...     "2020-01-08 23:16:43",
... ]
>>> df = pl.LazyFrame({"dt": dates, "a": [3, 7, 5, 9, 2, 1]}).with_columns(
...     pl.col("dt").str.strptime(pl.Datetime).set_sorted()
... )
>>> out = (
...     df.rolling(index_column="dt", period="2d")
...     .agg(
...         pl.sum("a").alias("sum_a"),
...         pl.min("a").alias("min_a"),
...         pl.max("a").alias("max_a"),
...     )
...     .collect()
... )
>>> out
shape: (6, 4)
┌─────────────────────┬───────┬───────┬───────┐
│ dt                  ┆ sum_a ┆ min_a ┆ max_a │
│ ---                 ┆ ---   ┆ ---   ┆ ---   │
│ datetime[μs]        ┆ i64   ┆ i64   ┆ i64   │
╞═════════════════════╪═══════╪═══════╪═══════╡
│ 2020-01-01 13:45:48 ┆ 3     ┆ 3     ┆ 3     │
│ 2020-01-01 16:42:13 ┆ 10    ┆ 3     ┆ 7     │
│ 2020-01-01 16:45:09 ┆ 15    ┆ 3     ┆ 7     │
│ 2020-01-02 18:12:48 ┆ 24    ┆ 3     ┆ 9     │
│ 2020-01-03 19:45:32 ┆ 11    ┆ 2     ┆ 9     │
│ 2020-01-08 23:16:43 ┆ 1     ┆ 1     ┆ 1     │
└─────────────────────┴───────┴───────┴───────┘

property schema: Schema[source]

获取列名到其数据类型的有序映射。

警告

解析LazyFrame的模式可能是一项昂贵的操作。使用collect_schema()是解析模式的惯用方法。此属性仅存在于与DataFrame类的对称性。

另请参阅

collect_schema
Schema

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.schema  
Schema({'foo': Int64, 'bar': Float64, 'ham': String})

select(

*exprs: IntoExpr | Iterable[IntoExpr],

**named_exprs: IntoExpr,

) → LazyFrame[source]

从这个LazyFrame中选择列。

Parameters:

*exprs: 要选择的列，指定为位置参数。接受表达式输入。字符串被解析为列名，其他非表达式输入被解析为字面量。
**named_exprs: 要选择的额外列，指定为关键字参数。这些列将被重命名为所使用的关键字。

示例

传递列的名称以选择该列。

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> lf.select("foo").collect()
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

可以通过传递列名列表来选择多列。

>>> lf.select(["foo", "bar"]).collect()
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 6   │
│ 2   ┆ 7   │
│ 3   ┆ 8   │
└─────┴─────┘

也可以使用位置参数而不是列表来选择多列。表达式也被接受。

>>> lf.select(pl.col("foo"), pl.col("bar") + 1).collect()
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
└─────┴─────┘

使用关键字参数可以轻松命名您的表达式输入。

>>> lf.select(
...     threshold=pl.when(pl.col("foo") > 2).then(10).otherwise(0)
... ).collect()
shape: (3, 1)
┌───────────┐
│ threshold │
│ ---       │
│ i32       │
╞═══════════╡
│ 0         │
│ 0         │
│ 10        │
└───────────┘

通过启用设置 Config.set_auto_structify(True)，可以将具有多个输出的表达式自动实例化为结构体：

>>> with pl.Config(auto_structify=True):
...     lf.select(
...         is_odd=(pl.col(pl.Int64) % 2 == 1).name.suffix("_is_odd"),
...     ).collect()
shape: (3, 1)
┌──────────────┐
│ is_odd       │
│ ---          │
│ struct[2]    │
╞══════════════╡
│ {true,false} │
│ {false,true} │
│ {true,false} │
└──────────────┘

select_seq(

*exprs: IntoExpr | Iterable[IntoExpr],

**named_exprs: IntoExpr,

) → LazyFrame[source]

从这个LazyFrame中选择列。

这将按顺序运行所有表达式，而不是并行运行。当每个表达式的工作量较小时使用此方法。

Parameters:

*exprs: 要选择的列，指定为位置参数。接受表达式输入。字符串被解析为列名，其他非表达式输入被解析为字面量。
**named_exprs: 要选择的额外列，指定为关键字参数。这些列将被重命名为所使用的关键字。

另请参阅

select

将此LazyFrame的逻辑计划序列化为JSON格式的文件或字符串。

Parameters:

file

结果应写入的文件路径。如果设置为None（默认），则输出将作为字符串返回。

format

序列化的格式。选项：

"binary": 序列化为二进制格式（字节）。这是默认设置。
"json": 序列化为JSON格式（字符串）（已弃用）。

另请参阅

LazyFrame.deserialize

注释

序列化在Polars版本之间不稳定：在一个Polars版本中序列化的LazyFrame可能无法在另一个Polars版本中反序列化。

示例

将逻辑计划序列化为二进制表示。

>>> lf = pl.LazyFrame({"a": [1, 2, 3]}).sum()
>>> bytes = lf.serialize()

字节可以稍后反序列化回LazyFrame。

>>> import io
>>> pl.LazyFrame.deserialize(io.BytesIO(bytes)).collect()
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 6   │
└─────┘

set_sorted( column: str, *, descending: bool = False, ) → LazyFrame[source]

指示一个或多个列已排序。

这可以加快未来的操作。

Parameters:

column: 已排序的列
descending: 列是否按降序排序。

警告

如果数据未排序，这可能导致错误的结果！！请谨慎使用！

shift( n: int | IntoExprColumn = 1, *, fill_value: IntoExpr | None = None, ) → LazyFrame[source]

将值按给定的索引数进行移动。

Parameters:

n: 向前移动的索引数量。如果传递了负值，则值将向相反方向移动。
fill_value: 用此值填充结果中的空值。接受表达式输入。非表达式输入将被解析为字面量。

注释

此方法类似于SQL中的LAG操作，当n的值为正时。当n的值为负时，它类似于LEAD。

示例

默认情况下，值会向前移动一个索引。

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [5, 6, 7, 8],
...     }
... )
>>> lf.shift().collect()
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ null ┆ null │
│ 1    ┆ 5    │
│ 2    ┆ 6    │
│ 3    ┆ 7    │
└──────┴──────┘

传递一个负值以向相反方向移动。

>>> lf.shift(-2).collect()
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ 3    ┆ 7    │
│ 4    ┆ 8    │
│ null ┆ null │
│ null ┆ null │
└──────┴──────┘

指定fill_value以填充结果中的空值。

>>> lf.shift(-2, fill_value=100).collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 7   │
│ 4   ┆ 8   │
│ 100 ┆ 100 │
│ 100 ┆ 100 │
└─────┴─────┘

show_graph( *, optimized: bool = True, show: bool = True, output_path: str | Path | None = None, raw_output: bool = False, figsize: tuple[float, float] = (16.0, 12.0), type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, comm_subplan_elim: bool = True, comm_subexpr_elim: bool = True, cluster_with_columns: bool = True, collapse_joins: bool = True, streaming: bool = False, _check_order: bool = True, ) → str | None[source]

显示查询计划的图表。

请注意，必须安装Graphviz才能渲染可视化效果（如果尚未安装，您可以在此处下载：https://graphviz.org/download）。

Parameters:

optimized: 优化查询计划。
show: 显示图表。
output_path: 将图形写入磁盘。
raw_output: 返回点语法。这不能与show和/或output_path结合使用。
figsize: 如果show == True，则传递给matplotlib。
type_coercion: 进行类型强制优化。
predicate_pushdown: 执行谓词下推优化。
projection_pushdown: 执行投影下推优化。
simplify_expression: 运行简化表达式优化。
slice_pushdown: 切片下推优化。
comm_subplan_elim: 将尝试缓存出现在自连接或联合上的分支子计划。
comm_subexpr_elim: 常见的子表达式将被缓存并重复使用。
cluster_with_columns: 将顺序独立的调用合并到with_columns。
collapse_joins: 将连接和过滤器合并为一个更快的连接。
streaming: 以流式方式运行查询的部分内容（此功能处于alpha状态）。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [1, 2, 3, 4, 5, 6],
...         "c": [6, 5, 4, 3, 2, 1],
...     }
... )
>>> lf.group_by("a", maintain_order=True).agg(pl.all().sum()).sort(
...     "a"
... ).show_graph()  

sink_csv( path: str | Path, *, include_bom: bool = False, include_header: bool = True, separator: str = ',', line_terminator: str = '\n', quote_char: str = '"', batch_size: int = 1024, datetime_format: str | None = None, date_format: str | None = None, time_format: str | None = None, float_scientific: bool | None = None, float_precision: int | None = None, null_value: str | None = None, quote_style: CsvQuoteStyle | None = None, maintain_order: bool = True, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, collapse_joins: bool = True, no_optimization: bool = False, storage_options: dict[str, Any] | None = None, credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto', retries: int = 2, ) → None[source]

在流模式下评估查询并将结果写入CSV文件。

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

这允许将大于RAM的流式结果写入磁盘。

Parameters:

path

文件应写入的文件路径。

include_bom

是否在CSV输出中包含UTF-8 BOM。

include_header

是否在CSV输出中包含标题。

separator

用此符号分隔CSV字段。

line_terminator

用于结束每一行的字符串。

quote_char

用作引用字符的字节。

batch_size

每个线程将处理的行数。

datetime_format

一个格式字符串，使用由 chrono Rust crate 定义的说明符。如果未指定格式，则默认的分数秒精度将从帧的Datetime列中找到的最大时间单位推断（如果有的话）。

date_format

一个格式字符串，使用由 chrono Rust crate 定义的说明符。

time_format

一个格式字符串，使用由 chrono Rust crate 定义的说明符。

float_scientific

是否始终使用科学计数法（true），从不使用（false），或自动选择（None）用于Float32和Float64数据类型。

float_precision

要写入的小数位数，适用于Float32和 Float64数据类型。

null_value

表示空值的字符串（默认为空字符串）。

quote_style{‘necessary’, ‘always’, ‘non_numeric’, ‘never’}

确定使用的引用策略。

必要的（默认）：仅在必要时在字段周围加上引号。当字段包含引号、分隔符或记录终止符时，引号是必要的。在写入空记录时也需要引号（这与具有一个空字段的记录无法区分）。这是默认设置。
always: 这会在每个字段周围加上引号。总是如此。
never: 这永远不会在字段周围加上引号，即使这会导致无效的CSV数据（例如：不引用包含分隔符的字符串）。
non_numeric: 这会在所有非数字字段周围加上引号。也就是说，当写入一个无法解析为有效浮点数或整数的字段时，即使严格来说不需要，也会使用引号。

maintain_order

保持数据处理的顺序。将此设置为False会稍微快一些。

type_coercion

进行类型强制优化。

predicate_pushdown

执行谓词下推优化。

projection_pushdown

执行投影下推优化。

simplify_expression

运行简化表达式优化。

slice_pushdown

切片下推优化。

collapse_joins

将连接和过滤器合并为更快的连接

no_optimization

关闭（某些）优化。

storage_options

指示如何连接到云提供商的选项。

目前支持的云提供商有AWS、GCP和Azure。查看支持的密钥请点击这里：

aws
gcp
azure
Hugging Face (hf://): 接受在 token 参数下的 API 密钥：{'token': '...'}，或者通过设置 HF_TOKEN 环境变量。

如果未提供storage_options，Polars将尝试从环境变量中推断信息。

credential_provider

提供一个可以被调用的函数来提供云存储凭证。该函数预期返回一个包含凭证键的字典以及一个可选的凭证过期时间。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

retries

如果访问云实例失败，重试次数。

Returns:

DataFrame

示例

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_csv("out.csv")  

sink_ipc( path: str | Path, *, compression: str | None = 'zstd', maintain_order: bool = True, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, collapse_joins: bool = True, no_optimization: bool = False, storage_options: dict[str, Any] | None = None, credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto', retries: int = 2, ) → None[source]

在流模式下评估查询并将结果写入IPC文件。

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

这允许将大于RAM的流式结果写入磁盘。

Parameters:

path

文件应写入的文件路径。

compression{‘lz4’, ‘zstd’}

选择“zstd”以获得良好的压缩性能。选择“lz4”以实现快速的压缩/解压缩。

maintain_order

保持数据处理的顺序。将此设置为False会稍微快一些。

type_coercion

进行类型强制优化。

predicate_pushdown

执行谓词下推优化。

projection_pushdown

执行投影下推优化。

simplify_expression

运行简化表达式优化。

slice_pushdown

切片下推优化。

collapse_joins

将连接和过滤器合并为更快的连接

no_optimization

关闭（某些）优化。

storage_options

指示如何连接到云提供商的选项。

目前支持的云提供商有AWS、GCP和Azure。查看支持的密钥请点击这里：

aws
gcp
azure
Hugging Face (hf://): 接受在 token 参数下的 API 密钥：{'token': '...'}，或者通过设置 HF_TOKEN 环境变量。

如果未提供storage_options，Polars将尝试从环境变量中推断信息。

credential_provider

提供一个可以被调用的函数来提供云存储凭证。该函数预期返回一个包含凭证键的字典以及一个可选的凭证过期时间。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

retries

如果访问云实例失败，重试次数。

Returns:

DataFrame

示例

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_ipc("out.arrow")  

sink_ndjson( path: str | Path, *, maintain_order: bool = True, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, collapse_joins: bool = True, no_optimization: bool = False, storage_options: dict[str, Any] | None = None, credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto', retries: int = 2, ) → None[source]

在流模式下评估查询并将结果写入NDJSON文件。

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

这允许将大于RAM的流式结果写入磁盘。

Parameters:

path

文件应写入的文件路径。

maintain_order

保持数据处理的顺序。将此设置为False会稍微快一些。

type_coercion

进行类型强制优化。

predicate_pushdown

执行谓词下推优化。

projection_pushdown

执行投影下推优化。

simplify_expression

运行简化表达式优化。

slice_pushdown

切片下推优化。

collapse_joins

将连接和过滤器合并为更快的连接

no_optimization

关闭（某些）优化。

storage_options

指示如何连接到云提供商的选项。

目前支持的云提供商有AWS、GCP和Azure。查看支持的密钥请点击这里：

aws
gcp
azure
Hugging Face (hf://): 接受在 token 参数下的 API 密钥：{'token': '...'}，或者通过设置 HF_TOKEN 环境变量。

如果未提供storage_options，Polars将尝试从环境变量中推断信息。

credential_provider

提供一个可以被调用的函数来提供云存储凭证。该函数预期返回一个包含凭证键的字典以及一个可选的凭证过期时间。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

retries

如果访问云实例失败，重试次数。

Returns:

DataFrame

示例

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_ndjson("out.ndjson")  

sink_parquet( path: str | Path, *, compression: str = 'zstd', compression_level: int | None = None, statistics: bool | str | dict[str, bool] = True, row_group_size: int | None = None, data_page_size: int | None = None, maintain_order: bool = True, type_coercion: bool = True, _type_check: bool = True, predicate_pushdown: bool = True, projection_pushdown: bool = True, simplify_expression: bool = True, slice_pushdown: bool = True, collapse_joins: bool = True, no_optimization: bool = False, storage_options: dict[str, Any] | None = None, credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto', retries: int = 2, ) → None[source]

在流模式下评估查询并将结果写入Parquet文件。

警告

流模式被认为是不稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

这允许将大于RAM的流式结果写入磁盘。

Parameters:

path

文件应写入的文件路径。

compression{‘lz4’, ‘uncompressed’, ‘snappy’, ‘gzip’, ‘lzo’, ‘brotli’, ‘zstd’}

选择“zstd”以获得良好的压缩性能。选择“lz4”以实现快速的压缩/解压缩。选择“snappy”以在处理较旧的parquet读取器时获得更多的向后兼容性保证。

compression_level

使用的压缩级别。更高的压缩意味着磁盘上的文件更小。

“gzip” : 最小级别: 0, 最大级别: 10.
“brotli”：最小级别：0，最大级别：11。
“zstd” : 最小级别: 1, 最大级别: 22.

statistics

将统计信息写入parquet头部。这是默认行为。

可能的值：

True: 启用默认的统计集合（默认）
False: 禁用所有统计信息
“full”：计算并写入所有可用的统计信息。不能与use_pyarrow结合使用。
{ "statistic-key": True / False, ... }. 不能与 use_pyarrow 结合使用。可用的键:
- “min”: 列的最小值 (默认: True)
- “max”: 列的最大值 (默认: True)
- “distinct_count”: 唯一列值的数量（默认值：False）
- “null_count”: 列中空值的数量（默认值：True）

row_group_size

行组的大小，以行数为单位。如果为None（默认值），则使用DataFrame的块。以较小的块写入可能会减少内存压力并提高写入速度。

data_page_size

单个数据页的大小限制。如果未设置，默认为1024 * 1024字节

maintain_order

保持数据处理的顺序。将此设置为False会稍微快一些。

type_coercion

进行类型强制优化。

predicate_pushdown

执行谓词下推优化。

projection_pushdown

执行投影下推优化。

simplify_expression

运行简化表达式优化。

slice_pushdown

切片下推优化。

collapse_joins

将连接和过滤器合并为更快的连接

no_optimization

关闭（某些）优化。

storage_options

指示如何连接到云提供商的选项。

目前支持的云提供商有AWS、GCP和Azure。查看支持的密钥请点击这里：

aws
gcp
azure
Hugging Face (hf://): 接受在 token 参数下的 API 密钥：{'token': '...'}，或者通过设置 HF_TOKEN 环境变量。

如果未提供storage_options，Polars将尝试从环境变量中推断信息。

credential_provider

提供一个可以被调用的函数来提供云存储凭证。该函数预期返回一个包含凭证键的字典以及一个可选的凭证过期时间。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

retries

如果访问云实例失败，重试次数。

Returns:

DataFrame

示例

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_parquet("out.parquet")  

slice( offset: int, length: int | None = None, ) → LazyFrame[source]

获取此DataFrame的一个切片。

Parameters:

offset: 起始索引。支持负索引。
length: 切片的长度。如果设置为None，将从偏移量开始选择所有行。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["x", "y", "z"],
...         "b": [1, 3, 5],
...         "c": [2, 4, 6],
...     }
... )
>>> lf.slice(1, 2).collect()
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ y   ┆ 3   ┆ 4   │
│ z   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

sort( by: IntoExpr | Iterable[IntoExpr], *more_by: IntoExpr, descending: bool | Sequence[bool] = False, nulls_last: bool | Sequence[bool] = False, maintain_order: bool = False, multithreaded: bool = True, ) → LazyFrame[source]

按给定的列对LazyFrame进行排序。

Parameters:

by: 要排序的列。接受表达式输入，包括选择器。字符串被解析为列名。
*more_by: 要排序的附加列，指定为位置参数。
descending: 按降序排序。当按多列排序时，可以通过传递布尔值序列来为每列指定。
nulls_last: 将空值放在最后；可以指定一个适用于所有列的布尔值，或者为每列控制指定一个布尔值序列。
maintain_order: 如果元素相等，是否应保持顺序。请注意，如果true，则无法进行流式处理，性能可能会更差，因为这需要一个稳定的搜索。
multithreaded: 使用多线程进行排序。

示例

传递单个列名以按该列排序。

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, None],
...         "b": [6.0, 5.0, 4.0],
...         "c": ["a", "c", "b"],
...     }
... )
>>> lf.sort("a").collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ null ┆ 4.0 ┆ b   │
│ 1    ┆ 6.0 ┆ a   │
│ 2    ┆ 5.0 ┆ c   │
└──────┴─────┴─────┘

支持通过表达式进行排序。

>>> lf.sort(pl.col("a") + pl.col("b") * 2, nulls_last=True).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 2    ┆ 5.0 ┆ c   │
│ 1    ┆ 6.0 ┆ a   │
│ null ┆ 4.0 ┆ b   │
└──────┴─────┴─────┘

通过传递列列表按多列排序。

>>> lf.sort(["c", "a"], descending=True).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 2    ┆ 5.0 ┆ c   │
│ null ┆ 4.0 ┆ b   │
│ 1    ┆ 6.0 ┆ a   │
└──────┴─────┴─────┘

或者使用位置参数以相同的方式按多列排序。

>>> lf.sort("c", "a", descending=[False, True]).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 1    ┆ 6.0 ┆ a   │
│ null ┆ 4.0 ┆ b   │
│ 2    ┆ 5.0 ┆ c   │
└──────┴─────┴─────┘

sql( query: str, *, table_name: str = 'self', ) → LazyFrame[source]

对LazyFrame执行SQL查询。

在版本0.20.23中添加。

警告

此功能被认为是不稳定的，尽管它接近被认为是稳定的。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

query: 要执行的SQL查询。
table_name: 可选地提供一个明确的名称来表示调用帧的表（默认为“self”）。

另请参阅

SQLContext

注释

调用框架会自动在SQL上下文中注册为一个名为“self”的表。如果你想访问当前全局变量中的DataFrames和LazyFrames，请使用顶层的pl.sql。
通过使用SQLContext对象，可以更好地控制注册和执行行为。

示例

>>> lf1 = pl.LazyFrame({"a": [1, 2, 3], "b": [6, 7, 8], "c": ["z", "y", "x"]})
>>> lf2 = pl.LazyFrame({"a": [3, 2, 1], "d": [125, -654, 888]})

使用SQL查询LazyFrame：

>>> lf1.sql("SELECT c, b FROM self WHERE a > 1").collect()
shape: (2, 2)
┌─────┬─────┐
│ c   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ y   ┆ 7   │
│ x   ┆ 8   │
└─────┴─────┘

应用SQL转换（将“self”别名为“frame”），然后进行本地过滤（您可以自由混合SQL和本地操作）：

>>> lf1.sql(
...     query='''
...         SELECT
...             a,
...             (a % 2 == 0) AS a_is_even,
...             (b::float4 / 2) AS "b/2",
...             CONCAT_WS(':', c, c, c) AS c_c_c
...         FROM frame
...         ORDER BY a
...     ''',
...     table_name="frame",
... ).filter(~pl.col("c_c_c").str.starts_with("x")).collect()
shape: (2, 4)
┌─────┬───────────┬─────┬───────┐
│ a   ┆ a_is_even ┆ b/2 ┆ c_c_c │
│ --- ┆ ---       ┆ --- ┆ ---   │
│ i64 ┆ bool      ┆ f32 ┆ str   │
╞═════╪═══════════╪═════╪═══════╡
│ 1   ┆ false     ┆ 3.0 ┆ z:z:z │
│ 2   ┆ true      ┆ 3.5 ┆ y:y:y │
└─────┴───────────┴─────┴───────┘

std(ddof: int = 1) → LazyFrame[source]

将LazyFrame中的列聚合为其标准差值。

Parameters:

ddof: “自由度差值”：计算中使用的除数是 N - ddof，其中 N 表示元素的数量。默认情况下，ddof 为 1。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.std().collect()
shape: (1, 2)
┌──────────┬─────┐
│ a        ┆ b   │
│ ---      ┆ --- │
│ f64      ┆ f64 │
╞══════════╪═════╡
│ 1.290994 ┆ 0.5 │
└──────────┴─────┘
>>> lf.std(ddof=0).collect()
shape: (1, 2)
┌──────────┬──────────┐
│ a        ┆ b        │
│ ---      ┆ ---      │
│ f64      ┆ f64      │
╞══════════╪══════════╡
│ 1.118034 ┆ 0.433013 │
└──────────┴──────────┘

sum() → LazyFrame[source]

将LazyFrame中的列聚合为其总和值。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.sum().collect()
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 10  ┆ 5   │
└─────┴─────┘

tail(n: int = 5) → LazyFrame[source]

获取最后 n 行。

Parameters:

n: 返回的行数。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [7, 8, 9, 10, 11, 12],
...     }
... )
>>> lf.tail().collect()
shape: (5, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 8   │
│ 3   ┆ 9   │
│ 4   ┆ 10  │
│ 5   ┆ 11  │
│ 6   ┆ 12  │
└─────┴─────┘
>>> lf.tail(2).collect()
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 5   ┆ 11  │
│ 6   ┆ 12  │
└─────┴─────┘

top_k( k: int, *, by: IntoExpr | Iterable[IntoExpr], reverse: bool | Sequence[bool] = False, ) → LazyFrame[source]

返回k个最大的行。

非空元素总是优先于空元素，无论reverse的值如何。输出不保证按任何特定顺序排列，如果您希望输出排序，请在此函数后调用sort()。

Parameters:

k: 返回的行数。
by: 用于确定顶部行的列。接受表达式输入。字符串被解析为列名。
reverse: 考虑by列中的k个最小元素（而不是k个最大元素）。可以通过传递一个布尔值序列来为每列指定这一点。

另请参阅

bottom_k

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["a", "b", "a", "b", "b", "c"],
...         "b": [2, 1, 1, 3, 2, 1],
...     }
... )

获取包含列 b 中 4 个最大值的行。

>>> lf.top_k(4, by="b").collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ a   ┆ 2   │
│ b   ┆ 2   │
│ b   ┆ 1   │
└─────┴─────┘

获取在列b和a上排序时包含4个最大值的行。

>>> lf.top_k(4, by=["b", "a"]).collect()
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ b   ┆ 2   │
│ a   ┆ 2   │
│ c   ┆ 1   │
└─────┴─────┘

unique( subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None, *, keep: UniqueKeepStrategy = 'any', maintain_order: bool = False, ) → LazyFrame[source]

从这个DataFrame中删除重复的行。

Parameters:

subset

列名或选择器，用于在识别重复行时考虑。如果设置为None（默认值），则使用所有列。

keep{‘first’, ‘last’, ‘any’, ‘none’}

保留哪些重复行。

‘any’: Does not give any guarantee of which row is kept.
这允许更多的优化。
‘none’: 不保留重复的行。
‘first’: 保留第一个唯一的行。
‘last’: 保留最后一行唯一行。

maintain_order

保持与原始DataFrame相同的顺序。这需要更高的计算成本。将此设置为True会阻止在流引擎上运行的可能性。

Returns:

LazyFrame: 具有唯一行的LazyFrame。

警告

如果DataFrame或子集中有类型为List的列，则此方法将失败。

注释

如果你来自pandas，这类似于 pandas.DataFrame.drop_duplicates。

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3, 1],
...         "bar": ["a", "a", "a", "a"],
...         "ham": ["b", "b", "b", "b"],
...     }
... )
>>> lf.unique(maintain_order=True).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
└─────┴─────┴─────┘
>>> lf.unique(subset=["bar", "ham"], maintain_order=True).collect()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
└─────┴─────┴─────┘
>>> lf.unique(keep="last", maintain_order=True).collect()
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
│ 1   ┆ a   ┆ b   │
└─────┴─────┴─────┘

unnest( columns: ColumnNameOrSelector | Collection[ColumnNameOrSelector], *more_columns: ColumnNameOrSelector, ) → LazyFrame[source]

将结构体列分解为每个字段的单独列。

新列将被插入到DataFrame中结构列的位置。

Parameters:

columns: 应该被解构的结构体列的名称。
*more_columns: 要解嵌套的额外列，指定为位置参数。

示例

>>> df = pl.LazyFrame(
...     {
...         "before": ["foo", "bar"],
...         "t_a": [1, 2],
...         "t_b": ["a", "b"],
...         "t_c": [True, None],
...         "t_d": [[1, 2], [3]],
...         "after": ["baz", "womp"],
...     }
... ).select("before", pl.struct(pl.col("^t_.$")).alias("t_struct"), "after")
>>> df.collect()
shape: (2, 3)
┌────────┬─────────────────────┬───────┐
│ before ┆ t_struct            ┆ after │
│ ---    ┆ ---                 ┆ ---   │
│ str    ┆ struct[4]           ┆ str   │
╞════════╪═════════════════════╪═══════╡
│ foo    ┆ {1,"a",true,[1, 2]} ┆ baz   │
│ bar    ┆ {2,"b",null,[3]}    ┆ womp  │
└────────┴─────────────────────┴───────┘
>>> df.unnest("t_struct").collect()
shape: (2, 6)
┌────────┬─────┬─────┬──────┬───────────┬───────┐
│ before ┆ t_a ┆ t_b ┆ t_c  ┆ t_d       ┆ after │
│ ---    ┆ --- ┆ --- ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64 ┆ str ┆ bool ┆ list[i64] ┆ str   │
╞════════╪═════╪═════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1   ┆ a   ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2   ┆ b   ┆ null ┆ [3]       ┆ womp  │
└────────┴─────┴─────┴──────┴───────────┴───────┘

将DataFrame从宽格式转换为长格式。

可选地保留标识符设置。

此函数有助于将DataFrame整理成一种格式，其中一列或多列是标识符变量（索引），而所有其他列，被视为测量变量（on），被“逆透视”到行轴，只留下两个非标识符列，'variable'和'value'。

Parameters:

on: 用作值变量的列或选择器；如果on为空，则将使用不在index中的所有列。
index: 用作标识符变量的列或选择器。
variable_name: 为variable列指定的名称。默认为“variable”
value_name: 为value列指定的名称。默认为“value”
streamable: 已弃用

注释

如果你来自pandas，这类似于pandas.DataFrame.melt，但是用index替换id_vars，用on替换value_vars。在其他框架中，你可能知道这个操作为pivot_longer。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": ["x", "y", "z"],
...         "b": [1, 3, 5],
...         "c": [2, 4, 6],
...     }
... )
>>> import polars.selectors as cs
>>> lf.unpivot(cs.numeric(), index="a").collect()
shape: (6, 3)
┌─────┬──────────┬───────┐
│ a   ┆ variable ┆ value │
│ --- ┆ ---      ┆ ---   │
│ str ┆ str      ┆ i64   │
╞═════╪══════════╪═══════╡
│ x   ┆ b        ┆ 1     │
│ y   ┆ b        ┆ 3     │
│ z   ┆ b        ┆ 5     │
│ x   ┆ c        ┆ 2     │
│ y   ┆ c        ┆ 4     │
│ z   ┆ c        ┆ 6     │
└─────┴──────────┴───────┘

使用other中的值更新此LazyFrame中的值。

警告

此功能被视为不稳定。它可能会在任何时候更改，而不被视为破坏性更改。

Parameters:

other

将用于更新值的LazyFrame

on

将用于连接的列名。如果设置为None（默认值），则使用每个框架的隐式行索引作为连接键。

how{‘left’, ‘inner’, ‘full’}

'left' 将保留左表中的所有行；如果右表中的多行与左行的键匹配，则行可能会重复。
‘inner’ 只保留那些键在两个框架中都存在的行。
'full' 将更新键匹配的现有行，同时添加给定帧中包含的任何新行。

left_on

连接左侧DataFrame的列。

right_on

连接右侧DataFrame的列。

include_nulls

用右侧框架中的空值覆盖左侧框架中的值。如果设置为False（默认值），则忽略右侧框架中的空值。

注释

这是左连接/内连接的语法糖，当include_nulls = False时，可以选择使用coalesce。

示例

>>> lf = pl.LazyFrame(
...     {
...         "A": [1, 2, 3, 4],
...         "B": [400, 500, 600, 700],
...     }
... )
>>> lf.collect()
shape: (4, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 400 │
│ 2   ┆ 500 │
│ 3   ┆ 600 │
│ 4   ┆ 700 │
└─────┴─────┘
>>> new_lf = pl.LazyFrame(
...     {
...         "B": [-66, None, -99],
...         "C": [5, 3, 1],
...     }
... )

使用new_df中的非空值按行索引更新df的值：

>>> lf.update(new_lf).collect()
shape: (4, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -66 │
│ 2   ┆ 500 │
│ 3   ┆ -99 │
│ 4   ┆ 700 │
└─────┴─────┘

使用new_df中的非空值按行索引更新df的值，但仅保留两个框架中共有的行：

>>> lf.update(new_lf, how="inner").collect()
shape: (3, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -66 │
│ 2   ┆ 500 │
│ 3   ┆ -99 │
└─────┴─────┘

使用new_df中的非空值更新df值，采用全外连接策略，该策略在每个框架中定义了明确的连接列：

>>> lf.update(new_lf, left_on=["A"], right_on=["C"], how="full").collect()
shape: (5, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -99 │
│ 2   ┆ 500 │
│ 3   ┆ 600 │
│ 4   ┆ 700 │
│ 5   ┆ -66 │
└─────┴─────┘

更新 df 值，包括 new_df 中的空值，使用定义每个框架中明确连接列的完全外连接策略：

>>> lf.update(
...     new_lf, left_on="A", right_on="C", how="full", include_nulls=True
... ).collect()
shape: (5, 2)
┌─────┬──────┐
│ A   ┆ B    │
│ --- ┆ ---  │
│ i64 ┆ i64  │
╞═════╪══════╡
│ 1   ┆ -99  │
│ 2   ┆ 500  │
│ 3   ┆ null │
│ 4   ┆ 700  │
│ 5   ┆ -66  │
└─────┴──────┘

var(ddof: int = 1) → LazyFrame[source]

将LazyFrame中的列聚合为其方差值。

Parameters:

ddof: “自由度差值”：计算中使用的除数是 N - ddof，其中 N 表示元素的数量。默认情况下，ddof 为 1。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [1, 2, 1, 1],
...     }
... )
>>> lf.var().collect()
shape: (1, 2)
┌──────────┬──────┐
│ a        ┆ b    │
│ ---      ┆ ---  │
│ f64      ┆ f64  │
╞══════════╪══════╡
│ 1.666667 ┆ 0.25 │
└──────────┴──────┘
>>> lf.var(ddof=0).collect()
shape: (1, 2)
┌──────┬────────┐
│ a    ┆ b      │
│ ---  ┆ ---    │
│ f64  ┆ f64    │
╞══════╪════════╡
│ 1.25 ┆ 0.1875 │
└──────┴────────┘

property width: int[source]

获取列数。

Returns:

int

警告

确定LazyFrame的宽度需要解析其模式，这可能是一个昂贵的操作。使用collect_schema()是解析模式的惯用方法。此属性仅存在于与DataFrame类的对称性中。

另请参阅

collect_schema
Schema.len

示例

>>> lf = pl.LazyFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4, 5, 6],
...     }
... )
>>> lf.width  
2

with_columns(

*exprs: IntoExpr | Iterable[IntoExpr],

**named_exprs: IntoExpr,

) → LazyFrame[source]

向此LazyFrame添加列。

添加的列将替换具有相同名称的现有列。

Parameters:

*exprs: 要添加的列，指定为位置参数。接受表达式输入。字符串被解析为列名，其他非表达式输入被解析为字面量。
**named_exprs: 要添加的额外列，指定为关键字参数。这些列将被重命名为所使用的关键字。

Returns:

LazyFrame: 一个新的LazyFrame，添加了列。

注释

使用此方法创建新的LazyFrame不会创建现有数据的新副本。

示例

传递一个表达式以将其添加为新列。

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [0.5, 4, 10, 13],
...         "c": [True, True, False, True],
...     }
... )
>>> lf.with_columns((pl.col("a") ** 2).alias("a^2")).collect()
shape: (4, 4)
┌─────┬──────┬───────┬─────┐
│ a   ┆ b    ┆ c     ┆ a^2 │
│ --- ┆ ---  ┆ ---   ┆ --- │
│ i64 ┆ f64  ┆ bool  ┆ i64 │
╞═════╪══════╪═══════╪═════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   │
│ 2   ┆ 4.0  ┆ true  ┆ 4   │
│ 3   ┆ 10.0 ┆ false ┆ 9   │
│ 4   ┆ 13.0 ┆ true  ┆ 16  │
└─────┴──────┴───────┴─────┘

添加的列将替换具有相同名称的现有列。

>>> lf.with_columns(pl.col("a").cast(pl.Float64)).collect()
shape: (4, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ f64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╡
│ 1.0 ┆ 0.5  ┆ true  │
│ 2.0 ┆ 4.0  ┆ true  │
│ 3.0 ┆ 10.0 ┆ false │
│ 4.0 ┆ 13.0 ┆ true  │
└─────┴──────┴───────┘

可以使用位置参数添加多列。

>>> lf.with_columns(
...     (pl.col("a") ** 2).alias("a^2"),
...     (pl.col("b") / 2).alias("b/2"),
...     (pl.col("c").not_()).alias("not c"),
... ).collect()
shape: (4, 6)
┌─────┬──────┬───────┬─────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ a^2 ┆ b/2  ┆ not c │
│ --- ┆ ---  ┆ ---   ┆ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   ┆ 0.25 ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 4   ┆ 2.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 9   ┆ 5.0  ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 16  ┆ 6.5  ┆ false │
└─────┴──────┴───────┴─────┴──────┴───────┘

也可以通过传递表达式列表来添加多个列。

>>> lf.with_columns(
...     [
...         (pl.col("a") ** 2).alias("a^2"),
...         (pl.col("b") / 2).alias("b/2"),
...         (pl.col("c").not_()).alias("not c"),
...     ]
... ).collect()
shape: (4, 6)
┌─────┬──────┬───────┬─────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ a^2 ┆ b/2  ┆ not c │
│ --- ┆ ---  ┆ ---   ┆ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   ┆ 0.25 ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 4   ┆ 2.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 9   ┆ 5.0  ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 16  ┆ 6.5  ┆ false │
└─────┴──────┴───────┴─────┴──────┴───────┘

使用关键字参数可以轻松命名您的表达式输入。

>>> lf.with_columns(
...     ab=pl.col("a") * pl.col("b"),
...     not_c=pl.col("c").not_(),
... ).collect()
shape: (4, 5)
┌─────┬──────┬───────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ ab   ┆ not_c │
│ --- ┆ ---  ┆ ---   ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 0.5  ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 8.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 30.0 ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 52.0 ┆ false │
└─────┴──────┴───────┴──────┴───────┘

通过启用实验性设置 Config.set_auto_structify(True)，具有多个输出的表达式可以自动实例化为结构体：

>>> with pl.Config(auto_structify=True):
...     lf.drop("c").with_columns(
...         diffs=pl.col(["a", "b"]).diff().name.suffix("_diff"),
...     ).collect()
shape: (4, 3)
┌─────┬──────┬─────────────┐
│ a   ┆ b    ┆ diffs       │
│ --- ┆ ---  ┆ ---         │
│ i64 ┆ f64  ┆ struct[2]   │
╞═════╪══════╪═════════════╡
│ 1   ┆ 0.5  ┆ {null,null} │
│ 2   ┆ 4.0  ┆ {1,3.5}     │
│ 3   ┆ 10.0 ┆ {1,6.0}     │
│ 4   ┆ 13.0 ┆ {1,3.0}     │
└─────┴──────┴─────────────┘

with_columns_seq(

*exprs: IntoExpr | Iterable[IntoExpr],

**named_exprs: IntoExpr,

) → LazyFrame[source]

向此LazyFrame添加列。

添加的列将替换具有相同名称的现有列。

这将按顺序运行所有表达式，而不是并行运行。当每个表达式的工作量较小时使用此方法。

Parameters:

*exprs: 要添加的列，指定为位置参数。接受表达式输入。字符串被解析为列名，其他非表达式输入被解析为字面量。
**named_exprs: 要添加的额外列，指定为关键字参数。这些列将被重命名为所使用的关键字。

Returns:

LazyFrame: 一个新的LazyFrame，添加了列。

另请参阅

with_columns

with_context(other: Self | list[Self]) → LazyFrame[source]

向计算图添加外部上下文。

自版本1.0.0起已弃用：请改用concat()，并使用how='horizontal'

这允许表达式也可以访问不属于此DataFrame的其他DataFrame中的列。

Parameters:

other: 要连接的惰性DataFrame。

示例

>>> lf = pl.LazyFrame({"a": [1, 2, 3], "b": ["a", "c", None]})
>>> lf_other = pl.LazyFrame({"c": ["foo", "ham"]})
>>> lf.with_context(lf_other).select(  
...     pl.col("b") + pl.col("c").first()
... ).collect()
shape: (3, 1)
┌──────┐
│ b    │
│ ---  │
│ str  │
╞══════╡
│ afoo │
│ cfoo │
│ null │
└──────┘

用另一个DataFrame的中位数填充空值：

>>> train_lf = pl.LazyFrame(
...     {"feature_0": [-1.0, 0, 1], "feature_1": [-1.0, 0, 1]}
... )
>>> test_lf = pl.LazyFrame(
...     {"feature_0": [-1.0, None, 1], "feature_1": [-1.0, 0, 1]}
... )
>>> test_lf.with_context(  
...     train_lf.select(pl.all().name.suffix("_train"))
... ).select(
...     pl.col("feature_0").fill_null(pl.col("feature_0_train").median())
... ).collect()
shape: (3, 1)
┌───────────┐
│ feature_0 │
│ ---       │
│ f64       │
╞═══════════╡
│ -1.0      │
│ 0.0       │
│ 1.0       │
└───────────┘

with_row_count( name: str = 'row_nr', offset: int = 0, ) → LazyFrame[source]

在第0列添加一个用于计算行数的列。

自版本0.20.4起已弃用：请改用with_row_index()。请注意，默认列名已从‘row_nr’更改为‘index’。

Parameters:

name: 要添加的列的名称。
offset: 从这个偏移量开始行计数。

警告

这可能对查询性能产生负面影响。例如，这可能会阻止谓词下推优化。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.with_row_count().collect()  
shape: (3, 3)
┌────────┬─────┬─────┐
│ row_nr ┆ a   ┆ b   │
│ ---    ┆ --- ┆ --- │
│ u32    ┆ i64 ┆ i64 │
╞════════╪═════╪═════╡
│ 0      ┆ 1   ┆ 2   │
│ 1      ┆ 3   ┆ 4   │
│ 2      ┆ 5   ┆ 6   │
└────────┴─────┴─────┘

with_row_index( name: str = 'index', offset: int = 0, ) → LazyFrame[source]

在LazyFrame中添加一行索引作为第一列。

Parameters:

name: 索引列的名称。
offset: 从这个偏移量开始索引。不能为负数。

警告

使用此函数可能会对查询性能产生负面影响。例如，这可能会阻止谓词下推优化。

注释

生成的列没有任何特殊属性。它是一个常规的列，类型为 UInt32（或在 polars-u64-idx 中为 UInt64）。

示例

>>> lf = pl.LazyFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> lf.with_row_index().collect()
shape: (3, 3)
┌───────┬─────┬─────┐
│ index ┆ a   ┆ b   │
│ ---   ┆ --- ┆ --- │
│ u32   ┆ i64 ┆ i64 │
╞═══════╪═════╪═════╡
│ 0     ┆ 1   ┆ 2   │
│ 1     ┆ 3   ┆ 4   │
│ 2     ┆ 5   ┆ 6   │
└───────┴─────┴─────┘
>>> lf.with_row_index("id", offset=1000).collect()
shape: (3, 3)
┌──────┬─────┬─────┐
│ id   ┆ a   ┆ b   │
│ ---  ┆ --- ┆ --- │
│ u32  ┆ i64 ┆ i64 │
╞══════╪═════╪═════╡
│ 1000 ┆ 1   ┆ 2   │
│ 1001 ┆ 3   ┆ 4   │
│ 1002 ┆ 5   ┆ 6   │
└──────┴─────┴─────┘

索引列也可以使用表达式 int_range() 和 len() 创建。

>>> lf.select(
...     pl.int_range(pl.len(), dtype=pl.UInt32).alias("index"),
...     pl.all(),
... ).collect()
shape: (3, 3)
┌───────┬─────┬─────┐
│ index ┆ a   ┆ b   │
│ ---   ┆ --- ┆ --- │
│ u32   ┆ i64 ┆ i64 │
╞═══════╪═════╪═════╡
│ 0     ┆ 1   ┆ 2   │
│ 1     ┆ 3   ┆ 4   │
│ 2     ┆ 5   ┆ 6   │
└───────┴─────┴─────┘