remove direct placement (#8230)

information-schema/information-schema-placement-rules.md

@@ -5,7 +5,7 @@ summary: 了解 information_schema 表 `PLACEMENT_RULES`。
 
 # PLACEMENT_RULES
 
-`PLACEMENT_RULES` 表展示所有已显式配置的 [Placement Rules in SQL](/placement-rules-in-sql.md) 信息，包括通过放置策略 (placement policy) 和通过直接放置 (directly placement) 进行配置的信息。
+`PLACEMENT_RULES` 表展示所有已显式配置的 [Placement Rules in SQL](/placement-rules-in-sql.md) 信息，即所有放置策略 (placement policy) 的信息。
 
 {{< copyable "sql" >}}
 
@@ -39,17 +39,16 @@ DESC placement_rules;
 
 ## 示例
 
-`PLACEMENT_RULES` 表只展示显式配置的规则。如要查看 Placement Rules 放置规则的规范版本（包括附加到表格的放置策略），请改用 `SHOW PLACEMENT` 语句：
+`PLACEMENT_RULES` 表只展示已显式配置的规则。如要查看 Placement Rules 放置规则的规范版本（包括绑定了对象的放置策略），请改用 `SHOW PLACEMENT` 语句：
 
 {{< copyable "sql" >}}
 
 ```sql
 CREATE TABLE t1 (a INT);
-CREATE TABLE t2 (a INT) primary_region="us-east-1" regions="us-east-1";
 CREATE PLACEMENT POLICY p1 primary_region="us-east-1" regions="us-east-1";
-CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1;
-SHOW PLACEMENT; -- 包含 t3。
-SELECT * FROM information_schema.placement_rules; -- 不包含 t3。
+CREATE TABLE t2 (a INT) PLACEMENT POLICY=p1;
+SHOW PLACEMENT; -- 包含 t2。
+SELECT * FROM information_schema.placement_rules; -- 不包含 t2。
 ```
 
 ```sql
@@ -66,15 +65,13 @@ Query OK, 0 rows affected (0.11 sec)
 +---------------+------------------------------------------------+
 | POLICY p1     | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" |
 | TABLE test.t2 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" |
-| TABLE test.t3 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" |
 +---------------+------------------------------------------------+
-3 rows in set (0.00 sec)
+2 rows in set (0.00 sec)
 
 +-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+
 | POLICY_ID | CATALOG_NAME | POLICY_NAME | SCHEMA_NAME | TABLE_NAME | PARTITION_NAME | PRIMARY_REGION | REGIONS   | CONSTRAINTS | LEADER_CONSTRAINTS | FOLLOWER_CONSTRAINTS | LEARNER_CONSTRAINTS | SCHEDULE | FOLLOWERS | LEARNERS |
 +-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+
 |         3 | def          | p1          | NULL        | NULL       | NULL           | us-east-1      | us-east-1 |             |                    |                      |                     |          |         0 |        0 |
-|      NULL | def          | NULL        | test        | t2         | NULL           | us-east-1      | us-east-1 |             |                    |                      |                     |          |         0 |        0 |
 +-----------+--------------+-------------+-------------+------------+----------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+
 2 rows in set (0.00 sec)
 ```

placement-rules-in-sql.md

@@ -11,6 +11,10 @@ summary: 了解如何通过 SQL 接口调度表和分区的放置位置。
 
 Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群中的放置位置。通过该功能，用户可以将表和分区指定部署至不同的地域、机房、机柜、主机。适用场景包括低成本优化数据高可用策略、保证本地的数据副本可用于本地 Stale Read 读取、遵守数据本地要求等。
 
+> **注意：**
+>
+> Placement Rules in SQL 底层的实现依赖 PD 提供的放置规则 (placement rules) 功能，参考 [Placement Rules 使用文档](/configure-placement-rules.md)。在 Placement Rules in SQL 语境下，放置规则既可以代指绑定对象的放置策略 (placement policy)，也可以代指 TiDB 发给 PD 的放置规则。
+
 该功能可以实现以下业务场景：
 
 - 合并多个不同业务的数据库，大幅减少数据库常规运维管理的成本
@@ -19,23 +23,51 @@ Placement Rules in SQL 特性用于通过 SQL 接口配置数据在 TiKV 集群
 - 把热点数据的 leader 放到高性能的 TiKV 实例上
 - 将冷数据分离到不同的存储中以提高可用性
 
-## 指定放置选项
+## 指定放置规则
+
+指定放置规则，首先需要创建放置策略 (placement policy)。
+
+```sql
+CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
+```
+
+然后可以使用 `CREATE TABLE` 或者 `ALTER TABLE` 将规则绑定至表或分区表，这样就在表或分区上指定了放置规则：
+
+```sql
+CREATE TABLE t1 (a INT) PLACEMENT POLICY myplacementpolicy;
+CREATE TABLE t2 (a INT);
+ALTER TABLE t2 PLACEMENT POLICY myplacementpolicy;
+```
+
+`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置规则时，无需任何额外的权限。
 
-要使用 Placement Rules in SQL 特性，你需要在 SQL 语句中指定一个或多个放置选项 (placement option)。可通过*直接放置 (direct placement)* 或*放置策略 (placement policy)* 来指定放置选项。
+## 查看放置规则
 
-以下示例中，表 `t1` 和 `t2` 的放置规则相同。`t1` 是通过直接放置指定的规则，而 `t2` 是通过放置策略来指定的规则。
+如果一张表绑定了放置规则，你可以用 `SHOW CREATE TABLE` 来查看。还可以用 `SHOW CREATE PLACEMENT POLICY` 来查看已经创建的规则。
 
 ```sql
-CREATE TABLE t1 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
-CREATE PLACEMENT POLICY eastandwest PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
-CREATE TABLE t2 (a INT) PLACEMENT POLICY=eastandwest;
+tidb> SHOW CREATE TABLE t1\G
+*************************** 1. row ***************************
+       Table: t1
+Create Table: CREATE TABLE `t1` (
+  `a` int(11) DEFAULT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin /*T![placement] PLACEMENT POLICY=`myplacementpolicy` */
+1 row in set (0.00 sec)
+tidb> SHOW CREATE PLACEMENT POLICY myplacementpolicy\G
+*************************** 1. row ***************************
+       Policy: myplacementpolicy
+Create Policy: CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1"
+1 row in set (0.00 sec)
 ```
 
-为了能够更轻松地管理放置规则，推荐使用放置策略来指定规则。当你通过 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 更改放置策略后，此更改会自动传播至所有数据库对象。
+`information_schema.tables` 表和 `information_schema.partitions` 表也有一列 `tidb_placement_policy_name`，用于展示所有绑定了放置规则的对象：
 
-如果你使用直接放置选项，你需要为每个对象（例如表和分区）都单独更改放置规则。
+```sql
+SELECT * FROM information_schema.tables WHERE tidb_placement_policy_name IS NOT NULL;
+SELECT * FROM information_schema.partitions WHERE tidb_placement_policy_name IS NOT NULL;
+```
 
-`PLACEMENT POLICY` 为全局作用域，不与任何数据库表结构相关联。因此，通过 `CREATE TABLE` 指定放置策略时，无需任何额外的权限。
+所有绑定规则的对象都是异步调度的。可以用 [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) 来查看放置规则的调度进度。
 
 ## 放置选项参考
 
@@ -62,7 +94,7 @@ CREATE TABLE t2 (a INT) PLACEMENT POLICY=eastandwest;
 | `SCHEDULE`                 |  用于调度 follower 放置位置的策略。可选值为 `EVEN`（默认值）或 `MAJORITY_IN_PRIMARY`。 |
 | `FOLLOWERS`                |  Follower 的数量。例如 `FOLLOWERS=2` 表示数据有 3 个副本（2 个 follower 和 1 个 leader）。 |
 
-除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置](#高级放置)。
+除以上配置选项外，你还可以使用高级配置，详细介绍见[高级放置选项](#高级放置选项)。
 
 | 选项名                | 描述                                                                                    |
 |----------------------------|------------------------------------------------------------------------------------------------|
@@ -99,7 +131,7 @@ CREATE TABLE t1 (a INT) PLACEMENT POLICY=eastandwest;
 >
 > 以下示例使用的 List 分区目前为 TiDB 实验特性。在表的分区功能中，要求主键里包含所有分区函数中使用的列。
 
-除了将放置选项分配给表之外，你还可以将选项分配给表分区。示例如下：
+除了给表绑定放置策略之外，你还可以给表分区绑定放置策略。示例如下：
 
 ```sql
 CREATE PLACEMENT POLICY europe PRIMARY_REGION="eu-central-1" REGIONS="eu-central-1,eu-west-1";
@@ -117,25 +149,33 @@ CREATE TABLE t1 (
 
 ### 为数据库配置默认的放置规则
 
-你可以为某个数据库指定默认的放置选项，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下：
+你可以为某个数据库指定默认的放置策略，类似于为数据库设置默认字符集或排序规则。如果没有指定其他选项，就会使用数据库上指定的配置。示例如下：
 
 ```sql
-CREATE TABLE t1 (a INT);  -- 创建表 t1，且未指定放置选项。
+CREATE PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2";  -- 创建放置策略
+
+CREATE PLACEMENT POLICY p2 FOLLOWERS=4;
+
+CREATE PLACEMENT POLICY p3 FOLLOWERS=2;
+
+CREATE TABLE t1 (a INT);  -- 创建表 t1，且未指定放置规则。
+
+ALTER DATABASE test POLICY=p2;  -- 更改默认的放置规则，但更改不影响已有的表 t1。
 
-ALTER DATABASE test FOLLOWERS=4;  -- 更改默认的放置选项，但更改不影响已有的表 t1。
+CREATE TABLE t2 (a INT);  -- 创建表 t2，默认的放置策略 p2 在 t2 上生效。
 
-CREATE TABLE t2 (a INT);  -- 创建表 t2，默认的放置规则 FOLLOWERS=4 在 t2 上生效。
+CREATE TABLE t3 (a INT) POLICY=p1;  -- 创建表 t3。因为语句中已经指定了其他放置规则，默认的 p2 策略在 t3 上不生效。
 
-CREATE TABLE t3 (a INT) PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-east-2";  -- 创建表 t3。因为语句中已经指定了其他放置规则，默认的 FOLLOWERS=4 规则在 t3 上不生效。
+ALTER DATABASE test POLICY=p3;  -- 再次更改默认的放置规则，此更改不影响已有的表。
 
-ALTER DATABASE test FOLLOWERS=2;  -- 再次更改默认的放置选项，此更改不影响已有的表。
+CREATE TABLE t4 (a INT);  -- 创建表 t4，默认的放置策略 p3 生效。
 
-CREATE TABLE t4 (a INT);  -- 创建表 t4，默认的放置规则 FOLLOWERS=2 生效。
+ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- 绑定策略 p3 的表，也就是 t4，会采用 FOLLOWERS=3。
 ```
 
-由于只有在创建表时才会从数据库继承放置选项，因此推荐使用 `PLACEMENT POLICY` 放置策略来设置默认的放置选项。使用后，用户可以通过改动放置策略，改变继承自数据库的放置选项。
+用户可以通过使用 [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) 改变放置策略，从而改变已从数据库继承放置规则的表。
 
-### 高级放置
+### 高级放置选项
 
 放置选项 `PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 可满足数据放置的基本需求，但会缺乏一些灵活性。在较复杂的场景下，若需要更灵活地放置数据，可以使用高级放置选项 `CONSTRAINTS` 和 `FOLLOWER_CONSTRAINTS`。`PRIMARY_REGION`、`REGIONS` 和 `SCHEDULE` 选项不可与 `CONSTRAINTS` 选项同时指定，否则会报错。
 
@@ -173,7 +213,7 @@ PARTITION BY RANGE( YEAR(purchased) ) (
 
 * Dumpling 不支持导出放置策略，见 [issue #29371](https://github.com/pingcap/tidb/issues/29371)。
 * TiDB 生态工具，包括 Backup & Restore (BR)、TiCDC、TiDB Lightning 和 TiDB Data Migration (DM)，不支持放置规则。
-* 临时表不支持放置选项，直接放置和放置策略均不支持。
+* 临时表不支持放置规则。
 * 设置 `PRIMARY_REGION` 和 `REGIONS` 时允许存在语法糖。但在未来版本中，我们计划为 `PRIMARY_RACK`、`PRIMARY_ZONE` 和 `PRIMARY_HOST` 添加变体支持，见 [issue #18030](https://github.com/pingcap/tidb/issues/18030)。
 * 不能通过放置规则语法配置 TiFlash 副本。
 * 放置规则仅保证静态数据被放置在正确的 TiKV 节点上。该规则不保证传输中的数据（通过用户查询或内部操作）只出现在特定区域内。

sql-statements/sql-statement-alter-placement-policy.md

@@ -9,7 +9,14 @@ summary: TiDB 数据库中 ALTER PLACEMENT POLICY 的使用概况。
 >
 > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。
 
-`ALTER PLACEMENT POLICY` 用于修改已创建的放置策略。此修改会自动更新至所有使用这些放置策略的表和分区。
+`ALTER PLACEMENT POLICY` 用于修改已创建的放置策略。此修改会自动更新至所有绑定这些放置策略的表和分区。
+
+`ALTER PLACEMENT POLICY` 会完全替换之前定义的规则，而不会和之前的规则合并，比如在下面的例子中，`FOLLOWERS=4` 就被 `ALTER PLACEMENT POLICY` 语句覆盖了：
+
+```sql
+CREATE PLACEMENT POLICY p1 FOLLOWERS=4;
+ALTER PLACEMENT POLICY p1 PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
+```
 
 ## 语法图
 
@@ -21,11 +28,11 @@ PolicyName ::=
     Identifier
 
 PlacementOptionList ::=
-    DirectPlacementOption
-|   PlacementOptionList DirectPlacementOption
-|   PlacementOptionList ',' DirectPlacementOption
+    PlacementOption
+|   PlacementOptionList PlacementOption
+|   PlacementOptionList ',' PlacementOption
 
-DirectPlacementOption ::=
+PlacementOption ::=
     "PRIMARY_REGION" EqOpt stringLit
 |   "REGIONS" EqOpt stringLit
 |   "FOLLOWERS" EqOpt LengthNum

sql-statements/sql-statement-create-placement-policy.md

@@ -9,7 +9,7 @@ summary: TiDB 数据库中 CREATE PLACEMENT POLICY 的使用概况。
 >
 > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。
 
-`CREATE PLACEMENT POLICY` 用于创建命名的放置策略，随后可以将该策略分配给表、分区或数据库。
+`CREATE PLACEMENT POLICY` 用于创建命名的放置策略，随后可以将该策略绑定到表、分区或数据库上。
 
 ## 语法图
 
@@ -21,11 +21,11 @@ PolicyName ::=
     Identifier
 
 PlacementOptionList ::=
-    DirectPlacementOption
-|   PlacementOptionList DirectPlacementOption
-|   PlacementOptionList ',' DirectPlacementOption
+    PlacementOption
+|   PlacementOptionList PlacementOption
+|   PlacementOptionList ',' PlacementOption
 
-DirectPlacementOption ::=
+PlacementOption ::=
     "PRIMARY_REGION" EqOpt stringLit
 |   "REGIONS" EqOpt stringLit
 |   "FOLLOWERS" EqOpt LengthNum

sql-statements/sql-statement-drop-placement-policy.md

@@ -23,20 +23,20 @@ PolicyName ::=
 
 ## 示例
 
-删除放置策略时，确保该策略未被任何表或分区引用，否则会删除失败。
+删除放置规则时，确保该策略未被任何表或分区引用，否则会删除失败。
 
 {{< copyable "sql" >}}
 
 ```sql
 CREATE PLACEMENT POLICY p1 FOLLOWERS=4;
 CREATE TABLE t1 (a INT PRIMARY KEY) PLACEMENT POLICY=p1;
-DROP PLACEMENT POLICY p1;  -- 该语句执行失败，因为放置策略 p1 被引用。
+DROP PLACEMENT POLICY p1;  -- 该语句执行失败，因为放置规则 p1 被引用。
 
--- 查看引用放置策略的表和分区。
+-- 查看引用放置规则的表和分区。
 SELECT table_schema, table_name FROM information_schema.tables WHERE tidb_placement_policy_name='p1';
 SELECT table_schema, table_name FROM information_schema.partitions WHERE tidb_placement_policy_name='p1';
 
-ALTER TABLE t1 PLACEMENT POLICY=default;  -- 移除表 t1 上的默认放置策略。
+ALTER TABLE t1 PLACEMENT POLICY=default;  -- 移除表 t1 上的默认放置规则。
 DROP PLACEMENT POLICY p1;  -- 执行成功。
 ```
 

sql-statements/sql-statement-show-create-placement-policy.md

@@ -9,7 +9,7 @@ summary: TiDB 数据库中 SHOW CREATE PLACEMENT POLICY 的使用概况。
 >
 > Placement Rules in SQL 是 TiDB 在 v5.3.0 中引入的实验特性，其语法在 GA 前可能会发生变化，还可能存在 bug。如果你知晓潜在的风险，可通过执行 `SET GLOBAL tidb_enable_alter_placement = 1;` 来开启该实验特性。
 
-`SHOW CREATE PLACEMENT POLICY` 语句可用于查看放置策略当前的定义，并在另一个 TiDB 集群中重新创建该策略。
+`SHOW CREATE PLACEMENT POLICY` 语句可用于查看放置规则当前的定义，并在另一个 TiDB 集群中重新创建该策略。
 
 ## 语法图