Merge pull request #27747 from WilliamDAssafMSFT/20230716-set-recommendations-tsql

20230716 add SET RECOMMENDATIONS TSQL syntax

Author: denrea

docs/t-sql/statements/create-table-as-select-azure-sql-data-warehouse.md

@@ -116,6 +116,8 @@ Distributes the rows based on the hash values of up to eight columns, allowing f
 For details and to understand how to choose the best distribution column, see the [Table distribution options](create-table-azure-sql-data-warehouse.md#TableDistributionOptions) section in CREATE TABLE. 
 
 
+For recommendations on the best distribution do to use based on your workloads, see the [Synapse SQL Distribution Advisor (Preview)](/azure/synapse-analytics/sql/distribution-advisor).
+
 <a name="table-partition-options-bk"></a>
 
 ### Table partition options

docs/t-sql/statements/create-table-azure-sql-data-warehouse.md

@@ -3,8 +3,8 @@ title: CREATE TABLE
 description: "CREATE TABLE creates a new table in Azure Synapse Analytics, Analytics Platform System (PDW), and Microsoft Fabric."
 author: WilliamDAssafMSFT
 ms.author: wiassaf
-ms.reviewer: vanto, xiaoyul, wiassaf, mariyaali, maghan, kecona
-ms.date: 07/12/2023
+ms.reviewer: vanto, xiaoyul, mariyaali, maghan, kecona
+ms.date: 07/16/2023
 ms.service: sql
 ms.topic: reference
 dev_langs:
@@ -158,13 +158,12 @@ Assigns each row to one distribution by hashing the value stored in *distributio
 `DISTRIBUTION = HASH ( [distribution_column_name [, ...n]] )` 
 Distributes the rows based on the hash values of up to eight columns, allowing for more even distribution of the base table data, reducing the data skew over time and improving query performance.
 
->[!NOTE]
->
-> - To enable the Multi-Column Distribution (MCD) feature, change the database's compatibility level to 50 with this command. For more information on setting the database compatibility level, see [ALTER DATABASE SCOPED CONFIGURATION](./alter-database-scoped-configuration-transact-sql.md). For example: `ALTER DATABASE SCOPED CONFIGURATION SET DW_COMPATIBILITY_LEVEL = 50;`
+> [!NOTE]
+> - To enable the multi-column distribution (MCD) feature, change the database's compatibility level to 50 with this command. For more information on setting the database compatibility level, see [ALTER DATABASE SCOPED CONFIGURATION](./alter-database-scoped-configuration-transact-sql.md). For example: `ALTER DATABASE SCOPED CONFIGURATION SET DW_COMPATIBILITY_LEVEL = 50;`
 > - To disable the Multi-Column distribution (MCD) feature, run this command to change the database's compatibility level to AUTO. For example: `ALTER DATABASE SCOPED CONFIGURATION SET DW_COMPATIBILITY_LEVEL = AUTO;` Existing MCD tables will stay but become unreadable. Queries over MCD tables will return this error: `Related table/view is not readable because it distributes data on multiple columns and multi-column distribution is not supported by this product version or this feature is disabled.`
 >   - To regain access to MCD tables, enable the feature again.
 >   - To load data into a MCD table, use CTAS statement and the data source needs be Synapse SQL tables.  
-> - Using SSMS for [generating a script](../../ssms/scripting/generate-scripts-sql-server-management-studio.md) to create MCD tables is currently supported beyond SSMS version 19.
+> - [Generating a script](../../ssms/scripting/generate-scripts-sql-server-management-studio.md) to create MCD tables is currently supported SSMS version 19 and later versions.
 
 `DISTRIBUTION = ROUND_ROBIN`
 Distributes the rows evenly across all the distributions in a round-robin fashion. This behavior is the default for [!INCLUDE[ssazuresynapse-md](../../includes/ssazuresynapse-md.md)].

docs/t-sql/statements/set-recommendations-sql.md

@@ -0,0 +1,92 @@
+---
+title: "SET RECOMMENDATIONS (Transact-SQL)"
+description: "SET RECOMMENDATIONS enables or disables the Azure Synapse distribution advisor for the current session."
+author: mariyaali
+ms.author: mariyaali
+ms.reviewer: xiaoyul, wiassaf
+ms.date: 07/16/2023
+ms.service: synapse-analytics
+ms.topic: reference
+f1_keywords:
+  - "SET RECOMMENDATIONS"
+  - "RECOMMENDATIONS"
+helpviewer_keywords:
+  - "SET RECOMMENDATIONS"
+  - "RECOMMENDATIONS"
+dev_langs:
+  - "TSQL"
+monikerRange: "=azure-sqldw-latest"
+---
+# SET RECOMMENDATIONS (Transact-SQL)
+
+[!INCLUDE [asa](../../includes/applies-to-version/asa-dedicated-sqlpool-only.md)]
+
+Enables or disables the Azure Synapse distribution advisor for the current session. For instructions and samples on the use of the distribution advisor, see [Distribution Advisor in Azure Synapse SQL](/azure/synapse-analytics/sql/distribution-advisor).
+
+> [!NOTE]
+> Distribution Advisor is currently in preview for Azure Synapse Analytics. Preview features are meant for testing only and should not be used on production instances or production data. As a preview feature, Distribution Advisor is subject to undergo changes in behavior or functionality. Please also keep a copy of your test data if the data is important.
+  
+ :::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: [Transact-SQL syntax conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)  
+  
+## Syntax
+
+```syntaxsql
+SET RECOMMENDATIONS { ON | OFF };
+```  
+
+## Arguments
+
+#### ON
+Enables Distribution Advisor for the current client session. Subsequently run queries will be taken into consideration for distribution strategy recommendations.
+
+#### OFF
+Turns Distribution Advisor OFF for the current client session. Returns advice as a string.
+
+## Remarks
+
+Applies to [!INCLUDE [ssSDW](../../includes/ssazuresynapse_sqlpool_only.md)] only.
+
+Run this command when connected to a user database.
+
+## Permissions
+
+Requires membership in the public role.
+
+## Examples
+
+Following example will return distribution recommendation on selected TPC-DS queries. TPC-DS is an industry standard benchmark for analytical decision support workloads.
+
+First, begin the distribution advisor recommendation collection and run sample queries.
+
+```sql
+-- Step 1: Turn the distribution advisor ON for the current client session
+SET RECOMMENDATIONS ON;
+GO
+
+-- <insert your queries here, up to 100>
+SELECT ss_store_sk, COUNT(*) FROM store_sales, store WHERE ss_store_sk = s_store_sk GROUP BY ss_store_sk;
+
+SELECT cs_item_sk, COUNT(*) FROM catalog_sales, item WHERE cs_item_sk = i_item_sk  AND i_manufact_id > 100 GROUP BY cs_item_sk;
+
+SELECT * FROM dbo.reason;
+
+-- Turn the distribution advisor OFF for the current client session.
+SET RECOMMENDATIONS OFF;
+GO
+```
+
+Collect recommendations from the dynamic management view `sys.dm_pdw_distrib_advisor_results` for the current session. For example:
+
+```sql
+
+-- Step 2: view advice generated for the above workload
+DECLARE @sessionid nvarchar(100), @recommendation nvarchar(max);
+SELECT @sessionid = SESSION_ID();
+SELECT @recommendation = recommendation FROM sys.dm_pdw_distrib_advisor_results WHERE session_id = @sessionid;
+SELECT @recommendation;
+GO
+```
+
+## Next steps
+
+- [Distribution Advisor in Azure Synapse SQL](/azure/synapse-analytics/sql/distribution-advisor)

docs/toc.yml

@@ -18725,6 +18725,8 @@ items:
           href: t-sql/statements/set-query-governor-cost-limit-transact-sql.md
         - name: QUOTED_IDENTIFIER
           href: t-sql/statements/set-quoted-identifier-transact-sql.md
+        - name: RECOMMENDATIONS
+          href: t-sql/statements/set-recommendations-sql.md          
         - name: REMOTE_PROC_TRANSACTIONS
           href: t-sql/statements/set-remote-proc-transactions-transact-sql.md
         - name: RESULT SET CACHING