polars.DataFrame.gather#

DataFrame.gather( indices: int | Sequence[int] | IntoExpr | Series | np.ndarray[Any, Any], *, null_on_oob: bool = False, ) → DataFrame[source]#

Selects rows from this DataFrame 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.
null_on_oob: If true when an index is out-of-bounds a null row will be generated instead of raising an error.

Examples

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

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