[SPARK-48180][SQL] Improve error when UDTF call with TABLE arg forgets parentheses around multiple PARTITION/ORDER BY exprs

[dtenedor]

What changes were proposed in this pull request?

This PR improves the error message when a table-valued function call has a TABLE argument with a PARTITION BY or ORDER BY clause with more than one associated expression, but forgets parentheses around them.

For example:

SELECT * FROM testUDTF(
  TABLE(SELECT 1 AS device_id, 2 AS data_ds)
  WITH SINGLE PARTITION
  ORDER BY device_id, data_ds)

This query previously returned an obscure, unrelated error:

[UNSUPPORTED_SUBQUERY_EXPRESSION_CATEGORY.UNSUPPORTED_TABLE_ARGUMENT] Unsupported subquery expression: Table arguments are used in a function where they are not supported:
'UnresolvedTableValuedFunction [tvf], [table-argument#338 [], 'data_ds](https://issues.apache.org/jira/browse/SPARK-48180#338%20[],%20'data_ds), false
   +- Project [1 AS device_id#336, 2 AS data_ds#337](https://issues.apache.org/jira/browse/SPARK-48180#336,%202%20AS%20data_ds#337)
      +- OneRowRelation

Now it returns a reasonable error:

The table function call includes a table argument with an invalid partitioning/ordering specification: the ORDER BY clause included multiple expressions without parentheses surrounding them; please add parentheses around these expressions and then retry the query again. (line 4, pos 2)

== SQL ==

SELECT * FROM testUDTF(
  TABLE(SELECT 1 AS device_id, 2 AS data_ds)
  WITH SINGLE PARTITION
--^^^
  ORDER BY device_id, data_ds)

Why are the changes needed?

Here we improve error messages for common SQL syntax mistakes.

Does this PR introduce any user-facing change?

Yes, see above.

How was this patch tested?

This PR adds test coverage.

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

No

[dtenedor]

cc @ueshin @allisonwang-db

[dtenedor]

@HyukjinKwon I fixed the test failures, it should work now :)

[allisonwang-db]

Thanks for the fix!

[allisonwang-db]

Should the correct syntax be ORDER BY (device_id, date_ds)? Do we want to add an example in the error message?

[dtenedor]

Yes, that should be the correct syntax.
Interesting idea...trying this out with some simple and complex cases, I am a bit scared to copy/paste the entire provided ORDER BY clause into the error message since it could be very long if there are many columns/complex expressions. But the new error message specifically indicates to add parentheses around the expressions, it should be pretty clear (see L381-L384 below).

[allisonwang-db]

SGTM!

[HyukjinKwon]

Merged to master.