Merge pull request #33413 from WilliamDAssafMSFT/20250307-query-hints-dw

20250307 hints maintenance, add Fabric DW applicability

Author: denrea

docs/t-sql/queries/from-transact-sql.md

@@ -4,7 +4,7 @@ description: FROM clause plus JOIN, APPLY, PIVOT (Transact-SQL)
 author: VanMSFT
 ms.author: vanto
 ms.reviewer: randolphwest
-ms.date: 09/25/2024
+ms.date: 03/07/2025
 ms.service: sql
 ms.subservice: t-sql
 ms.topic: reference
@@ -59,7 +59,7 @@ This article also discusses the following keywords that can be used on the FROM
 
 ## Syntax
 
-Syntax for SQL Server, Azure SQL Database, and Fabric SQL database:
+Syntax for SQL Server, Azure SQL Database, and SQL database in Fabric:
 
 ```syntaxsql
 [ FROM { <table_source> } [ , ...n ] ]
@@ -168,8 +168,7 @@ FROM { <table_source> [ , ...n ] }
     | REDISTRIBUTE
 ```
 
-Syntax for Microsoft Fabric:
-
+Syntax for Microsoft Fabric Data Warehouse:
 
 ```syntaxsql
 FROM { <table_source> [ , ...n ] }
@@ -334,19 +333,9 @@ Specifies all rows from the right table not meeting the join condition are inclu
 
 For [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] and [!INCLUDE[ssSDS](../../includes/sssds-md.md)], specifies that the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] query optimizer uses one join hint, or execution algorithm, per join specified in the query FROM clause. For more information, see [Join Hints (Transact-SQL)](../queries/hints-transact-sql-join.md).
 
-For [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)] and [!INCLUDE[ssPDW](../../includes/sspdw-md.md)], these join hints apply to INNER joins on two distribution incompatible columns. They can improve query performance by restricting the amount of data movement that occurs during query processing. The allowable join hints for [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)] and [!INCLUDE[ssPDW](../../includes/sspdw-md.md)] are as follows:
-
-#### REDUCE
-
-Reduces the number of rows to be moved for the table on the right side of the join in order to make two distribution incompatible tables compatible. The REDUCE hint is also called a semi-join hint.
-
-#### REPLICATE
-
-Causes the values in the joining column from the table on the right side of the join to be replicated to all nodes. The table on the left is joined to the replicated version of those columns.
-
-#### REDISTRIBUTE
+For [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)], [!INCLUDE[ssPDW](../../includes/sspdw-md.md)], and [!INCLUDE [fabric](../../includes/fabric.md)] Data Warehouse, these join hints apply to `INNER` joins on two distribution incompatible columns. They can improve query performance by restricting the amount of data movement that occurs during query processing. 
 
-Forces two data sources to be distributed on columns specified in the JOIN clause. For a distributed table, [!INCLUDE[ssPDW](../../includes/sspdw-md.md)] performs a shuffle move. For a replicated table, [!INCLUDE[ssPDW](../../includes/sspdw-md.md)] performs a trim move. To understand these move types, see the "DMS Query Plan Operations" section in the "Understanding Query Plans" article in the [!INCLUDE[pdw-product-documentation](../../includes/pdw-product-documentation-md.md)]. This hint can improve performance when the query plan is using a broadcast move to resolve a distribution incompatible join.
+For more information on `REDUCE`, `REPLICATE`, and `REDISTRIBUTE`, see [Join hints (Transact-SQL)](hints-transact-sql-join.md). 
 
 #### JOIN
 
@@ -681,7 +670,7 @@ The following example assumes that the following tables and table-valued functio
 | Employees | EmpID, EmpLastName, EmpFirstName, EmpSalary |
 | GetReports(MgrID) | EmpID, EmpLastName, EmpSalary |
 
-The `GetReports` table-valued function, returns the list of all employees that report directly or indirectly to the specified `MgrID`.
+The `GetReports` table-valued function returns the list of all employees that report directly or indirectly to the specified `MgrID`.
 
 The example uses `APPLY` to return all departments and all employees in that department. If a particular department doesn't have any employees, there won't be any rows returned for that department.
 
@@ -729,7 +718,7 @@ GO
 
 **Applies to**: [!INCLUDE[sssql16-md](../../includes/sssql16-md.md)] and later versions, and [!INCLUDE[sssds](../../includes/sssds-md.md)].
 
-The following example uses the FOR SYSTEM_TIME AS OF *date_time_literal_or_variable* argument to return table rows that were actual (current) as of January 1, 2014.
+The following example uses the `FOR SYSTEM_TIME AS OF *date_time_literal_or_variable*` argument to return table rows that were actual (current) as of January 1, 2014.
 
 ```sql
 SELECT DepartmentNumber,
@@ -741,7 +730,7 @@ FOR SYSTEM_TIME AS OF '2014-01-01'
 WHERE ManagerID = 5;
 ```
 
-The following example uses the FOR SYSTEM_TIME FROM *date_time_literal_or_variable* TO *date_time_literal_or_variable* argument to return all rows that were active during the period defined as starting with January 1, 2013 and ending with January 1, 2014, exclusive of the upper boundary.
+The following example uses the `FOR SYSTEM_TIME FROM *date_time_literal_or_variable* TO *date_time_literal_or_variable*` argument to return all rows that were active during the period defined as starting with January 1, 2013 and ending with January 1, 2014, exclusive of the upper boundary.
 
 ```sql
 SELECT DepartmentNumber,
@@ -753,7 +742,7 @@ FOR SYSTEM_TIME FROM '2013-01-01' TO '2014-01-01'
 WHERE ManagerID = 5;
 ```
 
-The following example uses the FOR SYSTEM_TIME BETWEEN *date_time_literal_or_variable* AND *date_time_literal_or_variable* argument to return all rows that were active during the period defined as starting with January 1, 2013 and ending with January 1, 2014, inclusive of the upper boundary.
+The following example uses the `FOR SYSTEM_TIME BETWEEN *date_time_literal_or_variable* AND *date_time_literal_or_variable*` argument to return all rows that were active during the period defined as starting with January 1, 2013 and ending with January 1, 2014, inclusive of the upper boundary.
 
 ```sql
 SELECT DepartmentNumber,
@@ -765,7 +754,7 @@ FOR SYSTEM_TIME BETWEEN '2013-01-01' AND '2014-01-01'
 WHERE ManagerID = 5;
 ```
 
-The following example uses the FOR SYSTEM_TIME CONTAINED IN (*date_time_literal_or_variable*, *date_time_literal_or_variable*) argument to return all rows that were opened and closed during the period defined as starting with January 1, 2013 and ending with January 1, 2014.
+The following example uses the `FOR SYSTEM_TIME CONTAINED IN (*date_time_literal_or_variable*, *date_time_literal_or_variable*)` argument to return all rows that were opened and closed during the period defined as starting with January 1, 2013 and ending with January 1, 2014.
 
 ```sql
 SELECT DepartmentNumber,
@@ -797,7 +786,7 @@ WHERE ManagerID = 5;
 
 ### N. Use the INNER JOIN syntax
 
-The following example returns the `SalesOrderNumber`, `ProductKey`, and `EnglishProductName` columns from the `FactInternetSales` and `DimProduct` tables where the join key, `ProductKey`, matches in both tables. The `SalesOrderNumber` and `EnglishProductName` columns each exist in one of the tables only, so it isn't necessary to specify the table alias with these columns, as is shown; these aliases are included for readability. The word **AS** before an alias name isn't required but is recommended for readability and to conform to the ANSI standard.
+The following example returns the `SalesOrderNumber`, `ProductKey`, and `EnglishProductName` columns from the `FactInternetSales` and `DimProduct` tables where the join key, `ProductKey`, matches in both tables. The `SalesOrderNumber` and `EnglishProductName` columns each exist in one of the tables only, so it isn't necessary to specify the table alias with these columns, as is shown; these aliases are included for readability. The keyword `AS` before an alias name isn't required but is recommended for readability and to conform to the ANSI standard.
 
 ```sql
 -- Uses AdventureWorks
@@ -868,7 +857,7 @@ RIGHT OUTER JOIN FactInternetSales AS fis
     ON dp.ProductKey = fis.ProductKey;
 ```
 
-The following query uses the `DimSalesTerritory` table as the left table in a left outer join. It retrieves the `SalesOrderNumber` values from the `FactInternetSales` table. If there are no orders for a particular `SalesTerritoryKey`, the query returns a NULL for the `SalesOrderNumber` for that row. This query is ordered by the `SalesOrderNumber` column, so that any NULLs in this column appear at the top of the results.
+The following query uses the `DimSalesTerritory` table as the left table in a left outer join. It retrieves the `SalesOrderNumber` values from the `FactInternetSales` table. If there are no orders for a particular `SalesTerritoryKey`, the query returns a `NULL` for the `SalesOrderNumber` for that row. This query is ordered by the `SalesOrderNumber` column, so that any `NULL`s in this column appear at the top of the results.
 
 ```sql
 -- Uses AdventureWorks
@@ -898,7 +887,7 @@ ORDER BY fis.SalesOrderNumber;
 
 ### P. Use the FULL OUTER JOIN syntax
 
-The following example demonstrates a full outer join, which returns all rows from both joined tables but returns NULL for values that don't match from the other table.
+The following example demonstrates a full outer join, which returns all rows from both joined tables but returns `NULL` for values that don't match from the other table.
 
 ```sql
 -- Uses AdventureWorks
@@ -998,9 +987,9 @@ ORDER BY SalesOrderNumber;
 
 ### U. Use the REDISTRIBUTE hint to guarantee a Shuffle move for a distribution incompatible join
 
-The following query uses the REDISTRIBUTE query hint on a distribution incompatible join. This guarantees the query optimizer uses a Shuffle move in the query plan. This also guarantees the query plan won't use a Broadcast move, which moves a distributed table to a replicated table.
+The following query uses the `REDISTRIBUTE` query hint on a distribution incompatible join. This guarantees the query optimizer uses a Shuffle move in the query plan. This also guarantees the query plan won't use a Broadcast move, which moves a distributed table to a replicated table.
 
-In the following example, the REDISTRIBUTE hint forces a Shuffle move on the FactInternetSales table because ProductKey is the distribution column for DimProduct, and isn't the distribution column for FactInternetSales.
+In the following example, the `REDISTRIBUTE` hint forces a Shuffle move on the `FactInternetSales` table because `ProductKey` is the distribution column for `DimProduct`, and isn't the distribution column for `FactInternetSales`.
 
 ```sql
 -- Uses AdventureWorks

docs/t-sql/queries/hints-transact-sql-join.md

@@ -3,8 +3,8 @@ title: "Join hints (Transact-SQL)"
 description: Join hints specify that the query optimizer enforce a join strategy between two tables in SQL Server.
 author: VanMSFT
 ms.author: vanto
-ms.reviewer: randolphwest
-ms.date: 06/07/2024
+ms.reviewer: randolphwest, wiassaf
+ms.date: 03/20/2025
 ms.service: sql
 ms.subservice: t-sql
 ms.topic: reference
@@ -26,7 +26,7 @@ monikerRange: "=azuresqldb-current || >=sql-server-2016 || >=sql-server-linux-20
 ---
 # Join hints (Transact-SQL)
 
-[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance FabricSQLDB](../../includes/applies-to-version/sql-asdb-asdbmi-fabricsqldb.md)]
+[!INCLUDE [sql-asdb-asdbmi-fabricse-fabricdw-fabricsqldb](../../includes/applies-to-version/sql-asdb-asdbmi-fabricse-fabricdw-fabricsqldb.md)]
 
 Join hints specify that the query optimizer enforce a join strategy between two tables in [!INCLUDE [ssnoversion](../../includes/ssnoversion-md.md)]. For general information about joins and join syntax, see [FROM clause plus JOIN, APPLY, PIVOT](from-transact-sql.md).
 
@@ -45,17 +45,22 @@ Join hints specify that the query optimizer enforce a join strategy between two
 
 ```syntaxsql
 <join_hint> ::=
-     { LOOP | HASH | MERGE | REMOTE }
+     { LOOP | HASH | MERGE | REMOTE | REDUCE | REPLICATE | REDISTRIBUTE [(columns count)]}
 ```
 
 ## Arguments
 
 #### { LOOP | HASH | MERGE }
 
+***Applies to:***  [!INCLUDE [Azure SQL Database](../../includes/ssazure-sqldb.md)], [!INCLUDE [SQL Managed Instance](../../includes/ssazuremi-md.md)], [!INCLUDE [Fabric SQL analytics endpoint](../../includes/fabric-se.md)], [!INCLUDE [fabric-sqldb](../../includes/fabric-sqldb.md)], [!INCLUDE [fabric](../../includes/fabric.md)] [!INCLUDE [Fabric Warehouse](../../includes/fabric-dw.md)]
+
 Specifies that the join in the query should use looping, hashing, or merging. Using `LOOP`, `HASH`, or `MERGE JOIN` enforces a particular join between two tables. `LOOP` can't be specified together with `RIGHT` or `FULL` as a join type. For more information, see [Joins](../../relational-databases/performance/joins.md).
 
 #### REMOTE
 
+***Applies to:*** [!INCLUDE [Azure SQL Database](../../includes/ssazure-sqldb.md)], [!INCLUDE [SQL Managed Instance](../../includes/ssazuremi-md.md)], [!INCLUDE [Fabric SQL analytics endpoint](../../includes/fabric-se.md)], [!INCLUDE [fabric-sqldb](../../includes/fabric-sqldb.md)]
+
+
 Specifies that the join operation is performed on the site of the right table. This is useful when the left table is a local table and the right table is a remote table. `REMOTE` should be used only when the left table has fewer rows than the right table.
 
 If the right table is local, the join is performed locally. If both tables are remote but from different data sources, `REMOTE` causes the join to be performed on the site of the right table. If both tables are remote tables from the same data source, `REMOTE` isn't required.
@@ -64,6 +69,35 @@ If the right table is local, the join is performed locally. If both tables are r
 
 `REMOTE` can be used only for `INNER JOIN` operations.
 
+#### REDUCE
+
+***Applies to:*** [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)] and [!INCLUDE[ssPDW](../../includes/sspdw-md.md)]
+
+Reduces the number of rows to be moved for the table on the right side of the join in order to make two distribution incompatible tables compatible. The REDUCE hint is also called a semi-join hint.
+
+#### REPLICATE
+
+***Applies to:*** [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)], [!INCLUDE[ssPDW](../../includes/sspdw-md.md)], [!INCLUDE [fabric](../../includes/fabric.md)] [!INCLUDE [Fabric Warehouse](../../includes/fabric-dw.md)]
+
+Causes a broadcast move operation, where a specific table to be replicated across all distribution nodes.
+
+- Using `REPLICATE` with a `INNER` or `LEFT` join, the broadcast move operation will replicate the right side of the join to all nodes.
+- Similarly, while using `REPLICATE` with a `RIGHT` join, the broadcast move operation will replicate the left side of the join to all nodes.
+- When using `REPLICATE` with a `FULL` join, an estimated plan cannot be created.
+
+#### REDISTRIBUTE [(columns_count)]
+
+***Applies to:*** [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)] and [!INCLUDE[ssPDW](../../includes/sspdw-md.md)]
+
+Forces two data sources to be distributed on columns specified in the JOIN clause. For a distributed table, [!INCLUDE[ssPDW](../../includes/sspdw-md.md)] performs a shuffle move on the first column of both tables For a replicated table, [!INCLUDE[ssPDW](../../includes/sspdw-md.md)] performs a trim move. To understand these move types, see the "DMS Query Plan Operations" section in the "Understanding Query Plans" article in the [!INCLUDE[pdw-product-documentation](../../includes/pdw-product-documentation-md.md)]. This hint can improve performance when the query plan is using a broadcast move to resolve a distribution incompatible join.
+
+***Applies to:*** [!INCLUDE [fabric](../../includes/fabric.md)] [!INCLUDE [Fabric Warehouse](../../includes/fabric-dw.md)]
+
+The `REDISTRIBUTE` hint ensures two data sources are distributed based on `JOIN` clause columns. It handles multiple join conditions, specified by the first *n* columns in both tables, where *n* is the `column_count` argument. Redistributing data optimizes query performance by evenly spreading data across nodes during intermediate steps of execution.
+
+The `(columns_count)` argument is only supported in [!INCLUDE [fabric](../../includes/fabric.md)] [!INCLUDE [Fabric Warehouse](../../includes/fabric-dw.md)].
+
+ 
 ## Remarks
 
 Join hints are specified in the `FROM` clause of a query. Join hints enforce a join strategy between two tables. If a join hint is specified for any two tables, the query optimizer automatically enforces the join order for all joined tables in the query, based on the position of the `ON` keywords. When a `CROSS JOIN` is used without the `ON` clause, parentheses can be used to indicate the join order.
@@ -115,6 +149,71 @@ INNER MERGE JOIN Purchasing.PurchaseOrderDetail AS pod
 GO
 ```
 
+### D. REDUCE join hint example
+
+The following example uses the `REDUCE` join hint to alter the processing of the derived table within the query. When using the `REDUCE` join hint in this query, the `fis.ProductKey` is projected, replicated and made distinct, and then joined to `DimProduct` during the shuffle of `DimProduct` on `ProductKey`. The resulting derived table is distributed on `fis.ProductKey`.
+
+```sql
+-- Uses AdventureWorks
+  
+SELECT SalesOrderNumber
+FROM (
+    SELECT fis.SalesOrderNumber,
+        dp.ProductKey,
+        dp.EnglishProductName
+    FROM DimProduct AS dp
+    INNER REDUCE JOIN FactInternetSales AS fis
+        ON dp.ProductKey = fis.ProductKey
+    ) AS dTable
+ORDER BY SalesOrderNumber;
+```
+
+### E. REPLICATE join hint example
+
+This next example shows the same query as the previous example, except that a `REPLICATE` join hint is used instead of the `REDUCE` join hint. Use of the `REPLICATE` hint causes the values in the `ProductKey` (joining) column from the `FactInternetSales` table to be replicated to all nodes. The `DimProduct` table is joined to the replicated version of those values.
+
+```sql
+-- Uses AdventureWorks
+
+SELECT SalesOrderNumber
+FROM (
+    SELECT fis.SalesOrderNumber,
+        dp.ProductKey,
+        dp.EnglishProductName
+    FROM DimProduct AS dp
+    INNER REPLICATE JOIN FactInternetSales AS fis
+        ON dp.ProductKey = fis.ProductKey
+    ) AS dTable
+ORDER BY SalesOrderNumber;
+```
+
+### F. Use the REDISTRIBUTE hint to guarantee a Shuffle move for a distribution incompatible join
+
+The following query uses the `REDISTRIBUTE` query hint on a distribution incompatible join. This guarantees the query optimizer uses a Shuffle move in the query plan. This also guarantees the query plan won't use a Broadcast move, which moves a distributed table to a replicated table.
+
+In the following example, the `REDISTRIBUTE` hint forces a Shuffle move on the `FactInternetSales` table because `ProductKey` is the distribution column for `DimProduct`, and isn't the distribution column for `FactInternetSales`.
+
+```sql
+-- Uses AdventureWorks
+  
+SELECT dp.ProductKey,
+    fis.SalesOrderNumber,
+    fis.TotalProductCost
+FROM DimProduct AS dp
+INNER REDISTRIBUTE JOIN FactInternetSales AS fis
+    ON dp.ProductKey = fis.ProductKey;
+```
+
+### G. Use the columns count argument with the REDISTRIBUTE hint
+
+The following query uses the `REDISTRIBUTE` query hint with the columns count argument, and the shuffle takes place across the first four columns of each table in the join. 
+
+```sql
+SELECT * FROM DA
+INNER REDISTRIBUTE (4) JOIN DB
+ON DA.a1 = DB.b1
+```
+
 ## Related content
 
 - [Hints (Transact-SQL)](hints-transact-sql.md)