partition: add doc for global index

partitioned-table.md

@@ -1662,6 +1662,67 @@ CREATE TABLE t (a varchar(20), b blob,
 ERROR 1503 (HY000): A UNIQUE INDEX must include all columns in the table's partitioning function
 ```
 
+#### Global Index
+
+If you need to create unique indexes that **don't include all the columns used in the partition expressions**, you can achieve this by enabling the [tidb_enable_global_index](/system-variables.md#tidb_enable_global_index-new-in-v760) variable.
+
+Previously an index on partitioned tables are created for each partition, which is the reason for the limitation that all unique keys needs to include all partitioning columns. Since the uniqueness can only be enforced within each partition. A global index will be created on table level, so it can enforce uniqueness regardless of partitioning. Note that this has implications on partitioning management, DROP, TRUNCATE, REORGANIZE PARTITION will need to also manage the table level global index.
+
+After enabling this variable, any unique index created by the user that does not meet the above constraint will automatically be a global index.
+
+{{< copyable "sql" >}}
+
+```sql
+set tidb_enable_global_index = true;
+
+CREATE TABLE t1 (
+    col1 INT NOT NULL,
+    col2 DATE NOT NULL,
+    col3 INT NOT NULL,
+    col4 INT NOT NULL,
+    UNIQUE KEY uidx12(col1, col2),
+    UNIQUE KEY uidx3(col3)
+)
+PARTITION BY HASH(col3)
+PARTITIONS 4;
+```
+
+In the example above, the unique index `uidx12` will be implicitly a global index, but `uidx3` remains a regular unique index.
+
+It should be noted that a **clustered index** cannot be a global index:
+
+{{< copyable "sql" >}}
+
+```sql
+set tidb_enable_global_index = true;
+
+CREATE TABLE t1 (
+    col1 INT NOT NULL,
+    col2 DATE NOT NULL,
+    PRIMARY KEY (col2) clustered
+) PARTITION BY HASH(col1) PARTITIONS 5;
+```
+
+```sql
+ERROR 1503 (HY000): A CLUSTERED INDEX must include all columns in the table's partitioning function
+```
+
+The reason is that if the clustered index is a global index, the table will no longer be partitioned. This is because the key of the clustered index is also the record key which means it should be partition level, but the global index is on table level, which creates a conflict.
+
+Users can identify a global index by querying the `information_schema`.`tidb_indexes` table, aside from checking the table structure.
+
+```sql
+mysql> select * from information_schema.tidb_indexes where table_name='t1';
++--------------+------------+------------+----------+--------------+-------------+----------+---------------+------------+----------+------------+-----------+-----------+
+| TABLE_SCHEMA | TABLE_NAME | NON_UNIQUE | KEY_NAME | SEQ_IN_INDEX | COLUMN_NAME | SUB_PART | INDEX_COMMENT | Expression | INDEX_ID | IS_VISIBLE | CLUSTERED | IS_GLOBAL |
++--------------+------------+------------+----------+--------------+-------------+----------+---------------+------------+----------+------------+-----------+-----------+
+| test         | t1         |          0 | uidx12   |            1 | col1        |     NULL |               | NULL       |        1 | YES        | NO        |         1 |
+| test         | t1         |          0 | uidx12   |            2 | col2        |     NULL |               | NULL       |        1 | YES        | NO        |         1 |
+| test         | t1         |          0 | uidx3    |            1 | col3        |     NULL |               | NULL       |        2 | YES        | NO        |         0 |
++--------------+------------+------------+----------+--------------+-------------+----------+---------------+------------+----------+------------+-----------+-----------+
+3 rows in set (0.00 sec)
+```
+
 ### Partitioning limitations relating to functions
 
 Only the functions shown in the following list are allowed in partitioning expressions:

system-variables.md

@@ -2128,13 +2128,17 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1;
 
 ### tidb_enable_global_index <span class="version-mark">New in v7.6.0</span>
 
+> **Warning:**
+>
+> The feature controlled by this variable is an experimental feature. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub.
+
 - Scope: SESSION | GLOBAL
 - Persists to cluster: Yes
 - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
 - Type: Boolean
 - Default value: `OFF`
 - Possible values: `OFF`, `ON`
-- This variable controls whether to support creating `Global indexes` for partitioned tables. `Global index` is currently in the development stage. **It is not recommended to modify the value of this system variable**.
+- This variable controls whether to support creating `Global indexes` for partitioned tables. When this variable is enabled, TiDB could create unique indexes that do not contain all columns in the partition expressions.
 
 ### tidb_enable_non_prepared_plan_cache