*: refine placement documents

TOC.md

@@ -585,7 +585,7 @@
         - [`METRICS_SUMMARY`](/information-schema/information-schema-metrics-summary.md)
         - [`METRICS_TABLES`](/information-schema/information-schema-metrics-tables.md)
         - [`PARTITIONS`](/information-schema/information-schema-partitions.md)
-        - [`PLACEMENT_RULES`](/information-schema/information-schema-placement-rules.md)
+        - [`PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md)
         - [`PROCESSLIST`](/information-schema/information-schema-processlist.md)
         - [`REFERENTIAL_CONSTRAINTS`](/information-schema/information-schema-referential-constraints.md)
         - [`SCHEMATA`](/information-schema/information-schema-schemata.md)

information-schema/information-schema-placement-policies.md

@@ -0,0 +1,72 @@
+---
+title: PLACEMENT_POLICIES
+sgmmary: Learn the `PLACEMENT_POLICIES` information_schema table.
+---
+
+# PLACEMENT_POLICIES
+
+The `PLACEMENT_POLICIES` table provides information on all placement policies, refer [Placement Rules in SQL](/placement-rules-in-sql.md).
+
+{{< copyable "sql" >}}
+
+```sql
+USE information_schema;
+DESC placement_policies;
+```
+
+```sql
++----------------------+---------------+------+-----+---------+-------+
+| Field                | Type          | Null | Key | Default | Extra |
++----------------------+---------------+------+-----+---------+-------+
+| POLICY_ID            | bigint(64)    | NO   |     | <null>  |       |
+| CATALOG_NAME         | varchar(512)  | NO   |     | <null>  |       |
+| POLICY_NAME          | varchar(64)   | NO   |     | <null>  |       |
+| PRIMARY_REGION       | varchar(1024) | YES  |     | <null>  |       |
+| REGIONS              | varchar(1024) | YES  |     | <null>  |       |
+| CONSTRAINTS          | varchar(1024) | YES  |     | <null>  |       |
+| LEADER_CONSTRAINTS   | varchar(1024) | YES  |     | <null>  |       |
+| FOLLOWER_CONSTRAINTS | varchar(1024) | YES  |     | <null>  |       |
+| LEARNER_CONSTRAINTS  | varchar(1024) | YES  |     | <null>  |       |
+| SCHEDULE             | varchar(20)   | YES  |     | <null>  |       |
+| FOLLOWERS            | bigint(64)    | YES  |     | <null>  |       |
+| LEARNERS             | bigint(64)    | YES  |     | <null>  |       |
++----------------------+---------------+------+-----+---------+-------+
+12 rows in set (0.00 sec)
+```
+
+## Examples
+
+The `PLACEMENT_POLICIES` table only shows all placement policies. To view the canonical version of placement rules (including all placement policies and objects assigned placement policies), use the statement `SHOW PLACEMENT` instead:
+
+{{< copyable "sql" >}}
+
+```sql
+CREATE TABLE t1 (a INT); 
+CREATE PLACEMENT POLICY p1 primary_region="us-east-1" regions="us-east-1";
+CREATE TABLE t3 (a INT) PLACEMENT POLICY=p1;
+SHOW PLACEMENT; -- Shows all information. Includes table t3.
+SELECT * FROM information_schema.placement_policies; -- Only shows placement policies. Does not include t3.
+```
+
+```sql
+Query OK, 0 rows affected (0.09 sec)
+
+Query OK, 0 rows affected (0.11 sec)
+
+Query OK, 0 rows affected (0.08 sec)
+
++---------------+------------------------------------------------+------------------+
+| Target        | Placement                                      | Scheduling_State |
++---------------+------------------------------------------------+------------------+
+| POLICY p1     | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | NULL             |
+| TABLE test.t3 | PRIMARY_REGION="us-east-1" REGIONS="us-east-1" | PENDING          |
++---------------+------------------------------------------------+------------------+
+2 rows in set (0.00 sec)
+
++-----------+--------------+-------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+
+| POLICY_ID | CATALOG_NAME | POLICY_NAME | PRIMARY_REGION | REGIONS   | CONSTRAINTS | LEADER_CONSTRAINTS | FOLLOWER_CONSTRAINTS | LEARNER_CONSTRAINTS | SCHEDULE | FOLLOWERS | LEARNERS |
++-----------+--------------+-------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+
+| 1         | def          | p1          | us-east-1      | us-east-1 |             |                    |                      |                     |          | 2         | 0        |
++-----------+--------------+-------------+----------------+-----------+-------------+--------------------+----------------------+---------------------+----------+-----------+----------+
+1 rows in set (0.00 sec)
+```

information-schema/information-schema.md

@@ -76,7 +76,7 @@ Many `INFORMATION_SCHEMA` tables have a corresponding `SHOW` command. The benefi
 | [`METRICS_SUMMARY`](/information-schema/information-schema-metrics-summary.md)          | A summary of metrics extracted from Prometheus. |
 | `METRICS_SUMMARY_BY_LABEL`                                                              | See `METRICS_SUMMARY` table. |
 | [`METRICS_TABLES`](/information-schema/information-schema-metrics-tables.md)            | Provides the PromQL definitions for tables in `METRICS_SCHEMA`. |
-| [`PLACEMENT_RULES`](/information-schema/information-schema-placement-rules.md)          | Provides information on all objects that have explicit placement rules assigned. |
+| [`PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md)    | Provides all placement policies.                                 |
 | [`SEQUENCES`](/information-schema/information-schema-sequences.md)                      | The TiDB implementation of sequences is based on MariaDB. |
 | [`SLOW_QUERY`](/information-schema/information-schema-slow-query.md)                    | Provides information on slow queries on the current TiDB server. |
 | [`STATEMENTS_SUMMARY`](/statement-summary-tables.md)                                    | Similar to performance_schema statement summary in MySQL. |

placement-rules-in-sql.md

@@ -9,7 +9,7 @@ summary: Learn how to schedule placement of tables and partitions using SQL stat
 >
 > Placement Rules in SQL is an experimental feature introduced in v5.3.0. The syntax might change before its GA, and there might also be bugs. If you understand the risks, you can enable this experiment feature by executing `SET GLOBAL tidb_enable_alter_placement = 1;`.
 
-> **Note：**
+> **Note:**
 >
 > The implementation of *Placement Rules in SQL* relies on the *placement rules feature* of PD. For details, refer to [Configure Placement Rules](/configure-placement-rules.md). In the context of Placement Rules in SQL, *placement rules* might refer to *placement policies* attached to other objects, or to rules that are sent from TiDB to PD.
 
@@ -25,7 +25,7 @@ The detailed user scenarios are as follows:
 
 ## Specify placement rules
 
-To specify placement rules, first create a placement policy:
+To specify placement rules, first create a placement policy by [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md):
 
 ```sql
 CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us-east-1,us-west-1";
@@ -34,16 +34,28 @@ CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east-1" REGIONS="us
 Then attach the policy to a table or partition using either `CREATE TABLE` or `ALTER TABLE`. Then, the placement rules are specified on the table or the partition:
 
 ```sql
-CREATE TABLE t1 (a INT) PLACEMENT POLICY myplacementpolicy;
+CREATE TABLE t1 (a INT) PLACEMENT POLICY=myplacementpolicy;
 CREATE TABLE t2 (a INT);
-ALTER TABLE t2 PLACEMENT POLICY myplacementpolicy;
+ALTER TABLE t2 PLACEMENT POLICY=myplacementpolicy;
 ```
 
 A placement policy is not associated with any database schema and has the global scope. Therefore, assigning a placement policy does not require any additional privileges over the `CREATE TABLE` privilege.
 
+It is also possible to alter placement policies by [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md), and the changes will propagate to all objects with the corresponding policy.
+
+```sql
+ALTER PLACEMENT POLICY myplacementpolicy FOLLOWERS=5;
+```
+
+Finally, you can use [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md) to drop policies that are not attached to any table or partition:
+
+```sql
+DROP PLACEMENT POLICY myplacementpolicy;
+```
+
 ## View current placement rules
 
-If a table has placement rules attached, you can view the placement rules in the output of `SHOW CREATE TABLE`. To view the definition of the policy available, execute `SHOW CREATE PLACEMENT POLICY`:
+If a table has placement rules attached, you can view the placement rules in the output of [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md). To view the definition of the policy available, execute [`SHOW CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-show-create-placement-policy.md):
 
 ```sql
 tidb> SHOW CREATE TABLE t1\G
@@ -61,14 +73,34 @@ Create Policy: CREATE PLACEMENT POLICY myplacementpolicy PRIMARY_REGION="us-east
 1 row in set (0.00 sec)
 ```
 
+It is also possible to view definition of placement policies through [`INFORMATION_SCHEMA.PLACEMENT_POLICIES`](/information-schema/information-schema-placement-policies.md) table.
+
+```sql
+tidb> select * from information_schema.placement_policies\G
+***************************[ 1. row ]***************************
+POLICY_ID            | 1
+CATALOG_NAME         | def
+POLICY_NAME          | p1
+PRIMARY_REGION       | us-east-1
+REGIONS              | us-east-1,us-west-1
+CONSTRAINTS          | 
+LEADER_CONSTRAINTS   | 
+FOLLOWER_CONSTRAINTS | 
+LEARNER_CONSTRAINTS  | 
+SCHEDULE             | 
+FOLLOWERS            | 4
+LEARNERS             | 0
+1 row in set
+```
+
 The `information_schema.tables` and `information_schema.partitions` tables also include a column for `tidb_placement_policy_name`, which shows all objects with placement rules attached:
 
 ```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;
 ```
 
-Rules that are attached to objects are applied _asynchronously_. To view the current scheduling progress of placement, use [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md).
+Rules that are attached to objects are applied *asynchronously*. To view the current scheduling progress of placement, use [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md).
 
 ## Option reference
 
@@ -99,8 +131,11 @@ In addition to the placement options above, you can also use the advance configu
 
 | Option Name                | Description                                                                                    |
 | --------------| ------------ |
-| `CONSTRAINTS`              | A list of constraints that apply to all roles. For example, `CONSTRAINTS="[+disk=ssd]`.        |
-| `FOLLOWER_CONSTRAINTS`     | A list of constraints that only apply to followers.                                            |
+| `CONSTRAINTS`              | A list of constraints that apply to all roles. For example, `CONSTRAINTS="[+disk=ssd]`.       |
+| `LEADER_CONSTRAINTS`       | A list of constraints that only apply to leader.                                      |
+| `FOLLOWER_CONSTRAINTS`     | A list of constraints that only apply to followers.                                   |
+| `LEARNER_CONSTRAINTS`      | A list of constraints that only apply to learners.                                     |
+| `LEARNERS`                 | The number of learners. |
 
 ## Examples
 
@@ -135,19 +170,23 @@ To ensure that enough followers are placed in the primary region (`us-east-1`) s
 In addition to assigning placement options to tables, you can also assign the options to table partitions. For example:
 
 ```sql
+CREATE PLACEMENT POLICY p1 FOLLOWERS=5;
 CREATE PLACEMENT POLICY europe PRIMARY_REGION="eu-central-1" REGIONS="eu-central-1,eu-west-1";
 CREATE PLACEMENT POLICY northamerica PRIMARY_REGION="us-east-1" REGIONS="us-east-1";
 
 SET tidb_enable_list_partition = 1;
 CREATE TABLE t1 (
   country VARCHAR(10) NOT NULL,
   userdata VARCHAR(100) NOT NULL
-) PARTITION BY LIST COLUMNS (country) (
+) PLACEMENT POLICY=p1 PARTITION BY LIST COLUMNS (country) (
   PARTITION pEurope VALUES IN ('DE', 'FR', 'GB') PLACEMENT POLICY=europe,
   PARTITION pNorthAmerica VALUES IN ('US', 'CA', 'MX') PLACEMENT POLICY=northamerica
+  PARTITION pAsia VALUES IN ('CN', 'KR', 'JP')
 );
 ```
 
+If partitions have no attached policies, it will try to apply possibly existed policy on the table. For example, `pEurope` will apply `europe` policy, but `pAsia` will apply policy `p1` from table `t1`. If `t1` has no assigned policies, `pAsia` will not apply any policy, too.
+
 ### Set the default placement for a schema
 
 You can directly attach the default placement rules to a database schema. This works similar to setting the default character set or collation for a schema. Your specified placement options apply when no other options are specified. For example:
@@ -174,7 +213,7 @@ CREATE TABLE t4 (a INT);  -- Creates a table t4 with the default policy p3.
 ALTER PLACEMENT POLICY p3 FOLLOWERS=3; -- The table with policy p3 (t4) will have FOLLOWERS=3.
 ```
 
-You can use [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) to change a policy, and the changes will propagate to all objects with the corresponding policy.
+Note that this is different from inheritance between partitions and tables, where changing policy of tables will affect their partitions. Tables only inherit the policy of schema when it is created without attaching policies, and modify policies of schemas does not affect created tables.
 
 ### Advanced placement options
 
@@ -212,8 +251,9 @@ In dictionary format, constraints also indicate a number of instances that apply
 
 The following known limitations exist in the experimental release of Placement Rules in SQL:
 
-* Dumpling does not support dumping placement policies. See [issue #29371](https://github.com/pingcap/tidb/issues/29371).
-* TiDB tools, including Backup & Restore (BR), TiCDC, TiDB Lightning, and TiDB Data Migration (DM), do not yet support placement rules.
+* TiDB tools，including Backup & Restore (BR), TiDB Lightning, TiCDC and TiDB Binlog, does not support placement rules before TiDB 6.0.
+* Since TiDB 6.0, Backup & Restore (BR) supports imports and exports of placement rules.
+* Since TiDB 6.0, TiCDC and TiDB Binlog will work in clusters assigned placement rules, and will not synchronize rules to the downstream clusters.
 * Temporary tables do not support placement options.
 * Syntactic sugar rules are permitted for setting `PRIMARY_REGION` and `REGIONS`. In the future, we plan to add varieties for `PRIMARY_RACK`, `PRIMARY_ZONE`, and `PRIMARY_HOST`. See [issue #18030](https://github.com/pingcap/tidb/issues/18030).
 * TiFlash learners are not configurable through Placement Rules syntax.