[SPARK-31866][SQL][DOCS] Add COALESCE/REPARTITION/REPARTITION_BY_RANGE Hints to SQL Reference

docs/_data/menu-sql.yaml

@@ -171,12 +171,12 @@
                   url: sql-ref-syntax-qry-select-limit.html
                 - text: Common Table Expression
                   url: sql-ref-syntax-qry-select-cte.html
+                - text: Hints
+                  url: sql-ref-syntax-qry-select-hints.html
                 - text: Inline Table
                   url: sql-ref-syntax-qry-select-inline-table.html
                 - text: JOIN
                   url: sql-ref-syntax-qry-select-join.html
-                - text: Join Hints
-                  url: sql-ref-syntax-qry-select-hints.html
                 - text: LIKE Predicate
                   url: sql-ref-syntax-qry-select-like.html
                 - text: Set Operators

docs/sql-performance-tuning.md

@@ -179,7 +179,7 @@ SELECT /*+ BROADCAST(r) */ * FROM records r JOIN src s ON r.key = s.key
 </div>
 </div>
 
-For more details please refer to the documentation of [Join Hints](sql-ref-syntax-qry-select-hints.html).
+For more details please refer to the documentation of [Hints](sql-ref-syntax-qry-select-hints.html).
 
 ## Coalesce Hints for SQL Queries
 

docs/sql-ref-syntax-qry-select-hints.md

@@ -1,7 +1,7 @@
 ---
 layout: global
-title: Join Hints
-displayTitle: Join Hints
+title: Hints
+displayTitle: Hints
 license: |
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
@@ -21,14 +21,69 @@ license: |
 
 ### Description
 
-Join Hints allow users to suggest the join strategy that Spark should use. Prior to Spark 3.0, only the `BROADCAST` Join Hint was supported. `MERGE`, `SHUFFLE_HASH` and `SHUFFLE_REPLICATE_NL` Joint Hints support was added in 3.0. When different join strategy hints are specified on both sides of a join, Spark prioritizes hints in the following order: `BROADCAST` over `MERGE` over `SHUFFLE_HASH` over `SHUFFLE_REPLICATE_NL`. When both sides are specified with the `BROADCAST` hint or the `SHUFFLE_HASH` hint, Spark will pick the build side based on the join type and the sizes of the relations. Since a given strategy may not support all join types, Spark is not guaranteed to use the join strategy suggested by the hint.
+Hints give users a way to suggest how Spark SQL to use specific approaches to generate its execution plan.
 
 ### Syntax
 
 ```sql
-/*+ join_hint [ , ... ] */
+/*+ hint [ , ... ] */
 ```
 
+### Partitioning Hints
+
+`COALESCE`/`REPARTITION`/`REPARTITION_BY_RANGE` hints have functionalities equivalent to those of the
+`Dataset` `coalesce`/`repartition`/`repartitionByRange` APIs. The `COALESCE` hint can be used to reduce
+the number of partitions to the specified number of partitions. The `REPARTITION`/`REPARTITION_BY_RANGE`
+hint can be used to repartition to the specified number of partitions using the specified partitioning expressions.
+The `COALESCE` hint takes a partition number as a
+parameter. The `REPARTITION` hint takes a partition number, column names, or both as parameters.
+The `REPARTITION_BY_RANGE` hint takes column names and an optional partition number as parameters.
+These hints give users a way to tune performance and control the number of output files in Spark SQL.
+
+### Examples
+```sql
+SELECT /*+ COALESCE(3) */ * FROM t;
+
+EXPLAIN SELECT /*+ COALESCE(3) */ * FROM t;
+== Physical Plan ==
+Coalesce 3
++- *(1) ColumnarToRow
+   +- FileScan parquet default.t[name#5,c#6] Batched: true, DataFilters: [], Format: Parquet,
+      Location: CatalogFileIndex[file:/spark/spark-warehouse/t], PartitionFilters: [],
+      PushedFilters: [], ReadSchema: struct<name:string>
+
+SELECT /*+ REPARTITION(3) */ * FROM t;
+
+SELECT /*+ REPARTITION(c) */ * FROM t;
+
+SELECT /*+ REPARTITION(3, c) */ * FROM t;
+
+EXPLAIN SELECT /*+ REPARTITION(3, c) */ * FROM t;
+== Physical Plan ==
+Exchange hashpartitioning(c#6, 3), false, [id=#148]
++- *(1) ColumnarToRow
+   +- FileScan parquet default.t[name#5,c#6] Batched: true, DataFilters: [], Format: Parquet,
+      Location: CatalogFileIndex[file:/spark/spark-warehouse/t], PartitionFilters: [],
+      PushedFilters: [], ReadSchema: struct<name:string>
+
+SELECT /*+ REPARTITION_BY_RANGE(c) */ * FROM t;
+
+SELECT /*+ REPARTITION_BY_RANGE(3, c) */ * FROM t;
+
+EXPLAIN SELECT /*+ REPARTITION_BY_RANGE(3, c) */ * FROM t;
+== Physical Plan ==
+Exchange rangepartitioning(c#6 ASC NULLS FIRST, 3), false, [id=#167]
++- *(1) ColumnarToRow
+   +- FileScan parquet default.t[name#5,c#6] Batched: true, DataFilters: [], Format: Parquet,
+      Location: CatalogFileIndex[file:/spark/spark-warehouse/t], PartitionFilters: [],
+      PushedFilters: [], ReadSchema: struct<name:string>
+```
+
+
+### Join Hints
+
+Join Hints allow users to suggest the join strategy that Spark should use. Prior to Spark 3.0, only the `BROADCAST` Join Hint was supported. `MERGE`, `SHUFFLE_HASH` and `SHUFFLE_REPLICATE_NL` Joint Hints support was added in 3.0. When different join strategy hints are specified on both sides of a join, Spark prioritizes hints in the following order: `BROADCAST` over `MERGE` over `SHUFFLE_HASH` over `SHUFFLE_REPLICATE_NL`. When both sides are specified with the `BROADCAST` hint or the `SHUFFLE_HASH` hint, Spark will pick the build side based on the join type and the sizes of the relations. Since a given strategy may not support all join types, Spark is not guaranteed to use the join strategy suggested by the hint.
+
 ### Join Hints Types
 
 * **BROADCAST**

docs/sql-ref-syntax-qry-select-join.md

@@ -235,4 +235,4 @@ SELECT * FROM employee ANTI JOIN department ON employee.deptno = department.dept
 ### Related Statements
 
 * [SELECT](sql-ref-syntax-qry-select.html)
-* [Join Hints](sql-ref-syntax-qry-select-hints.html)
+* [Hints](sql-ref-syntax-qry-select-hints.html)

docs/sql-ref-syntax-qry-select.md

@@ -151,9 +151,9 @@ SELECT [ hints , ... ] [ ALL | DISTINCT ] { named_expression [ , ... ] }
 * [DISTRIBUTE BY Clause](sql-ref-syntax-qry-select-distribute-by.html)
 * [LIMIT Clause](sql-ref-syntax-qry-select-limit.html)
 * [Common Table Expression](sql-ref-syntax-qry-select-cte.html)
+* [Hints](sql-ref-syntax-qry-select-hints.html)
 * [Inline Table](sql-ref-syntax-qry-select-inline-table.html)
 * [JOIN](sql-ref-syntax-qry-select-join.html)
-* [Join Hints](sql-ref-syntax-qry-select-hints.html)
 * [LIKE Predicate](sql-ref-syntax-qry-select-like.html)
 * [Set Operators](sql-ref-syntax-qry-select-setops.html)
 * [TABLESAMPLE](sql-ref-syntax-qry-sampling.html)

docs/sql-ref-syntax-qry.md

@@ -37,9 +37,9 @@ ability to generate logical and physical plan for a given query using
   * [DISTRIBUTE BY Clause](sql-ref-syntax-qry-select-distribute-by.html)
   * [LIMIT Clause](sql-ref-syntax-qry-select-limit.html)
   * [Common Table Expression](sql-ref-syntax-qry-select-cte.html)
+  * [Hints](sql-ref-syntax-qry-select-hints.html)
   * [Inline Table](sql-ref-syntax-qry-select-inline-table.html)
   * [JOIN](sql-ref-syntax-qry-select-join.html)
-  * [Join Hints](sql-ref-syntax-qry-select-hints.html)
   * [LIKE Predicate](sql-ref-syntax-qry-select-like.html)
   * [Set Operators](sql-ref-syntax-qry-select-setops.html)
   * [TABLESAMPLE](sql-ref-syntax-qry-sampling.html)

docs/sql-ref-syntax.md

@@ -54,9 +54,9 @@ Spark SQL is Apache Spark's module for working with structured data. The SQL Syn
    * [DISTRIBUTE BY Clause](sql-ref-syntax-qry-select-distribute-by.html)
    * [GROUP BY Clause](sql-ref-syntax-qry-select-groupby.html)
    * [HAVING Clause](sql-ref-syntax-qry-select-having.html)
+   * [Hints](sql-ref-syntax-qry-select-hints.html)
    * [Inline Table](sql-ref-syntax-qry-select-inline-table.html)
    * [JOIN](sql-ref-syntax-qry-select-join.html)
-   * [Join Hints](sql-ref-syntax-qry-select-hints.html)
    * [LIKE Predicate](sql-ref-syntax-qry-select-like.html)
    * [LIMIT Clause](sql-ref-syntax-qry-select-limit.html)
    * [ORDER BY Clause](sql-ref-syntax-qry-select-orderby.html)