[SPARK-58085][SQL][DOCS] Document accepted input types for built-in functions in the SQL function reference

[HyukjinKwon]

What changes were proposed in this pull request?

This documents, for every built-in function argument, which input types it accepts, in the SQL
@ExpressionDescriptionarguments blocks (rendered on the SQL functions reference page), using a
numeric umbrella (a numeric / a numeric or interval) where numeric subtypes cast in, and
timestamp for TIMESTAMP_NTZ in type phrases.

Subtask of SPARK-57999, split out from #57079 for reviewability. This PR covers only
the SQL surface.

Why are the changes needed?

The SQL function reference previously had no per-argument type information for most built-in
functions. This fills that gap.

Does this PR introduce any user-facing change?

Yes, documentation only. No behavioral or API change.

How was this patch tested?

Existing ExpressionInfoSuite and the SPARK-32870 argument-block-format tests pass. Types were
derived from and verified against the analyzer's accept/reject behavior and each expression's
inputTypes / checkInputDataTypes.

Co-authored-by: Isaac

[dongjoon-hyun]

This PR seems to break the CI at describe function unit test.

2026-07-10T10:04:14.2381680Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m- describe function *** FAILED *** (115 milliseconds)�[0m�[0m
2026-07-10T10:04:14.2390933Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m Results do not match for query:�[0m�[0m
2026-07-10T10:04:14.2436987Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m Timezone: sun.util.calendar.ZoneInfo[id="America/Los_Angeles",offset=-28800000,dstSavings=3600000,useDaylight=true,transitions=311,lastRule=java.util.SimpleTimeZone[id=America/Los_Angeles,offset=-28800000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]]�[0m�[0m
2026-07-10T10:04:14.2449058Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m Timezone Env: �[0m�[0m
2026-07-10T10:04:14.2450581Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m �[0m
2026-07-10T10:04:14.2451468Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m == Parsed Logical Plan ==�[0m�[0m
2026-07-10T10:04:14.2452454Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m 'DescribeFunction true�[0m�[0m
2026-07-10T10:04:14.2453548Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m +- 'UnresolvedFunctionName [^], DESCRIBE FUNCTION�[0m�[0m
2026-07-10T10:04:14.2454477Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m �[0m
2026-07-10T10:04:14.2455282Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m == Analyzed Logical Plan ==�[0m�[0m
2026-07-10T10:04:14.2456358Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m function_desc: string�[0m�[0m
2026-07-10T10:04:14.2458012Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m DescribeFunctionCommand org.apache.spark.sql.catalyst.expressions.ExpressionInfo@13541f24, true�[0m�[0m
2026-07-10T10:04:14.2459987Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m �[0m
2026-07-10T10:04:14.2460987Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m == Optimized Logical Plan ==�[0m�[0m
2026-07-10T10:04:14.2463845Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m CommandResult [function_desc#1140035], Execute DescribeFunctionCommand, [[Function: ^], [Class: org.apache.spark.sql.catalyst.expressions.BitwiseXor], [Usage: expr1 ^ expr2 - Returns the result of bitwise exclusive OR of `expr1` and `expr2`.], [Extended Usage:�[0m�[0m
2026-07-10T10:04:14.2466350Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m Arguments:�[0m�[0m
2026-07-10T10:04:14.2467543Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m * expr1 - The first operand of the bitwise exclusive OR.�[0m�[0m
2026-07-10T10:04:14.2468867Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m An expression that evaluates to an integral.�[0m�[0m
2026-07-10T10:04:14.2470447Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m * expr2 - The second operand of the bitwise exclusive OR.�[0m�[0m
2026-07-10T10:04:14.2471784Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m An expression that evaluates to an integral.�[0m�[0m
2026-07-10T10:04:14.2472804Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m �[0m
2026-07-10T10:04:14.2473892Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m Examples:�[0m�[0m
2026-07-10T10:04:14.2474855Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m > SELECT 3 ^ 5;�[0m�[0m
2026-07-10T10:04:14.2475761Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m 6�[0m�[0m
2026-07-10T10:04:14.2476546Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m �[0m
2026-07-10T10:04:14.2477361Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m Since: 1.4.0�[0m�[0m
2026-07-10T10:04:14.2478191Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m ]]�[0m�[0m
2026-07-10T10:04:14.2479891Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m�[31m +- DescribeFunctionCommand org.apache.spark.sql.catalyst.expressions.ExpressionInfo@13541f24, true�[0m�[0m
2026-07-10T10:04:14.2481555Z �[0m[�[0m�[0minfo�[0m] �[0m�[0m �[0m

[MaxGekk]

0 blocking, 2 non-blocking, 0 nits.
Careful, high-quality docs pass. I built the SQL functions API page (api/sql/) and confirmed the arguments blocks this PR populates render there, so the rationale holds. Two minor consistency items in the added text.

Correctness (1)

• datetimeExpressions.scala:1158: year/quarter/month/dayofmonth/dayofweek/dayofyear prose says "date or timestamp" but the type phrase says only "a date"; timestamp is accepted (verified) — see inline

Suggestions (1)

• Between.scala:38: upper (and arrays_zipa2, tuple-sketch lgNomEntries/mode) omit the type line their sibling args got — see inline

Verification

Built the SQL functions API page via sql/gen-sql-api-docs.py (the generator behind spark.apache.org/docs/latest/api/sql/): its ExpressionInfo carries an arguments field and it emits a Arguments: block reproducing the text verbatim — rendered blocks appear (44 in datetime, 22 in string, etc.), so the type sentences this PR adds will show there once compiled. Separately confirmed year(TIMESTAMP), dayofyear, weekofyear all evaluate against a local build, so "a date" is narrower than the accepted types.

[cloud-fan]

1 blocking, 1 non-blocking, 0 nits.
The documentation sweep is broadly consistent, but one function argument remains undocumented and an unrelated partial-download artifact was committed.

Design / architecture (1)

• General: Remove build/sbt-launch-1.12.13.jar.part; this empty partial-download artifact is unrelated to the SQL documentation change.

Correctness (1)

• sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/stringExpressions.scala:65: Document the variadic string/array argument accepted by concat_ws, not only its separator. -- see inline

Verification

Reviewed all 52 available per-file patches, traced the 12 extracted behavioral claims to their implementations, and independently checked concat_ws against ConcatWs.inputTypes.

[HyukjinKwon]

Merge Summary:

• merged into master 6bd7322
• merged into branch-4.x 9613df9

Posted by merge_spark_pr.py