{"record":{"id":"4179644e72fae243","repo":"pola-rs/polars","slug":"expressions-should-be-passed-to-the-by-predicate","errorCode":null,"errorMessage":"expressions should be passed to the `by_predicate` parameter","messagePattern":"expressions should be passed to the `by_predicate` parameter","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":11866,"sourceCode":"\n        >>> df.row(by_predicate=(pl.col(\"ham\") == \"b\"))\n        (2, 7, 'b')\n        \"\"\"\n        if index is None and by_predicate is None:\n            if self.height == 1:\n                index = 0\n            else:\n                msg = (\n                    'can only call `.row()` without \"index\" or \"by_predicate\" values '\n                    f\"if the DataFrame has a single row; shape={self.shape!r}\"\n                )\n                raise ValueError(msg)\n        elif index is not None and by_predicate is not None:\n            msg = \"cannot set both 'index' and 'by_predicate'; mutually exclusive\"\n            raise ValueError(msg)\n        elif isinstance(index, pl.Expr):\n            msg = \"expressions should be passed to the `by_predicate` parameter\"\n            raise TypeError(msg)\n\n        if index is not None:\n            row = self._df.row_tuple(index)\n            if named:\n                return dict(zip(self.columns, row, strict=True))\n            else:\n                return row\n\n        elif by_predicate is not None:\n            if not isinstance(by_predicate, pl.Expr):\n                msg = f\"expected `by_predicate` to be an expression, got {qualified_type_name(by_predicate)!r}\"\n                raise TypeError(msg)\n            rows = self.filter(by_predicate).rows()\n            n_rows = len(rows)\n            if n_rows > 1:\n                msg = f\"predicate <{by_predicate!s}> returned {n_rows} rows\"\n                raise TooManyRowsReturnedError(msg)\n            elif n_rows == 0:","sourceCodeStart":11848,"sourceCodeEnd":11884,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L11848-L11884","documentation":"DataFrame.row reserves `index` for integer row positions; expressions must go to the `by_predicate` parameter. Passing a pl.Expr as the positional or `index` argument — a natural mistake because many polars methods accept expressions positionally — raises this TypeError telling you to move it to by_predicate.","triggerScenarios":"df.row(pl.col('id') == 42); df.row(pl.first()); df.row(index=pl.col('ts').arg_max()) — any call where the first argument or index is a pl.Expr instead of an int.","commonSituations":"Coming from expression-style APIs (filter, select, with_columns) where expressions are passed positionally; muscle memory from Series/expr APIs; IDE autocompleting the first parameter with an expression.","solutions":["Move the expression to the keyword: df.row(by_predicate=pl.col('id') == 42)","If you meant a computed position, evaluate it first: pos = df.select(pl.col('ts').arg_max()).item(); df.row(pos)","Remember the rule: integers -> index, expressions -> by_predicate"],"exampleFix":"# before\nrow = df.row(pl.col('id') == 42)\n\n# after\nrow = df.row(by_predicate=pl.col('id') == 42)","handlingStrategy":"type-guard","validationCode":"from polars.expr import Expr\n\nif isinstance(index, Expr):\n    raise TypeError('expressions belong in by_predicate=; pass an int index')\nrow = df.row(index=index)","typeGuard":"from polars.expr import Expr\n\ndef is_row_index(v: object) -> bool:\n    return v is None or (isinstance(v, int) and not isinstance(v, bool))","tryCatchPattern":null,"preventionTips":["Apply the rule integers->index, expressions->by_predicate at every row() call site","For computed positions, evaluate the expression first via df.select(...).item()","Let mypy help: annotate index parameters as int | None, never IntoExpr"],"tags":["polars","dataframe","row","typeerror","expression","parameter-misuse"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}