docs: show array_distinct keeping first-seen order (#25930)

## Which issue does this PR close?

- None; documentation fix.

## Rationale for this change

The `array_distinct` example says `select array_distinct([1, 3, 2, 3, 1,
2, 4])` returns `[1, 2, 3, 4]`. It returns `[1, 3, 2, 4]`: #20364
changed it to keep elements in the order they first appear, matching
`array_union` and `array_intersect`, and the example was not updated.

## What changes are included in this PR?

The `#[user_doc]` example and description in `set_ops.rs`, the matching
code comment, and `scalar_functions.md` regenerated with
`./dev/update_function_docs.sh`. Also a sqllogictest case for the order,
since every existing `array_distinct` case used input whose sorted and
first-seen orders coincide.

## What is the testing strategy for this PR?

Ran the example against `datafusion-cli` built from `main`. The new case
in `array_distinct.slt` passes; `cargo fmt --check`, `cargo clippy -p
datafusion-functions-nested --all-targets -- -D warnings` and
`./ci/scripts/doc_prettier_check.sh` pass.

## Are there any user-facing changes?

Documentation and a test only.

Generated with Claude Code (claude-opus-5-5); I checked the output
above.

Author: rawsun007

datafusion/functions-nested/src/set_ops.rs

@@ -234,15 +234,15 @@ impl ScalarUDFImpl for ArrayIntersect {
 
 #[user_doc(
     doc_section(label = "Array Functions"),
-    description = "Returns distinct values from the array after removing duplicates.",
+    description = "Returns distinct values from the array after removing duplicates, in the order they first appear.",
     syntax_example = "array_distinct(array)",
     sql_example = r#"```sql
 > select array_distinct([1, 3, 2, 3, 1, 2, 4]);
-+---------------------------------+
-| array_distinct(List([1,2,3,4])) |
-+---------------------------------+
-| [1, 2, 3, 4]                    |
-+---------------------------------+
++---------------------------------------+
+| array_distinct(List([1,3,2,3,1,2,4])) |
++---------------------------------------+
+| [1, 3, 2, 4]                          |
++---------------------------------------+
 ```"#,
     argument(
         name = "array",
@@ -297,7 +297,7 @@ impl ScalarUDFImpl for ArrayDistinct {
 }
 
 /// array_distinct SQL function
-/// example: from list [1, 3, 2, 3, 1, 2, 4] to [1, 2, 3, 4]
+/// example: from list [1, 3, 2, 3, 1, 2, 4] to [1, 3, 2, 4]
 fn array_distinct_inner(args: &[ArrayRef]) -> Result<ArrayRef> {
     let [array] = take_function_args("array_distinct", args)?;
     match array.data_type() {

datafusion/sqllogictest/test_files/array/array_distinct.slt

@@ -45,6 +45,12 @@ select array_distinct(a) from values ([1, 2, 3]), (null), ([1, 3, 1]) as X(a);
 NULL
 [1, 3]
 
+# elements keep the order they first appear in
+query ?
+select array_distinct([1, 3, 2, 3, 1, 2, 4]);
+----
+[1, 3, 2, 4]
+
 query ?
 select array_distinct(arrow_cast(null, 'LargeList(Int64)'));
 ----

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

@@ -3644,7 +3644,7 @@ array_distance(array1, array2)
 
 ### `array_distinct`
 
-Returns distinct values from the array after removing duplicates.
+Returns distinct values from the array after removing duplicates, in the order they first appear.
 
 ```sql
 array_distinct(array)
@@ -3658,11 +3658,11 @@ array_distinct(array)
 
 ```sql
 > select array_distinct([1, 3, 2, 3, 1, 2, 4]);
-+---------------------------------+
-| array_distinct(List([1,2,3,4])) |
-+---------------------------------+
-| [1, 2, 3, 4]                    |
-+---------------------------------+
++---------------------------------------+
+| array_distinct(List([1,3,2,3,1,2,4])) |
++---------------------------------------+
+| [1, 3, 2, 4]                          |
++---------------------------------------+
 ```
 
 #### Aliases