Document descending-order index support (pingcap/tidb#2519)

mysql-compatibility.md

@@ -66,7 +66,7 @@ You can try out TiDB features on [TiDB Playground](https://play.tidbcloud.com/?u
 + `HANDLER` statement
 + `CREATE TABLESPACE` statement
 + "Session Tracker: Add GTIDs context to the OK packet"
-+ Descending Index [#2519](https://github.com/pingcap/tidb/issues/2519)
++ Descending Index [#2519](https://github.com/pingcap/tidb/issues/2519) (supported since v9.0.0; controlled by the [`tidb_enable_descending_index`](/system-variables.md#tidb_enable_descending_index-new-in-v900) system variable)
 + `SKIP LOCKED` syntax [#18207](https://github.com/pingcap/tidb/issues/18207)
 + Lateral derived tables [#40328](https://github.com/pingcap/tidb/issues/40328)
 + JOIN ON subquery [#11414](https://github.com/pingcap/tidb/issues/11414)

sql-statements/sql-statement-create-index.md

@@ -392,7 +392,7 @@ The system variables associated with the `CREATE INDEX` statement are `tidb_ddl_
     > Currently, only {{{ .starter }}} and {{{ .essential }}} instances in certain AWS regions support [`FULLTEXT` syntax and indexes](https://docs.pingcap.com/tidbcloud/vector-search-full-text-search-sql).
 
 * TiDB accepts index types such as `HASH`, `BTREE` and `RTREE` in syntax for compatibility with MySQL, but ignores them.
-* Descending indexes are not supported (similar to MySQL 5.7).
+* Descending indexes are supported when the [`tidb_enable_descending_index`](/system-variables.md#tidb_enable_descending_index-new-in-v900) system variable is set to `ON` (default `OFF`). When this variable is `OFF`, the `DESC` keyword on individual index columns is parsed but ignored, matching MySQL 5.7 behavior. When `ON`, columns marked `DESC` are stored in descending order. This allows composite indexes such as `INDEX(a ASC, b DESC)` to satisfy `ORDER BY a ASC, b DESC` with a single forward index scan and no additional `Sort` operator. This brings TiDB closer to MySQL 8.0 compatibility for descending indexes. Expression and `FULLTEXT` indexes do not support `DESC`.
 * Adding the primary key of the `CLUSTERED` type to a table is not supported. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 * Expression indexes are incompatible with views. When a query is executed using a view, the expression index cannot be used at the same time.
 * Expression indexes have compatibility issues with bindings. When the expression of an expression index has a constant, the binding created for the corresponding query expands its scope. For example, suppose that the expression in the expression index is `a+1`, and the corresponding query condition is `a+1 > 2`. In this case, the created binding is `a+? > ?`, which means that the query with the condition such as `a+2 > 2` is also forced to use the expression index and results in a poor execution plan. In addition, this also affects the baseline capturing and baseline evolution in SQL Plan Management (SPM).

system-variables.md

@@ -2172,6 +2172,20 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi
 - Default value: `ON`. Before v8.3.0, the default value is `OFF`.
 - This variable controls whether to enable TiDB to collect `PREDICATE COLUMNS`. After enabling the collection, if you disable it, the information of previously collected `PREDICATE COLUMNS` is cleared. For details, see [Collect statistics on some columns](/statistics.md#collect-statistics-on-some-columns).
 
+### tidb_enable_descending_index <span class="version-mark">New in v9.0.0</span>
+
+> **Note:**
+>
+> Setting this variable to `ON` requires every TiKV store in the cluster to support descending-order index keys. TiDB rejects `CREATE INDEX` and `CREATE TABLE` statements that persist a descending column if any store reports a TiKV version below the minimum required version. Upgrade TiKV before you enable this variable.
+
+- Scope: GLOBAL
+- Persists to cluster: Yes
+- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No
+- Type: Boolean
+- Default value: `OFF`
+- This variable controls whether TiDB honors the `DESC` keyword on individual columns in `CREATE INDEX` and `CREATE TABLE` statements. When this variable is set to `OFF` (default), TiDB parses the `DESC` keyword for compatibility with MySQL 5.7 but stores all index columns in ascending order. When set to `ON`, columns marked `DESC` are stored in descending order, which allows composite indexes such as `INDEX(a ASC, b DESC)` to satisfy `ORDER BY a ASC, b DESC` directly without an additional `Sort` operator.
+- TiDB evaluates this variable only at DDL time. Toggling it after you create descending indexes does not change those indexes. Subsequent `CREATE INDEX` statements with `DESC` use the current value of this variable.
+
 ### tidb_enable_enhanced_security
 
 - Scope: NONE