Document that a volatile coalesce or nvl argument is evaluated eagerly

`nvl`'s user documentation promised that the second argument "is not
evaluated". That stops being true once the volatility guard skips the
`CASE` rewrite, because `ScalarFunctionExpr::evaluate` evaluates every
child before calling `invoke_with_args`, and nothing in the physical layer
defers an argument. `coalesce` promised nothing either way, but the new
behaviour is worth stating there too.

`scalar_functions.md` is generated from these `#[user_doc]` attributes by
`dev/update_function_docs.sh`, and CI fails on drift, so the regenerated
file is included here.

Also adds a 56.0.0 upgrade-guide entry, as `api-health.md` asks for
user-visible SQL changes, modelled on 54.0.0's evaluation-order section
and pointing at the same `CASE` workaround.

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

Author: DeviousCardi

datafusion/functions/src/core/coalesce.rs

@@ -32,7 +32,7 @@ use itertools::Itertools;
 
 #[user_doc(
     doc_section(label = "Conditional Functions"),
-    description = "Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values.",
+    description = "Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. Arguments after the first non-_null_ one are normally not evaluated, but when any argument other than the last is volatile every argument is evaluated, so that each is evaluated exactly once. This function is often used to substitute a default value for _null_ values.",
     syntax_example = "coalesce(expression1[, ..., expression_n])",
     sql_example = r#"```sql
 > select coalesce(null, null, 'datafusion');

datafusion/functions/src/core/nvl.rs

@@ -27,7 +27,7 @@ use datafusion_macros::user_doc;
 
 #[user_doc(
     doc_section(label = "Conditional Functions"),
-    description = "Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_ and _expression2_ is not evaluated. This function can be used to substitute a default value for NULL values.",
+    description = "Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_. _expression2_ is normally not evaluated, but when _expression1_ is volatile both arguments are evaluated, so that _expression1_ is evaluated exactly once. This function can be used to substitute a default value for NULL values.",
     syntax_example = "nvl(expression1, expression2)",
     sql_example = r#"```sql
 > select nvl(null, 'a');

docs/source/library-user-guide/upgrading/56.0.0.md

@@ -577,3 +577,29 @@ Wire compatibility is directional:
 - A 55.0 reader must not consume an alias-preserving 56.0 MERGE payload. It
   ignores the unknown field but cannot preserve the qualifier required by the
   expressions, which can cause resolution failure or incorrect rebinding.
+### A volatile `coalesce` or `nvl` argument is now evaluated eagerly
+
+`coalesce` and `nvl` are normally rewritten to `CASE WHEN a IS NOT NULL THEN a
+ELSE b END`, which names every argument but the last one twice. For a volatile
+argument those two mentions were two independent draws, so
+`coalesce(nullif(floor(random() * 2), 0), -1)` could return `NULL` — a value a
+single evaluation can never produce — or fail at run time with
+`Column 'c' is declared as non-nullable but contains null values`.
+
+The rewrite is now skipped when any argument other than the last is volatile,
+and the call is evaluated by a kernel that reads each argument exactly once.
+That fixes the wrong results, but it also means the remaining arguments are
+evaluated rather than skipped:
+
+```sql
+-- previously returned rows, because `y / x` was never evaluated;
+-- now raises `Divide by zero error`
+SELECT coalesce(random(), y / x) FROM t;
+```
+
+Only calls that contain a volatile argument before the last one are affected.
+A volatile *last* argument still takes the lazy rewrite, and non-volatile
+`coalesce` and `nvl` are unchanged.
+
+To force conditional evaluation, rewrite using `CASE`, which has standardized
+short-circuit semantics.

docs/source/user-guide/sql/scalar_functions.md

@@ -962,7 +962,7 @@ trunc(numeric_expression[, decimal_places])
 
 ### `coalesce`
 
-Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values.
+Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. Arguments after the first non-_null_ one are normally not evaluated, but when any argument other than the last is volatile every argument is evaluated, so that each is evaluated exactly once. This function is often used to substitute a default value for _null_ values.
 
 ```sql
 coalesce(expression1[, ..., expression_n])
@@ -1066,7 +1066,7 @@ nullif(expression1, expression2)
 
 ### `nvl`
 
-Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_ and _expression2_ is not evaluated. This function can be used to substitute a default value for NULL values.
+Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_. _expression2_ is normally not evaluated, but when _expression1_ is volatile both arguments are evaluated, so that _expression1_ is evaluated exactly once. This function can be used to substitute a default value for NULL values.
 
 ```sql
 nvl(expression1, expression2)