From c99589e77d2f7ab862dfe897d30408f0ee80335e Mon Sep 17 00:00:00 2001
From: JoyinQin <56883733+Joyinqin@users.noreply.github.com>
Date: Thu, 3 Sep 2020 22:29:35 +0800
Subject: [PATCH 1/2] optimizer-hints: add docs for `nth_plan()` hint

---
 optimizer-hints.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/optimizer-hints.md b/optimizer-hints.md
index 6bcaf518b17f3..07f19cd2e32b6 100644
--- a/optimizer-hints.md
+++ b/optimizer-hints.md
@@ -302,7 +302,7 @@ In addition to this hint, setting the `tidb_replica_read` environment variable t
 
 ### IGNORE_PLAN_CACHE()
 
-`IGNORE_PLAN_CACHE()` reminds the optimizer not to use the Plan Cache when handling the current `prepare` statement.
+The `IGNORE_PLAN_CACHE()` hint reminds the optimizer not to use the Plan Cache when handling the current `prepare` statement.
 
 This hint is used to temporarily disable the Plan Cache for a certain type of queries when [prepare-plan-cache](/tidb-configuration-file.md#prepared-plan-cache) is enabled.
 
@@ -313,3 +313,23 @@ In the following example, the Plan Cache is forcibly disabled when executing the
 ```sql
 prepare stmt from 'select  /*+ IGNORE_PLAN_CACHE() */ * from t where t.id = ?';
 ```
+
+### NTH_PLAN(N)
+
+The `NTH_PLAN(N)` hint reminds the optimizer to select the `N`th physical plan found in the physical optimization stage. `N` must be a positive integer.
+
+If the specified `N` exceeds the search range of the physical optimization stage, TiDB will return a warning and select the optimal physical plan based on the same strategy as when this hint does not exist.
+
+This hint does not take effect when the cascades planner is enabled.
+
+In the following example, the optimizer is forcibly selected the third physical plan found in the physical optimization stage:
+
+{{< copyable "sql" >}}
+
+```sql
+SELECT /*+ NTH_PLAN(3) */ count(*) from t where a > 5;
+```
+
+> **Note:**
+>
+> `NTH_PLAN(N)` is mainly used for testing, and its compatibility is not guaranteed in later versions, so proceed **with caution**.

From dca5655a19dc2724311e9d000e9c9a4adc989092 Mon Sep 17 00:00:00 2001
From: JoyinQ <56883733+Joyinqin@users.noreply.github.com>
Date: Fri, 4 Sep 2020 15:44:50 +0800
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>
---
 optimizer-hints.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/optimizer-hints.md b/optimizer-hints.md
index 07f19cd2e32b6..a227c7d7ac6b8 100644
--- a/optimizer-hints.md
+++ b/optimizer-hints.md
@@ -316,13 +316,13 @@ prepare stmt from 'select  /*+ IGNORE_PLAN_CACHE() */ * from t where t.id = ?';
 
 ### NTH_PLAN(N)
 
-The `NTH_PLAN(N)` hint reminds the optimizer to select the `N`th physical plan found in the physical optimization stage. `N` must be a positive integer.
+The `NTH_PLAN(N)` hint reminds the optimizer to select the `N`th physical plan found during the physical optimization. `N` must be a positive integer.
 
-If the specified `N` exceeds the search range of the physical optimization stage, TiDB will return a warning and select the optimal physical plan based on the same strategy as when this hint does not exist.
+If the specified `N` is beyond the search range of the physical optimization, TiDB will return a warning and select the optimal physical plan based on the strategy that ignores this hint.
 
 This hint does not take effect when the cascades planner is enabled.
 
-In the following example, the optimizer is forcibly selected the third physical plan found in the physical optimization stage:
+In the following example, the optimizer is forced to select the third physical plan found during the physical optimization:
 
 {{< copyable "sql" >}}
 
@@ -332,4 +332,4 @@ SELECT /*+ NTH_PLAN(3) */ count(*) from t where a > 5;
 
 > **Note:**
 >
-> `NTH_PLAN(N)` is mainly used for testing, and its compatibility is not guaranteed in later versions, so proceed **with caution**.
+> `NTH_PLAN(N)` is mainly used for testing, and its compatibility is not guaranteed in later versions. Use this hint **with caution**.