Add missing conditional functions (#1464)

* Add missing conditional functions: greatest, least, nvl2, ifnull (#1449)

Expose four conditional functions from upstream DataFusion that were
not yet available in the Python bindings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add unit tests for greatest, least, nvl2, and ifnull functions

Tests cover multiple data types (integers, strings), null handling
(all-null, partial-null), multiple arguments, and ifnull/nvl equivalence.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Use standard alias docstring pattern for ifnull

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* remove unused df fixture and fix parameter shadowing

* Refactor conditional function tests into parametrized test suite

Replace separate test functions for coalesce, greatest, least, nvl,
nvl2, ifnull with a single parametrized test using a shared fixture.
Adds coverage for nvl, nullif (previously untested), datetime and
boolean types, literal fallbacks, and variadic calls.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timsaucer

crates/core/src/functions.rs

@@ -494,6 +494,8 @@ expr_fn!(length, string);
 expr_fn!(char_length, string);
 expr_fn!(chr, arg, "Returns the character with the given code.");
 expr_fn_vec!(coalesce);
+expr_fn_vec!(greatest);
+expr_fn_vec!(least);
 expr_fn!(
     contains,
     string search_str,
@@ -548,6 +550,11 @@ expr_fn!(
     x y,
     "Returns x if x is not NULL otherwise returns y."
 );
+expr_fn!(
+    nvl2,
+    x y z,
+    "Returns y if x is not NULL; otherwise returns z."
+);
 expr_fn!(nullif, arg_1 arg_2);
 expr_fn!(
     octet_length,
@@ -989,13 +996,15 @@ pub(crate) fn init_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(floor))?;
     m.add_wrapped(wrap_pyfunction!(from_unixtime))?;
     m.add_wrapped(wrap_pyfunction!(gcd))?;
+    m.add_wrapped(wrap_pyfunction!(greatest))?;
     // m.add_wrapped(wrap_pyfunction!(grouping))?;
     m.add_wrapped(wrap_pyfunction!(in_list))?;
     m.add_wrapped(wrap_pyfunction!(initcap))?;
     m.add_wrapped(wrap_pyfunction!(isnan))?;
     m.add_wrapped(wrap_pyfunction!(iszero))?;
     m.add_wrapped(wrap_pyfunction!(levenshtein))?;
     m.add_wrapped(wrap_pyfunction!(lcm))?;
+    m.add_wrapped(wrap_pyfunction!(least))?;
     m.add_wrapped(wrap_pyfunction!(left))?;
     m.add_wrapped(wrap_pyfunction!(length))?;
     m.add_wrapped(wrap_pyfunction!(ln))?;
@@ -1013,6 +1022,7 @@ pub(crate) fn init_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(named_struct))?;
     m.add_wrapped(wrap_pyfunction!(nanvl))?;
     m.add_wrapped(wrap_pyfunction!(nvl))?;
+    m.add_wrapped(wrap_pyfunction!(nvl2))?;
     m.add_wrapped(wrap_pyfunction!(now))?;
     m.add_wrapped(wrap_pyfunction!(nullif))?;
     m.add_wrapped(wrap_pyfunction!(octet_length))?;

python/datafusion/functions.py

@@ -152,6 +152,8 @@
     "floor",
     "from_unixtime",
     "gcd",
+    "greatest",
+    "ifnull",
     "in_list",
     "initcap",
     "isnan",
@@ -160,6 +162,7 @@
     "last_value",
     "lcm",
     "lead",
+    "least",
     "left",
     "length",
     "levenshtein",
@@ -216,6 +219,7 @@
     "ntile",
     "nullif",
     "nvl",
+    "nvl2",
     "octet_length",
     "order_by",
     "overlay",
@@ -1045,6 +1049,34 @@ def gcd(x: Expr, y: Expr) -> Expr:
     return Expr(f.gcd(x.expr, y.expr))
 
 
+def greatest(*args: Expr) -> Expr:
+    """Returns the greatest value from a list of expressions.
+
+    Returns NULL if all expressions are NULL.
+
+    Examples:
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.from_pydict({"a": [1, 3], "b": [2, 1]})
+        >>> result = df.select(
+        ...     dfn.functions.greatest(dfn.col("a"), dfn.col("b")).alias("greatest"))
+        >>> result.collect_column("greatest")[0].as_py()
+        2
+        >>> result.collect_column("greatest")[1].as_py()
+        3
+    """
+    exprs = [arg.expr for arg in args]
+    return Expr(f.greatest(*exprs))
+
+
+def ifnull(x: Expr, y: Expr) -> Expr:
+    """Returns ``x`` if ``x`` is not NULL. Otherwise returns ``y``.
+
+    See Also:
+        This is an alias for :py:func:`nvl`.
+    """
+    return nvl(x, y)
+
+
 def initcap(string: Expr) -> Expr:
     """Set the initial letter of each word to capital.
 
@@ -1098,6 +1130,25 @@ def lcm(x: Expr, y: Expr) -> Expr:
     return Expr(f.lcm(x.expr, y.expr))
 
 
+def least(*args: Expr) -> Expr:
+    """Returns the least value from a list of expressions.
+
+    Returns NULL if all expressions are NULL.
+
+    Examples:
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.from_pydict({"a": [1, 3], "b": [2, 1]})
+        >>> result = df.select(
+        ...     dfn.functions.least(dfn.col("a"), dfn.col("b")).alias("least"))
+        >>> result.collect_column("least")[0].as_py()
+        1
+        >>> result.collect_column("least")[1].as_py()
+        1
+    """
+    exprs = [arg.expr for arg in args]
+    return Expr(f.least(*exprs))
+
+
 def left(string: Expr, n: Expr) -> Expr:
     """Returns the first ``n`` characters in the ``string``.
 
@@ -1282,6 +1333,24 @@ def nvl(x: Expr, y: Expr) -> Expr:
     return Expr(f.nvl(x.expr, y.expr))
 
 
+def nvl2(x: Expr, y: Expr, z: Expr) -> Expr:
+    """Returns ``y`` if ``x`` is not NULL. Otherwise returns ``z``.
+
+    Examples:
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.from_pydict({"a": [None, 1], "b": [10, 20], "c": [30, 40]})
+        >>> result = df.select(
+        ...     dfn.functions.nvl2(
+        ...         dfn.col("a"), dfn.col("b"), dfn.col("c")).alias("nvl2")
+        ... )
+        >>> result.collect_column("nvl2")[0].as_py()
+        30
+        >>> result.collect_column("nvl2")[1].as_py()
+        20
+    """
+    return Expr(f.nvl2(x.expr, y.expr, z.expr))
+
+
 def octet_length(arg: Expr) -> Expr:
     """Returns the number of bytes of a string.