Document descending-order index support (pingcap/tidb#2519)#22805
Document descending-order index support (pingcap/tidb#2519)#22805takaidohigasi wants to merge 2 commits intopingcap:masterfrom
Conversation
Add user-facing documentation for the descending-order index feature introduced in pingcap/tidb#68049 (and the corresponding TiKV change in tikv/tikv#19558): * system-variables.md: new tidb_enable_descending_index entry documenting scope, default OFF, and the TiKV-version prerequisite. * sql-statements/sql-statement-create-index.md: replace the "descending indexes are not supported" note with the new conditional-support description, including the mixed-direction composite-index example that motivates the feature. * mysql-compatibility.md: qualify the existing Descending Index entry so it is no longer listed as wholly unsupported. Signed-off-by: takaidohigasi <takaidohigasi@gmail.com>
ti-chi-bot
Bot
added
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Hi @takaidohigasi. Thanks for your PR. I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
ti-chi-bot
Bot
added
needs-ok-to-test
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for descending index support, a new opt-in feature in TiDB v9.0.0 controlled by the tidb_enable_descending_index system variable. The changes include updates to the MySQL compatibility list, the CREATE INDEX statement documentation, and the addition of the new system variable's details. Review feedback focused on improving conciseness, ensuring consistent terminology, and adhering to style guide principles such as using the active voice and addressing the user in the second person.
| + `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 as an opt-in feature starting from v9.0.0; controlled by the [`tidb_enable_descending_index`](/system-variables.md#tidb_enable_descending_index-new-in-v900) system variable, which defaults to `OFF`) |
There was a problem hiding this comment.
This entry is a bit wordy for a list item. Following the general writing principle of avoiding unnecessary words, you can simplify the description of the feature's availability and control mechanism.
| + Descending Index [#2519](https://github.com/pingcap/tidb/issues/2519) (supported as an opt-in feature starting from v9.0.0; controlled by the [`tidb_enable_descending_index`](/system-variables.md#tidb_enable_descending_index-new-in-v900) system variable, which defaults to `OFF`) | |
| + 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) |
References
- Avoid unnecessary words and repetition. (link)
There was a problem hiding this comment.
Already applied verbatim — see commit d9a65a687 ("Apply gemini-code-assist style suggestions on the desc-index docs"). The file content on this PR already matches your suggestion.
There was a problem hiding this comment.
Understood, thank you for the update. Since the change has already been applied in commit d9a65a687, no further action is needed on this thread.
|
|
||
| * 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-order 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 the 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, allowing 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`. |
There was a problem hiding this comment.
To maintain consistency with standard MySQL terminology and improve readability, consider using "Descending indexes" and splitting the long final sentence. This also clarifies the limitations for expression and FULLTEXT indexes.
| * Descending-order 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 the 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, allowing 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`. | |
| * 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`. |
There was a problem hiding this comment.
Already applied verbatim — see commit d9a65a687. "Descending indexes" terminology and the split sentences (FULLTEXT exclusion on its own line) are in.
| ### tidb_enable_descending_index <span class="version-mark">New in v9.0.0</span> | ||
|
|
||
| > **Note:** | ||
| > | ||
| > Setting this variable to `ON` requires that every TiKV store in the cluster supports descending-order index keys. TiDB rejects `CREATE INDEX` and `CREATE TABLE` statements that would persist a descending column when any store reports a TiKV version below the minimum required by this feature; upgrade TiKV before enabling 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 the `DESC` keyword on individual columns of `CREATE INDEX` and `CREATE TABLE` statements is honored. When set to `OFF` (the 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, allowing composite indexes such as `INDEX(a ASC, b DESC)` to satisfy `ORDER BY a ASC, b DESC` directly without an additional `Sort` operator. | ||
| - The variable is evaluated at DDL time only. Toggling it after creating descending indexes does not change those indexes; subsequent `CREATE INDEX` statements with `DESC` are governed by the variable's current value. |
There was a problem hiding this comment.
The description of this system variable can be improved by using active voice and addressing the user in the second person, as per the general writing principles. Additionally, removing unnecessary words like "the" in "(the default)" enhances conciseness.
| ### tidb_enable_descending_index <span class="version-mark">New in v9.0.0</span> | |
| > **Note:** | |
| > | |
| > Setting this variable to `ON` requires that every TiKV store in the cluster supports descending-order index keys. TiDB rejects `CREATE INDEX` and `CREATE TABLE` statements that would persist a descending column when any store reports a TiKV version below the minimum required by this feature; upgrade TiKV before enabling 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 the `DESC` keyword on individual columns of `CREATE INDEX` and `CREATE TABLE` statements is honored. When set to `OFF` (the 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, allowing composite indexes such as `INDEX(a ASC, b DESC)` to satisfy `ORDER BY a ASC, b DESC` directly without an additional `Sort` operator. | |
| - The variable is evaluated at DDL time only. Toggling it after creating descending indexes does not change those indexes; subsequent `CREATE INDEX` statements with `DESC` are governed by the variable's current value. | |
| ### 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. |
There was a problem hiding this comment.
Already applied verbatim — see commit d9a65a687. Active voice, second person, and "(default)" instead of "(the default)" are in.
Three low-priority style fixes from the bot review on pingcap#22805, all matching the docs styleguide: * mysql-compatibility.md: trim wordiness on the descending-index bullet ("supported as an opt-in feature starting from" -> "supported since"; drop the redundant default-value parenthetical). * sql-statement-create-index.md: use "Descending indexes" instead of "Descending-order indexes" for consistent terminology, and split the long final sentence so the FULLTEXT exclusion stands on its own line. * system-variables.md: rewrite the description in active voice and second person, drop "(the default)" in favour of "(default)", and split the toggle-semantics paragraph into two sentences. No content changes - the technical claims and links are identical. Signed-off-by: takaidohigasi <takaidohigasi@gmail.com>
1 participant
What is changed, added or deleted? (Required)
Add user-facing documentation for the descending-order index feature
introduced in pingcap/tidb#68049 (and the corresponding TiKV change in
tikv/tikv#19558).
Three files updated:
system-variables.md— newtidb_enable_descending_indexentrydocumenting scope, default
OFF, and the TiKV-version prerequisite.sql-statements/sql-statement-create-index.md— replace theexisting "descending indexes are not supported (similar to MySQL 5.7)"
note with the new conditional-support description, including the
mixed-direction composite-index example (
INDEX(a ASC, b DESC)satisfying
ORDER BY a ASC, b DESCwithout aSort).mysql-compatibility.md— qualify the existing "Descending Index"entry so it is no longer listed as wholly unsupported.
Which TiDB version(s) do your changes apply to? (Required)
The feature is gated behind
tidb_enable_descending_index(defaultOFF), so the visible behaviour change is opt-in. Backporting to olderrelease branches is not appropriate because the feature requires a
matching TiKV release that contains tikv/tikv#19558.
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?
🤖 Generated with Claude Code