[SPARK-42924][SQL][CONNECT][PYTHON] Clarify the comment of parameterized SQL args

### What changes were proposed in this pull request?
In the PR, I propose to clarify the comment of `args` in parameterized `sql()`.

### Why are the changes needed?
To make the comment more clear and highlight that input strings are parsed (not evaluated), and considered as SQL literal expressions. Also while parsing the fragments w/ SQL comments in the string values are skipped.

### Does this PR introduce _any_ user-facing change?
No.

### How was this patch tested?
By checking coding style:
```
$ ./dev/lint-python
$ ./dev/scalastyle
```

Closes apache#40508 from MaxGekk/parameterized-sql-doc.

Authored-by: Max Gekk <[email protected]>
Signed-off-by: Max Gekk <[email protected]>

Author: MaxGekk

connector/connect/client/jvm/src/main/scala/org/apache/spark/sql/SparkSession.scala

@@ -213,7 +213,10 @@ class SparkSession private[sql] (
    * @param sqlText
    *   A SQL statement with named parameters to execute.
    * @param args
-   *   A map of parameter names to literal values.
+   *   A map of parameter names to string values that are parsed as SQL literal expressions. For
+   *   example, map keys: "rank", "name", "birthdate"; map values: "1", "'Steven'",
+   *   "DATE'2023-03-21'". The fragments of string values belonged to SQL comments are skipped
+   *   while parsing.
    *
    * @since 3.4.0
    */
@@ -229,7 +232,10 @@ class SparkSession private[sql] (
    * @param sqlText
    *   A SQL statement with named parameters to execute.
    * @param args
-   *   A map of parameter names to literal values.
+   *   A map of parameter names to string values that are parsed as SQL literal expressions. For
+   *   example, map keys: "rank", "name", "birthdate"; map values: "1", "'Steven'",
+   *   "DATE'2023-03-21'". The fragments of string values belonged to SQL comments are skipped
+   *   while parsing.
    *
    * @since 3.4.0
    */

connector/connect/common/src/main/protobuf/spark/connect/commands.proto

@@ -53,7 +53,10 @@ message SqlCommand {
   // (Required) SQL Query.
   string sql = 1;
 
-  // (Optional) A map of parameter names to literal values.
+  // (Optional) A map of parameter names to string values that are parsed as
+  // SQL literal expressions. For example, map keys: "rank", "name", "birthdate";
+  // map values: "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values
+  // belonged to SQL comments are skipped while parsing.
   map<string, string> args = 2;
 }
 

connector/connect/common/src/main/protobuf/spark/connect/relations.proto

@@ -108,7 +108,10 @@ message SQL {
   // (Required) The SQL query.
   string query = 1;
 
-  // (Optional) A map of parameter names to literal values.
+  // (Optional) A map of parameter names to string values that are parsed as
+  // SQL literal expressions. For example, map keys: "rank", "name", "birthdate";
+  // map values: "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values
+  // belonged to SQL comments are skipped while parsing.
   map<string, string> args = 2;
 }
 

python/pyspark/pandas/sql_formatter.py

@@ -103,8 +103,10 @@ def sql(
 
             Also note that the index name(s) should be matched to the existing name.
     args : dict
-        A dictionary of named parameters that begin from the `:` marker and
-        their SQL literals for substituting.
+        A dictionary of parameter names to string values that are parsed as SQL literal
+        expressions. For example, dict keys: "rank", "name", "birthdate"; dict values:
+        "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values belonged to SQL
+        comments are skipped while parsing.
 
         .. versionadded:: 3.4.0
 

python/pyspark/sql/connect/proto/commands_pb2.pyi

@@ -178,7 +178,11 @@ class SqlCommand(google.protobuf.message.Message):
     """(Required) SQL Query."""
     @property
     def args(self) -> google.protobuf.internal.containers.ScalarMap[builtins.str, builtins.str]:
-        """(Optional) A map of parameter names to literal values."""
+        """(Optional) A map of parameter names to string values that are parsed as
+        SQL literal expressions. For example, map keys: "rank", "name", "birthdate";
+        map values: "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values
+        belonged to SQL comments are skipped while parsing.
+        """
     def __init__(
         self,
         *,

python/pyspark/sql/connect/proto/relations_pb2.pyi

@@ -577,7 +577,11 @@ class SQL(google.protobuf.message.Message):
     """(Required) The SQL query."""
     @property
     def args(self) -> google.protobuf.internal.containers.ScalarMap[builtins.str, builtins.str]:
-        """(Optional) A map of parameter names to literal values."""
+        """(Optional) A map of parameter names to string values that are parsed as
+        SQL literal expressions. For example, map keys: "rank", "name", "birthdate";
+        map values: "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values
+        belonged to SQL comments are skipped while parsing.
+        """
     def __init__(
         self,
         *,

python/pyspark/sql/session.py

@@ -1336,8 +1336,10 @@ def sql(self, sqlQuery: str, args: Optional[Dict[str, str]] = None, **kwargs: An
         sqlQuery : str
             SQL query string.
         args : dict
-            A dictionary of named parameters that begin from the `:` marker and
-            their SQL literals for substituting.
+            A dictionary of parameter names to string values that are parsed as SQL literal
+            expressions. For example, dict keys: "rank", "name", "birthdate"; dict values:
+            "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values belonged to
+            SQL comments are skipped while parsing.
 
             .. versionadded:: 3.4.0
 

sql/core/src/main/scala/org/apache/spark/sql/SparkSession.scala

@@ -612,7 +612,10 @@ class SparkSession private(
    * This API eagerly runs DDL/DML commands, but not for SELECT queries.
    *
    * @param sqlText A SQL statement with named parameters to execute.
-   * @param args A map of parameter names to literal values.
+   * @param args A map of parameter names to string values that are parsed as
+   *             SQL literal expressions. For example, map keys: "rank", "name", "birthdate";
+   *             map values: "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values
+   *             belonged to SQL comments are skipped while parsing.
    *
    * @since 3.4.0
    */
@@ -637,7 +640,10 @@ class SparkSession private(
    * This API eagerly runs DDL/DML commands, but not for SELECT queries.
    *
    * @param sqlText A SQL statement with named parameters to execute.
-   * @param args A map of parameter names to literal values.
+   * @param args A map of parameter names to string values that are parsed as
+   *             SQL literal expressions. For example, map keys: "rank", "name", "birthdate";
+   *             map values: "1", "'Steven'", "DATE'2023-03-21'". The fragments of string values
+   *             belonged to SQL comments are skipped while parsing.
    *
    * @since 3.4.0
    */