[SPARK-55749][SQL][DOC] Clarify array_contains null-handling in the docs and example

python/pyspark/sql/functions/builtin.py

@@ -19892,9 +19892,9 @@ def array(
 @_try_remote_functions
 def array_contains(col: "ColumnOrName", value: Any) -> Column:
     """
-    Collection function: This function returns a boolean indicating whether the array
-    contains the given value, returning null if the array is null, true if the array
-    contains the given value, and false otherwise.
+    Collection function: Returns true if the array contains the value, false if not. Returns
+    null if the array or value is null, or if the value is not found and the array contains a
+    null element.
 
     .. versionadded:: 1.5.0
 
@@ -19972,6 +19972,17 @@ def array_contains(col: "ColumnOrName", value: Any) -> Column:
     +-----------------------+
     |                   true|
     +-----------------------+
+
+    Example 5: Value absent from an array that contains a null element returns NULL.
+
+    >>> from pyspark.sql import functions as sf
+    >>> df = spark.createDataFrame([(["a", None, "c"],)], ['data'])
+    >>> df.select(sf.array_contains(df.data, "b")).show()
+    +-----------------------+
+    |array_contains(data, b)|
+    +-----------------------+
+    |                   NULL|
+    +-----------------------+
     """
     return _invoke_function_over_columns("array_contains", col, lit(value))
 

sql/api/src/main/scala/org/apache/spark/sql/functions.scala

@@ -12933,7 +12933,8 @@ object functions {
   //////////////////////////////////////////////////////////////////////////////////////////////
 
   /**
-   * Returns null if the array is null, true if the array contains `value`, and false otherwise.
+   * Returns true if the array contains `value`, false if not. Returns null if the array or
+   * `value` is null, or if `value` is not found and the array contains a null element.
    * @param column
    *   the target column containing the arrays. A column that evaluates to an array.
    * @param value

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/collectionOperations.scala

@@ -1483,8 +1483,9 @@ case class Reverse(child: Expression)
 /**
  * Checks if the array (left) has the element (right)
  */
+// scalastyle:off line.size.limit
 @ExpressionDescription(
-  usage = "_FUNC_(array, value) - Returns true if the array contains the value.",
+  usage = "_FUNC_(array, value) - Returns true if the array contains the value, false if not. Returns null if the array or value is null, or if the value is not found and the array contains a null element.",
   arguments = """
     Arguments:
       * array - The array to search.
@@ -1496,9 +1497,12 @@ case class Reverse(child: Expression)
     Examples:
       > SELECT _FUNC_(array(1, 2, 3), 2);
        true
+      > SELECT _FUNC_(array(1, NULL, 3), 2);
+       NULL
   """,
   group = "array_funcs",
   since = "1.5.0")
+// scalastyle:on line.size.limit
 case class ArrayContains(left: Expression, right: Expression)
   extends BinaryExpression with ImplicitCastInputTypes with Predicate
   with QueryErrorsBase {