[SPARK-58061][SQL] Add variant_array_append expression

[bojana-db]

What changes were proposed in this pull request?

Adds the SQL function variant_array_append(v, path, val), which appends a value to the array in a Variant value at a single JSONPath location.

Details:

• Appends val as a new last element of the array at path (e.g. $.a, $[0], $.a[1]); the root path $ targets the whole Variant, which must itself be an array;
• A missing key or out-of-range array index along the path leaves v unchanged;
• Any NULL argument returns NULL;
• The value may be any expression castable to variant (primitives, arrays, or another variant; structs and maps are rejected). An array value is appended as a single nested element rather than flattened, and a variant null appends a null element;
• VARIANT_PATH_TYPE_MISMATCH is raised when a path segment is applied to a value of an incompatible type or when the target is not an array; a malformed path is rejected with INVALID_VARIANT_PATH, and results exceeding the size limit raise VARIANT_SIZE_LIMIT.

Why are the changes needed?

Without variant_array_append, appending to an array in a variant means converting it to another datatype (e.g. array), mutating, and converting back.

Does this PR introduce any user-facing change?

Yes, a new SQL function (and Scala/Python functions API).

How was this patch tested?

Unit tests.

Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Code with Claude Opus 4.8