[SPARK-54343][DOCS] Docs for parameter markers, identifier improvements, string coalescing

### What changes were proposed in this pull request?

* We document named an unnamed parameters and how to use them
* We document the ability to coalesce string literals though chaing
* We document the extended usage of teh IDENTIFIER clause

### Why are the changes needed?

Sync the docs with the code.

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

No

### How was this patch tested?

Building of the docs and reviewing the pages

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

No

Closes #53047 from srielau/param-rework-docs.

Authored-by: Serge Rielau <serge@rielau.com>
Signed-off-by: Daniel Tenedorio <daniel.tenedorio@databricks.com>

Author: srielau

docs/_data/menu-sql.yaml

@@ -99,6 +99,8 @@
       url: sql-ref-literals.html
     - text: Null Semantics
       url: sql-ref-null-semantics.html
+    - text: Parameter Markers
+      url: sql-ref-parameter-markers.html
     - text: SQL Syntax
       url: sql-ref-syntax.html
       subitems:

docs/sql-ref-identifier-clause.md

@@ -23,26 +23,54 @@ license: |
 
 Converts a constant `STRING` expression into a SQL object name.
 The purpose of this clause is to allow for templating of identifiers in SQL statements without opening up the risk of SQL injection attacks.
-Typically, this clause is used with a parameter marker or a variable as argument.
+
+The clause comes in two forms:
+
+- When passed a string-literal, which may include a coalesced string of literals and parameter markers, it can be used anywhere an identifier or qualified identifier can be used.
+  The usage of this form is encouraged.
+- When passed a more complex constant string expression, which may also include variables, it can be used in limited cases to reference dynamic SQL object references such as table names, column names, and function names.
+  The usage of this form is discouraged unless necessary.
+  For example you cannot use this form to parameterize a table or column alias, or a column name in a `CREATE TABLE` statement.
 
 ### Syntax
 
 ```sql
+IDENTIFIER ( strLiteral )
+
 IDENTIFIER ( strExpr )
 ```
 
 ### Parameters
 
-- **strExpr**: A constant `STRING` expression. Typically, the expression includes a parameter marker.
+- **strLiteral**
 
-### Returns
+  A constant `STRING` literal which may include string coalescing of strings and string parameter markers.
+
+  The string must be a valid (qualified) identifier.
+
+  For example:
+
+  ```
+  IDENTIFIER('default.' :tablename)
+  IDENTIFIER(:catalog '.' :namespace '.' :tablename '.' :columnname)
+  IDENTIFIER(:rootdirectory '/data/' :tablename)
+  ```
 
-A (qualified) identifier which can be used as a:
+- **strExpr**: A constant `STRING` expression. Typically, the expression includes a parameter marker or session variable.
 
-- qualified table name
-- namespace name
-- function name
-- qualified column or attribute reference
+  The string must be a valid (qualified) identifier.
+
+  For example:
+  
+  ```
+  IDENTIFIER(session.schema || '.' || session.tablename)
+  IDENTIFIER('`' || session.schema || '`.`' session.tablename || '`')
+  IDENTIFIER(CONCAT(:catalog, '.', :namespace, '.', :tablename, '.', :columnname))
+  ```
+
+### Returns
+
+A (qualified) identifier.
 
 ### Examples
 
@@ -88,7 +116,7 @@ spark.sql("SELECT * FROM IDENTIFIER(:myschema).mytab", args = Map("mychema" -> "
 [PARSE_SYNTAX_ERROR]
 
 // Dropping a table with separate schema and table parameters.
-spark.sql("DROP TABLE IDENTIFIER(:myschema || '.' || :mytab)", args = Map("myschema" -> "default", "mytab" -> "tab1")).show()
+spark.sql("DROP TABLE IDENTIFIER(:myschema '.' :mytab)", args = Map("myschema" -> "default", "mytab" -> "tab1")).show()
 
 // A parameterized column reference
 spark.sql("SELECT IDENTIFIER(:col) FROM VALUES(1) AS T(c1)", args = Map("col" -> "t.c1")).show()
@@ -117,18 +145,18 @@ DECLARE mytab = 'tab1';
 -- Creation of a table using variable.
 CREATE TABLE IDENTIFIER(mytab)(c1 INT);
 
-DESCRIBE IDENTIFIER(mytab);
+EXECUTE IMMEDIATE 'DESCRIBE IDENTIFIER(:mytab)' USING mytab;
 +--------+---------+-------+
 |col_name|data_type|comment|
 +--------+---------+-------+
 |      c1|      int|   NULL|
 +--------+---------+-------+
 
 -- Altering a table with a fixed schema and a parameterized table name. 
-ALTER TABLE IDENTIFIER('default.' || mytab) ADD COLUMN c2 INT;
+EXECUTE IMMEDIATE 'ALTER TABLE IDENTIFIER('default.' || :mytab) ADD COLUMN :col INT' USING mytab, 'c2' AS col;
 
 SET VAR mytab = '`default`.`tab1`';
-DESCRIBE IDENTIFIER(mytab);
+EXECUTE IMMEDIATE 'DESCRIBE IDENTIFIER(:mytab)' USING mytab;
 +--------+---------+-------+
 |col_name|data_type|comment|
 +--------+---------+-------+
@@ -137,30 +165,27 @@ DESCRIBE IDENTIFIER(mytab);
 +--------+---------+-------+
 
 -- A parameterized reference to a table in a query. This table name is qualified and uses back-ticks.
-SELECT * FROM IDENTIFIER(mytab);
+EXECUTE IMMEDIATE 'SELECT * FROM IDENTIFIER(mytab)' USING mytab;
 +---+---+
 | c1| c2|
 +---+---+
-+---+---+
-
 
 -- Dropping a table with separate schema and table parameters.
 DECLARE myschema = 'default';
 SET VAR mytab = 'tab1';
-DROP TABLE IDENTIFIER(myschema || '.' || mytab);
+EXECUTE IMMEDIATE 'DROP TABLE IDENTIFIER(:myschema '.' :mytab)' USING myschema, mytab;
 
 -- A parameterized column reference
-DECLARE col = 't.c1';
-SELECT IDENTIFIER(col) FROM VALUES(1) AS T(c1);
+DECLARE col = 'c1';
+EXECUTE IMEMDIATE 'SELECT IDENTIFIER(:col) FROM VALUES(1) AS T(IDENTIFIER(:col))' USING col;
 +---+
 | c1|
 +---+
 |  1|
 +---+
 
 -- Passing in a function name as a parameter
-DECLARE func = 'abs';
-SELECT IDENTIFIER(func)(-1);
+EXECUTE IMMEDIATE 'SELECT IDENTIFIER(:func)(-1)' USING 'abs' AS func;
 +-------+
 |abs(-1)|
 +-------+

docs/sql-ref-literals.md

@@ -36,7 +36,7 @@ A string literal is used to specify a character string value.
 #### Syntax
 
 ```sql
-[ r ] { 'char [ ... ]' | "char [ ... ]" }
+[ r ] { 'char [ ... ]' | "char [ ... ]" } [ ... ]
 ```
 
 #### Parameters
@@ -65,6 +65,10 @@ The following escape sequences are recognized in regular string literals (withou
 
 The unescaping rules above can be turned off by setting the SQL config `spark.sql.parser.escapedStringLiterals` to `true`.
 
+Chains of string literals are coalesced into a single string literal.
+This can be useful when constructing strings that are too long to fit on a single line.
+It also allows mixing of string literals and parameter marker into a single string literal.
+
 #### Examples
 
 ```sql
@@ -95,6 +99,20 @@ SELECT r"'\n' represents newline character." AS col;
 +----------------------------------+
 |'\n' represents newline character.|
 +----------------------------------+
+
+SELECT 'Hello' ',' 'World!' AS col;
++-------------+
+|          col|
++-------------+
+|Hello, World!|
++-------------+
+
+EXECUTE IMMEDIATE 'SELECT "Hello, " :p "!" AS col' USING 'World' AS p;
++-------------+
+|          col|
++-------------+
+|Hello, World!|
++-------------+
 ```
 
 ### Binary Literal