feat: Improve error message on unsupported SQL subquery comparisons (#25135)

Author: alexander-beedie

crates/polars-sql/src/sql_expr.rs

@@ -469,6 +469,18 @@ impl SQLExprVisitor<'_> {
         op: &SQLBinaryOperator,
         right: &SQLExpr,
     ) -> PolarsResult<Expr> {
+        // check for (unsupported) scalar subquery comparisons
+        if matches!(left, SQLExpr::Subquery(_)) || matches!(right, SQLExpr::Subquery(_)) {
+            let (suggestion, str_op) = match op {
+                SQLBinaryOperator::NotEq => ("; use 'NOT IN' instead", "!=".to_string()),
+                SQLBinaryOperator::Eq => ("; use 'IN' instead", format!("{op}")),
+                _ => ("", format!("{op}")),
+            };
+            polars_bail!(
+                SQLSyntax: "subquery comparisons with '{str_op}' are not supported{suggestion}"
+            );
+        }
+
         // need special handling for interval offsets and comparisons
         let (lhs, mut rhs) = match (left, op, right) {
             (_, SQLBinaryOperator::Minus, SQLExpr::Interval(v)) => {

py-polars/tests/unit/sql/test_subqueries.py

@@ -158,3 +158,28 @@ def test_subquery_20732() -> None:
     )
     res = pl.sql("SELECT * FROM lf WHERE id IN (SELECT MAX(id) FROM lf)", eager=True)
     assert res.to_dict(as_series=False) == {"id": [2], "s": ["b"]}
+
+
+def test_unsupported_subquery_comparisons() -> None:
+    """Test that using = with a subquery gives a helpful error message."""
+    df = pl.DataFrame({"value": [2000, 2000]})  # noqa: F841
+
+    for op, suggestion in (("=", "IN"), ("!=", "NOT IN")):
+        with pytest.raises(
+            SQLSyntaxError,
+            match=rf"subquery comparisons with '{op}' are not supported; use '{suggestion}' instead",
+        ):
+            pl.sql(f"SELECT * FROM df WHERE value {op} (SELECT MAX(e) FROM df)")
+
+    for op in ("<", "<=", ">", ">="):
+        with pytest.raises(
+            SQLSyntaxError,
+            match=rf"subquery comparisons with '{op}' are not supported",
+        ):
+            pl.sql(f"SELECT * FROM df WHERE (SELECT MAX(e) FROM df) {op} value")
+
+        with pytest.raises(
+            SQLSyntaxError,
+            match=rf"subquery comparisons with '{op}' are not supported",
+        ):
+            pl.sql(f"SELECT * FROM df WHERE value {op} (SELECT MAX(value) FROM df)")