polars.LazyFrame.gather#

Selects rows from this LazyFrame at the given indices.

Warning

This functionality is experimental. It may be changed at any point without it being considered a breaking change.

Parameters:

indices

The indices of the rows to select.

Due to the lack of a LazySeries it’s permitted to pass a single-width LazyFrame as indices as well.

null_on_oob

If true when an index is out-of-bounds a null row will be generated instead of raising an error.

Examples

>>> lf = pl.LazyFrame({"x": [2, 1, 0], "s": ["foo", "bar", "baz"]})
>>> lf.gather([2, 0, 0]).collect()
shape: (3, 2)
┌─────┬─────┐
│ x   ┆ s   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 0   ┆ baz │
│ 2   ┆ foo │
│ 2   ┆ foo │
└─────┴─────┘

>>> lf.gather([0, 10, 1], null_on_oob=True).collect()
shape: (3, 2)
┌──────┬──────┐
│ x    ┆ s    │
│ ---  ┆ ---  │
│ i64  ┆ str  │
╞══════╪══════╡
│ 2    ┆ foo  │
│ null ┆ null │
│ 1    ┆ bar  │
└──────┴──────┘

>>> idxs = pl.LazyFrame({"i": [1, 10, 0], "b": [True, False, True]})
>>> lf.gather(idxs.filter(pl.col.b).select(pl.col.i)).collect()
shape: (2, 2)
┌─────┬─────┐
│ x   ┆ s   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ bar │
│ 2   ┆ foo │
└─────┴─────┘