本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 提示
<a name="sql-commands-hints-spark"></a>

SQL 分析的提示提供最佳化指令，可引導 中的查詢執行策略 AWS Clean Rooms，讓您改善查詢效能並降低運算成本。提示會建議 Spark 分析引擎應如何產生其執行計畫。

## 語法
<a name="hints-syntax"></a>

```
SELECT /*+ hint_name(parameters), hint_name(parameters) */ column_list
FROM table_name;
```

提示使用註解樣式語法內嵌在 SQL 查詢中，且必須直接放置在 SELECT 關鍵字之後。

## 支援的提示類型
<a name="supported-hint-types"></a>

AWS Clean Rooms 支援兩種類型的提示：聯結提示和分割提示。

**Topics**
+ [聯結提示](join-hints.md)
+ [分割提示](partitioning-hints.md)

# 聯結提示
<a name="join-hints"></a>

聯結提示會建議查詢執行的聯結策略。語法、引數和一些範例來自 [Apache Spark SQL 參考](https://spark.apache.org/docs/latest/sql-ref-syntax-qry-select-hints.html#join-hints)，以取得詳細資訊

### BROADCAST
<a name="broadcast-hint"></a>

建議使用 AWS Clean Rooms 廣播聯結。無論 autoBroadcastJoinThreshold 為何，都會廣播具有提示的聯結端。如果聯結的兩端都有廣播提示，則具有較小大小 （根據統計資料） 的那一側將廣播。

*別名：*BROADCASTJOIN、MAPJOIN

*參數：*資料表識別符 （選用）

*範例*：

```
-- Broadcast a specific table
SELECT /*+ BROADCAST(students) */ e.name, s.course
FROM employees e JOIN students s ON e.id = s.id;

-- Broadcast multiple tables
SELECT /*+ BROADCASTJOIN(s, d) */ *
FROM employees e
JOIN students s ON e.id = s.id
JOIN departments d ON e.dept_id = d.id;
```

### MERGE
<a name="merge-hint"></a>

建議使用 AWS Clean Rooms 隨機排序合併聯結。

*別名：*SHUFFLE\$1MERGE、MERGEJOIN

*參數：*資料表識別符 （選用）

*範例*：

```
-- Use merge join for a specific table
SELECT /*+ MERGE(employees) */ *
FROM employees e JOIN students s ON e.id = s.id;

-- Use merge join for multiple tables
SELECT /*+ MERGEJOIN(e, s, d) */ *
FROM employees e
JOIN students s ON e.id = s.id
JOIN departments d ON e.dept_id = d.id;
```

### SHUFFLE\$1HASH
<a name="shuffle-hash-hint"></a>

建議使用 AWS Clean Rooms 隨機雜湊聯結。如果兩端都有隨機雜湊提示，則查詢最佳化工具會選擇較小的端 （根據統計資料） 做為建置端。

*參數：*資料表識別符 （選用）

*範例*：

```
-- Use shuffle hash join
SELECT /*+ SHUFFLE_HASH(students) */ *
FROM employees e JOIN students s ON e.id = s.id;
```

### SHUFFLE\$1REPLICATE\$1NL
<a name="shuffle-replicate-nl-hint"></a>

建議使用 AWS Clean Rooms shuffle-and-replicate巢狀迴圈聯結。

*參數：*資料表識別符 （選用）

*範例*：

```
-- Use shuffle-replicate nested loop join
SELECT /*+ SHUFFLE_REPLICATE_NL(students) */ *
FROM employees e JOIN students s ON e.id = s.id;
```

### Spark SQL 中的提示疑難排解
<a name="join-hint-warning-cases"></a>

下表顯示未在 SparkSQL 中套用提示的常見案例。如需其他資訊，請參閱 [考量和限制](sql-commands-hints-spark.md#hints-usage-notes)。

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/clean-rooms/latest/sql-reference/join-hints.html)

# 分割提示
<a name="partitioning-hints"></a>

分割提示控制執行器節點之間的資料分佈。指定多個分割提示時，會將多個節點插入邏輯計畫，但最左邊的提示是由最佳化工具挑選。

### COALESCE
<a name="coalesce-hint"></a>

將分割區數量減少為指定的分割區數量。

*參數：*數值 （必要） - 必須是介於 1 和 2147483647 之間的正整數

*範例*：

```
-- Reduce to 5 partitions
SELECT /*+ COALESCE(5) */ employee_id, salary
FROM employees;
```

### 保留
<a name="repartition-hint"></a>

使用指定的分割表達式，將資料重新分割至指定的分割區數量。使用循環配置分佈。

*參數：*
+ 數值 （選用） - 分割區數量；必須是介於 1 和 2147483647 之間的正整數
+ 資料欄識別符 （選用） - 要分割的資料欄；這些資料欄必須存在於輸入結構描述中。
+ 如果同時指定兩者，數值必須首先出現

*範例*：

```
-- Repartition to 10 partitions
SELECT /*+ REPARTITION(10) */ *
FROM employees;

-- Repartition by column
SELECT /*+ REPARTITION(department) */ *
FROM employees;

-- Repartition to 8 partitions by department
SELECT /*+ REPARTITION(8, department) */ *
FROM employees;

-- Repartition by multiple columns
SELECT /*+ REPARTITION(8, department, location) */ *
FROM employees;
```

### REPARTITION\$1BY\$1RANGE
<a name="repartition-by-range-hint"></a>

使用指定資料欄上的範圍分割，將資料重新分割至指定數量的分割區。

*參數：*
+ 數值 （選用） - 分割區數量；必須是介於 1 和 2147483647 之間的正整數
+ 資料欄識別符 （選用） - 要分割的資料欄；這些資料欄必須存在於輸入結構描述中。
+ 如果同時指定兩者，數值必須首先出現

*範例*：

```
SELECT /*+ REPARTITION_BY_RANGE(10) */ *
FROM employees;

-- Repartition by range on age column
SELECT /*+ REPARTITION_BY_RANGE(age) */ *
FROM employees;

-- Repartition to 5 partitions by range on age
SELECT /*+ REPARTITION_BY_RANGE(5, age) */ *
FROM employees;

-- Repartition by range on multiple columns
SELECT /*+ REPARTITION_BY_RANGE(5, age, salary) */ *
FROM employees;
```

### REBALANCE
<a name="rebalance-hint"></a>

重新平衡查詢結果輸出分割區，讓每個分割區的大小合理 （不會太小也不會太大）。這是最佳嘗試操作：如果有扭曲， AWS Clean Rooms 會分割扭曲的分割區，使其不會太大。當您需要將查詢結果寫入資料表，以避免檔案太小或太大時，此提示很有用。

*參數：*
+ 數值 （選用） - 分割區數量；必須是介於 1 和 2147483647 之間的正整數
+ 資料欄識別符 （選用） - 資料欄必須出現在 SELECT 輸出清單中
+ 如果同時指定兩者，數值必須首先出現

*範例*：

```
-- Rebalance to 10 partitions
SELECT /*+ REBALANCE(10) */ employee_id, name
FROM employees;

-- Rebalance by specific columns in output
SELECT /*+ REBALANCE(employee_id, name) */ employee_id, name
FROM employees;

-- Rebalance to 8 partitions by specific columns
SELECT /*+ REBALANCE(8, employee_id, name) */ employee_id, name, department
FROM employees;
```

## 結合多個提示
<a name="combining-multiple-hints"></a>

您可以在單一查詢中指定多個提示，方法是使用逗號分隔它們：

```
-- Combine join and partitioning hints
SELECT /*+ BROADCAST(d), REPARTITION(8) */ e.name, d.dept_name
FROM employees e JOIN departments d ON e.dept_id = d.id;

-- Multiple join hints
SELECT /*+ BROADCAST(s), MERGE(d) */ *
FROM employees e
JOIN students s ON e.id = s.id
JOIN departments d ON e.dept_id = d.id;

-- Hints within separate hint blocks within the same query
SELECT /*+ REPARTITION(100) */ /*+ COALESCE(500) */ /*+ REPARTITION_BY_RANGE(3, c) */ * FROM t;
```

## 考量和限制
<a name="hints-usage-notes"></a>
+ 提示是最佳化建議，而不是命令。查詢最佳化工具可能會根據資源限制或執行條件忽略提示。
+ 提示直接內嵌在 CreateAnalysisTemplate 和 StartProtectedQuery APIs SQL 查詢字串中。
+ 提示必須直接放在 SELECT 關鍵字後面。
+ 使用提示不支援具名參數，並會擲回例外狀況。
+ REPARTITION amd REPARTITION\$1BY\$1RANGE 提示中的資料欄名稱必須存在於輸入結構描述中。
+ REBALANCE 提示中的資料欄名稱必須出現在 SELECT 輸出清單中。
+ 數值參數必須是介於 1 和 2147483647 之間的正整數。不支援 *1e1* 等科學表示法
+ 差異隱私權 SQL 查詢不支援提示。
+ PySpark 任務不支援 SQL 查詢的提示。若要在 PySpark 任務中提供執行計畫的指令，請使用資料框架 API。如需詳細資訊，請參閱 [Apache Spark DataFrame API 文件](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.DataFrame.hint.html)。