[DOC-12247] Explain ordering within array aggregates

src/snowflake/snowpark/functions.py

@@ -7005,6 +7005,16 @@ def array_agg(
     """Returns the input values, pivoted into an ARRAY. If the input is empty, an empty
     ARRAY is returned.
 
+    Element order is unpredictable unless you specify :meth:`Column.within_group`
+    on the aggregate expression. Sorting the result DataFrame orders result
+    rows, not the elements inside each array. This also applies to the
+    ``collect_list`` alias. When ``is_distinct=True``, the ordering expression
+    must refer to the same column as the aggregate input.
+
+    For example, this expression orders elements within each array by ``a``::
+
+        >>> ordered_values = array_agg("a").within_group("a")
+
     Example::
         >>> df = session.create_dataframe([[1], [2], [3], [1]], schema=["a"])
         >>> df.select(array_agg("a", True).within_group("a").alias("result")).show()