{"record":{"id":"fec39b6b4180fb3f","repo":"pola-rs/polars","slug":"passing-a-list-to-search-sorted-is-ambiguous-us","errorCode":null,"errorMessage":"passing a list to `search_sorted` is ambiguous; use `Series.search_sorted(pl.Series([...]), ...)` or `Series.search_sorted(pl.lit(...), ...)`","messagePattern":"passing a list to `search_sorted` is ambiguous; use `Series\\.search_sorted\\(pl\\.Series\\(\\[\\.\\.\\.\\]\\), \\.\\.\\.\\)` or `Series\\.search_sorted\\(pl\\.lit\\(\\.\\.\\.\\), \\.\\.\\.\\)`","errorType":"exception","errorClass":"InvalidOperationError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/series/series.py","lineNumber":3913,"sourceCode":"        Series: 'set' [u32]\n        [\n            0\n            3\n            5\n        ]\n        >>> # To search for a list of values in a series, of lists, use pl.lit():\n        >>> list_s = pl.Series(\"lists\", [[0, 1], [0, 2], [1, 4]])\n        >>> list_s.search_sorted(pl.lit([0, 2]), \"left\")\n        shape: (1,)\n        Series: 'lists' [u32]\n        [\n            1\n        ]\n        \"\"\"\n        df = F.select(F.lit(self).search_sorted(element, side, descending=descending))\n        if isinstance(element, list):\n            msg = \"passing a list to `search_sorted` is ambiguous; use `Series.search_sorted(pl.Series([...]), ...)` or `Series.search_sorted(pl.lit(...), ...)`\"\n            raise InvalidOperationError(msg)\n        elif isinstance(element, (Series, pl.Expr)):\n            return df.to_series()\n        elif _check_for_numpy(element) and isinstance(element, np.ndarray):\n            return df.to_series()\n        else:\n            return df.item()\n\n    def unique(self, *, maintain_order: bool = False) -> Series:\n        \"\"\"\n        Get unique elements in series.\n\n        `null` is considered to be a unique value for the purposes of this operation.\n\n        Parameters\n        ----------\n        maintain_order\n            Maintain order of data. This requires more work.\n","sourceCodeStart":3895,"sourceCodeEnd":3931,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/py-polars/src/polars/series/series.py#L3895-L3931","documentation":"Series.search_sorted dispatches differently depending on whether the searched element is a scalar, a Series, an expression, or a numpy array, and each returns a different shape (scalar vs Series). Passing a plain Python list is ambiguous — Polars cannot know whether you want element-wise results or a single value — so it raises InvalidOperationError.","triggerScenarios":"Calling Series.search_sorted with a Python list, e.g. s.search_sorted([1, 5, 10]) or with side/descending arguments and a list element.","commonSituations":"Developers coming from numpy's searchsorted or bisect who naturally pass a list of needles; batch lookup code that builds a list dynamically instead of a Series; refactors from scalar lookups to batch lookups.","solutions":["Wrap the list in a Series: s.search_sorted(pl.Series([1, 5, 10]))","Or wrap in a literal expression: s.search_sorted(pl.lit([1, 5, 10]))","For a single value, pass the scalar directly (not a one-element list)"],"exampleFix":"# before\ns.search_sorted([1, 5, 10])\n\n# after\ns.search_sorted(pl.Series([1, 5, 10]))","handlingStrategy":"type-guard","validationCode":"element = pl.Series(element) if isinstance(element, list) else element\nresult = s.search_sorted(element, side='any')","typeGuard":"def is_searchable(e: object) -> bool:\n    return e is None or isinstance(e, (int, float, str, pl.Series, pl.Expr)) or (\n        _check_for_numpy(e) and isinstance(e, np.ndarray)\n    )","tryCatchPattern":"try:\n    result = s.search_sorted(element, side)\nexcept pl.exceptions.InvalidOperationError as e:\n    if 'ambiguous' in str(e):\n        result = s.search_sorted(pl.Series(element), side)\n    else:\n        raise","preventionTips":["Always construct pl.Series(...) for batch lookups instead of passing raw lists","Lint/guard call sites that forward dynamic values into search_sorted"],"tags":["polars","search-sorted","type-ambiguity","invalid-operation","series"],"backgroundTag":"polars-ambiguous-argument-type","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-08-28T18:02:35.179Z","contentChangedAt":"2026-08-28T18:02:35.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}