depr(api): deprecate ibis.where in favor of ibis.ifelse

ibis/backends/clickhouse/tests/test_select.py

@@ -268,8 +268,8 @@ def test_where_with_between(con, alltypes, snapshot):
     con.execute(expr)
 
 
-def test_where_use_if(con, alltypes, snapshot):
-    expr = ibis.where(alltypes.float_col > 0, alltypes.int_col, alltypes.bigint_col)
+def test_ifelse_use_if(con, alltypes, snapshot):
+    expr = ibis.ifelse(alltypes.float_col > 0, alltypes.int_col, alltypes.bigint_col)
 
     result = expr.compile()
     snapshot.assert_match(result, "out.sql")

ibis/backends/dask/tests/execution/test_operations.py

@@ -772,9 +772,9 @@ def test_left_binary_op_gb(t, df, op, argfunc):
         param(lambda _: None, id="none"),
     ],
 )
-def test_where_series(t, df, left_f, right_f):
+def test_ifelse_series(t, df, left_f, right_f):
     col_expr = t["plain_int64"]
-    result = ibis.where(
+    result = ibis.ifelse(
         col_expr > col_expr.mean(), left_f(col_expr), right_f(col_expr)
     ).execute()
 
@@ -795,16 +795,16 @@ def test_where_series(t, df, left_f, right_f):
         (False, lambda df: dd.from_array(np.repeat(3.0, len(df)))),
     ],
 )
-def test_where_scalar(t, df, cond, expected_func):
-    expr = ibis.where(cond, t["plain_int64"], 3.0)
+def test_ifelse_scalar(t, df, cond, expected_func):
+    expr = ibis.ifelse(cond, t["plain_int64"], 3.0)
     result = expr.compile()
     expected = expected_func(df)
     tm.assert_series_equal(result.compute(), expected.compute(), check_index=False)
 
 
-def test_where_long(batting, batting_df):
+def test_ifelse_long(batting, batting_df):
     col_expr = batting["AB"]
-    result = ibis.where(col_expr > col_expr.mean(), col_expr, 0.0).compile()
+    result = ibis.ifelse(col_expr > col_expr.mean(), col_expr, 0.0).compile()
 
     series = batting_df["AB"]
     expected = series.where(series > series.mean(), other=0.0)

ibis/backends/impala/tests/test_case_exprs.py

@@ -52,8 +52,8 @@ def test_search_case(search_case, snapshot):
     snapshot.assert_match(result, "out.sql")
 
 
-def test_where_use_if(table, snapshot):
-    expr = ibis.where(table.f > 0, table.e, table.a)
+def test_ifelse_use_if(table, snapshot):
+    expr = ibis.ifelse(table.f > 0, table.e, table.a)
     assert isinstance(expr, ir.FloatingValue)
 
     result = translate(expr)

ibis/backends/impala/tests/test_exprs.py

@@ -387,7 +387,7 @@ def test_decimal_timestamp_builtins(con):
         dc * 2,
         dc**2,
         dc.cast("double"),
-        api.where(table.l_discount > 0, dc * table.l_discount, api.NA),
+        api.ifelse(table.l_discount > 0, dc * table.l_discount, api.NA),
         dc.fillna(0),
         ts < (ibis.now() + ibis.interval(months=3)),
         ts < (ibis.timestamp("2005-01-01") + ibis.interval(months=3)),

ibis/backends/pandas/tests/execution/test_operations.py

@@ -571,9 +571,9 @@ def test_left_binary_op_gb(t, df, opname, argfunc):
         param(lambda _: None, id="none"),
     ],
 )
-def test_where_series(t, df, left_f, right_f):
+def test_ifelse_series(t, df, left_f, right_f):
     col_expr = t["plain_int64"]
-    result = ibis.where(
+    result = ibis.ifelse(
         col_expr > col_expr.mean(), left_f(col_expr), right_f(col_expr)
     ).execute()
 
@@ -598,16 +598,16 @@ def test_where_series(t, df, left_f, right_f):
         param(False, lambda df: pd.Series(np.repeat(3.0, len(df))), id="false"),
     ],
 )
-def test_where_scalar(t, df, cond, expected_func):
-    expr = ibis.where(cond, t["plain_int64"], 3.0)
+def test_ifelse_scalar(t, df, cond, expected_func):
+    expr = ibis.ifelse(cond, t["plain_int64"], 3.0)
     result = expr.execute()
     expected = expected_func(df)
     tm.assert_series_equal(result, expected)
 
 
-def test_where_long(batting, batting_df):
+def test_ifelse_long(batting, batting_df):
     col_expr = batting["AB"]
-    result = ibis.where(col_expr > col_expr.mean(), col_expr, 0.0).execute()
+    result = ibis.ifelse(col_expr > col_expr.mean(), col_expr, 0.0).execute()
 
     series = batting_df["AB"]
     expected = series.where(series > series.mean(), other=0.0).astype("float64")

ibis/backends/tests/test_generic.py

@@ -698,12 +698,16 @@ def test_zeroifnull_column(backend, alltypes, df):
 
 
 @pytest.mark.notimpl(["datafusion"])
-def test_where_select(backend, alltypes, df):
+def test_ifelse_select(backend, alltypes, df):
     table = alltypes
     table = table.select(
         [
             "int_col",
-            (ibis.where(table["int_col"] == 0, 42, -1).cast("int64").name("where_col")),
+            (
+                ibis.ifelse(table["int_col"] == 0, 42, -1)
+                .cast("int64")
+                .name("where_col")
+            ),
         ]
     )
 
@@ -718,8 +722,8 @@ def test_where_select(backend, alltypes, df):
 
 
 @pytest.mark.notimpl(["datafusion"])
-def test_where_column(backend, alltypes, df):
-    expr = ibis.where(alltypes["int_col"] == 0, 42, -1).cast("int64").name("where_col")
+def test_ifelse_column(backend, alltypes, df):
+    expr = ibis.ifelse(alltypes["int_col"] == 0, 42, -1).cast("int64").name("where_col")
     result = expr.execute()
 
     expected = pd.Series(

ibis/expr/api.py

@@ -1808,8 +1808,29 @@ def watermark(time_col: str, allowed_delay: ir.IntervalScalar) -> Watermark:
 │ no                            │
 └───────────────────────────────┘
 """
-# Deprecated, use ifelse instead: https://github.com/ibis-project/ibis/issues/7147
-where = _deferred(ir.BooleanValue.ifelse)
+
+
+@util.deprecated(instead="use `ibis.ifelse` instead", as_of="7.0")
+def where(cond, true_expr, false_expr) -> ir.Value:
+    """Construct a ternary conditional expression.
+
+    Parameters
+    ----------
+    cond : ir.Value
+        Boolean conditional expression
+    true_expr : ir.Value
+        Expression to return if `cond` evaluates to `True`
+    false_expr : ir.Value
+        Expression to return if `cond` evaluates to `False` or `NULL`
+
+    Returns
+    -------
+    Value : ir.Value
+        The value of `true_expr` if `arg` is `True` else `false_expr`
+    """
+    return ifelse(cond, true_expr, false_expr)
+
+
 coalesce = _deferred(ir.Value.coalesce)
 greatest = _deferred(ir.Value.greatest)
 least = _deferred(ir.Value.least)

ibis/tests/expr/test_decimal.py

@@ -8,7 +8,6 @@
 import ibis.expr.datatypes as dt
 import ibis.expr.types as ir
 from ibis.common.annotations import ValidationError
-from ibis.expr import api
 
 
 def test_type_metadata(lineitem):
@@ -19,7 +18,7 @@ def test_type_metadata(lineitem):
 
 
 def test_cast_scalar_to_decimal():
-    val = api.literal("1.2345")
+    val = ibis.literal("1.2345")
 
     casted = val.cast("decimal(15,5)")
     assert isinstance(casted, ir.DecimalScalar)
@@ -90,19 +89,19 @@ def test_decimal_aggregate_function_type(lineitem, func):
     assert result.type() == col.type()
 
 
-def test_where(lineitem):
+def test_ifelse(lineitem):
     table = lineitem
 
     q = table.l_quantity
-    expr = api.where(table.l_discount > 0, q * table.l_discount, api.null())
+    expr = ibis.ifelse(table.l_discount > 0, q * table.l_discount, ibis.null())
 
     assert isinstance(expr, ir.DecimalColumn)
 
-    expr = api.where(table.l_discount > 0, (q * table.l_discount).sum(), api.null())
+    expr = ibis.ifelse(table.l_discount > 0, (q * table.l_discount).sum(), ibis.null())
     assert isinstance(expr, ir.DecimalColumn)
 
-    expr = api.where(
-        table.l_discount.sum() > 0, (q * table.l_discount).sum(), api.null()
+    expr = ibis.ifelse(
+        table.l_discount.sum() > 0, (q * table.l_discount).sum(), ibis.null()
     )
     assert isinstance(expr, ir.DecimalScalar)
 

ibis/tests/expr/test_value_exprs.py

@@ -1469,14 +1469,14 @@ def test_deferred_r_ops(op_name, expected_left, expected_right):
 @pytest.mark.parametrize(
     ("expr_fn", "expected_type"),
     [
-        (lambda t: ibis.where(t.a == 1, t.b, ibis.NA), dt.string),
-        (lambda t: ibis.where(t.a == 1, t.b, t.a.cast("string")), dt.string),
+        (lambda t: ibis.ifelse(t.a == 1, t.b, ibis.NA), dt.string),
+        (lambda t: ibis.ifelse(t.a == 1, t.b, t.a.cast("string")), dt.string),
         (
-            lambda t: ibis.where(t.a == 1, t.b, t.a.cast("!string")),
+            lambda t: ibis.ifelse(t.a == 1, t.b, t.a.cast("!string")),
             dt.string.copy(nullable=False),
         ),
-        (lambda _: ibis.where(True, ibis.NA, ibis.NA), dt.null),
-        (lambda _: ibis.where(False, ibis.NA, ibis.NA), dt.null),
+        (lambda _: ibis.ifelse(True, ibis.NA, ibis.NA), dt.null),
+        (lambda _: ibis.ifelse(False, ibis.NA, ibis.NA), dt.null),
     ],
 )
 def test_non_null_with_null_precedence(expr_fn, expected_type):
@@ -1572,14 +1572,11 @@ def equal(x, y):
         param(ibis.coalesce, dt.timestamp, id="coalesce"),
         param(ibis.greatest, dt.timestamp, id="greatest"),
         param(ibis.least, dt.timestamp, id="least"),
-    ]
-    + [
         param(
-            lambda ts, func=func: func(ts.notnull(), ts, ts - ibis.interval(days=1)),
+            lambda ts: ibis.ifelse(ts.notnull(), ts, ts - ibis.interval(days=1)),
             dt.timestamp,
-            id=func.__name__,
-        )
-        for func in (ibis.ifelse, ibis.where)
+            id="ifelse",
+        ),
     ],
 )
 def test_deferred_function_call(func, expected_type):