Selecting with indexing

In this page we cover use of square bracket indexing to select data. Square bracket indexing can be used to select rows and/or columns.

Indexing is an anti-pattern in Polars

Indexing polars with square brackets is considered an anti-pattern and the functionality may be removed in the future. Polars strongly favours the expression API with select and filter in favor of accessing by square bracket indexing. See the introduction to this section for more information.

Indexing does not work in lazy mode

Selecting data by indexing only works with a DataFrame in eager mode. If you try to select data by indexing on a LazyFrame it will raise an exception that a LazyFrame is not subscriptable. Instead you need to select data using expressions.

Rules for square bracket indexing

The rules for square bracket indexing are as follows (depending on the datatypes of the values):

  • numeric

    • axis 0: row
    • axis 1: column

  • numeric + strings

    • axis 0: row (only accept numbers here)
    • axis 1: column (accept numeric + string values)

  • only strings

    • axis 0: column
    • axis 1: error

  • expressions

    All expression evaluations are executed in parallel

    • axis 0: column
    • axis 1: column
    • ..
    • axis n: column

Comparison with pandas

pandaspolars
select row
df.iloc[2]		df[2, :]
select several rows by their indices
df.iloc[[2, 5, 6]]		df[[2, 5, 6], :]
select slice of rows
df.iloc[2:6]		df[2:6, :]
select rows using a boolean mask
df.iloc[True, True, False]		df.filter([True, True, False])
select rows by a predicate condition
df.loc[df["A"] > 3]		df[df["A"] > 3]
select slice of columns
df.iloc[:, 1:3]		df[:, 1:3]
select slice of columns by string order
df.loc[:, "A":"Z"]		df[:, "A":"Z"]
select a single value (scalar)
df.loc[2, "A"]		df[2, "A"]
select a single value (scalar)
df.iloc[2, 1]		df[2, 1]
select a single value (Series/DataFrame)
df.loc[2, ["A"]]		df[2, ["A"]]
select a single value (Series/DataFrame)
df.iloc[2, [1]]		df[2, [1]]