pola-rs/polars · error · ValueError

arr.dot query vector must be one-dimensional

Error message

arr.dot query vector must be one-dimensional

What it means

Expr.arr.dot computes a dot product between each array row and a query vector. When the query is a numpy array it must be 1-D; a 2-D (or higher) ndarray cannot be interpreted as a single query vector, so a ValueError is raised.

Solutions

1. Flatten or select a single row: pass arr[0] or arr.reshape(-1) so ndim == 1
2. Loop over rows of a 2-D numpy array and call arr.dot once per query vector
3. Use the Sequence branch instead (a plain Python list is converted via list.to_array)
4. Assert other.ndim == 1 before the call

Example fix

// before
col.arr.dot(embedding_matrix)  # shape (768, 10)
// after
col.arr.dot(embedding_matrix[:, 0])

if isinstance(q, np.ndarray) and q.ndim != 1:
    raise ValueError('query vector must be 1-D')

def is_1d_array(x) -> bool:
    return isinstance(x, np.ndarray) and x.ndim == 1

try:
    out = df.select(pl.col('a').arr.dot(q))
except ValueError as e:
    if 'one-dimensional' in str(e):
        q = np.asarray(q).reshape(-1)
        out = df.select(pl.col('a').arr.dot(q))
    else:
        raise

When it happens

Trigger: Calling df.select(pl.col('a').arr.dot(np_2d_array)) with an ndarray whose ndim != 1, e.g. a matrix of shape (n, m) or a batch of query vectors passed in one call.

Common situations: Passing embedding matrices or batched query vectors straight from numpy; forgetting to index/select one row of a 2-D array; reshaping changes elsewhere in the pipeline altering ndim.

Related errors

• arr.to_struct() got a str instead of a list. hint: pass
• can not match overlapping patterns when leftmost == True
• cannot convert DataFrame to
• cannot convert List column
• cannot parse numpy data type

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/586cac4c44e27d5f. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/expr/array.py:380

        Cast both inputs before ``dot`` to perform multiplication and accumulation in
        a type that can represent the result.

        >>> wide = pl.Array(pl.Int64, 2)
        >>> a.cast(wide).arr.dot(b.cast(wide))
        shape: (1,)
        Series: 'a' [i64]
        [
            400
        ]
        """
        if isinstance(other, Sequence) and not isinstance(other, (str, bytes)):
            other = list(other)
            other = F.lit(other).list.to_array(len(other))
        elif _check_for_numpy(other) and isinstance(other, np.ndarray):
            if other.ndim != 1:
                msg = "arr.dot query vector must be one-dimensional"
                raise ValueError(msg)
            other = F.lit(other).implode().list.to_array(other.size)

        other_pyexpr = parse_into_expression(other)
        return wrap_expr(self._pyexpr.arr_dot(other_pyexpr))

    def std(self, ddof: int = 1) -> Expr:
        """
        Compute the std of the values of the sub-arrays.

        .. engine-support:: in-memory, streaming, distributed

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     data={"a": [[1, 2], [4, 3]]},
        ...     schema={"a": pl.Array(pl.Int64, 2)},
        ... )
        >>> df.select(pl.col("a").arr.std())

View on GitHub (pinned to fe841f959e)