Document UDAF list-valued scalar returns

Add documented list-valued scalar returns for UDAF
accumulators, including an example with pa.scalar and a note
about unsupported pyarrow.Array returns from evaluate().
Also, introduce a UDAF FAQ entry detailing list-returning
patterns and required return_type/state_type definitions.

Author: kosiew

docs/source/user-guide/common-operations/udf-and-udfa.rst

@@ -149,6 +149,17 @@ also see how the inputs to ``update`` and ``merge`` differ.
 
     df.aggregate([], [my_udaf(col("a"), col("b")).alias("col_diff")])
 
+FAQ
+^^^
+
+**How do I return a list from a UDAF?**
+Use a list-valued scalar and declare list types for both the return and state
+definitions. Returning a ``pyarrow.Array`` from ``evaluate`` is not supported
+unless you convert it to a list scalar. For example, in ``evaluate`` you can
+return ``pa.scalar([...], type=pa.list_(pa.timestamp("ms")))`` and register the
+UDAF with ``return_type=pa.list_(pa.timestamp("ms"))`` and
+``state_type=[pa.list_(pa.timestamp("ms"))]``.
+
 Window Functions
 ----------------
 

python/datafusion/user_defined.py

@@ -282,7 +282,21 @@ def merge(self, states: list[pa.Array]) -> None:
 
     @abstractmethod
     def evaluate(self) -> pa.Scalar:
-        """Return the resultant value."""
+        """Return the resultant value.
+
+        If you need to return a list, wrap it in a scalar with the correct
+        list type, for example::
+
+            import pyarrow as pa
+
+            return pa.scalar(
+                [pa.scalar("2024-01-01T00:00:00Z")],
+                type=pa.list_(pa.timestamp("ms")),
+            )
+
+        Returning a ``pyarrow.Array`` from ``evaluate`` is not supported unless
+        you explicitly convert it to a list-valued scalar.
+        """
 
 
 class AggregateUDFExportable(Protocol):