index: add document for partial index (#21903)#22991
Conversation
Signed-off-by: Yang Keao <yangkeao@chunibyo.icu> (cherry picked from commit 355e3e4)
|
[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 |
ti-chi-bot
Bot
added
missing-translation-status
![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 the "Partial indexes" feature in TiDB, including creation syntax, usage examples, use cases, limitations, and performance benefits. The reviewer's feedback focuses on aligning the text with the documentation style guide by addressing passive voice, removing contractions, using second-person perspective, correcting minor grammatical errors, and ensuring consistent capitalization of SQL keywords in examples. All review comments are valid and provide actionable improvements.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| 3 rows in set (0.00 sec) | ||
| ``` | ||
|
|
||
| If the predicates in query don't meet the index definition, the index will not be chosen even with hint: |
There was a problem hiding this comment.
Rewrite to avoid contractions ("don't"), passive voice ("will not be chosen"), and grammatical issues ("in query", "with hint").
| If the predicates in query don't meet the index definition, the index will not be chosen even with hint: | |
| If the predicates in a query do not match the index definition, TiDB does not choose the index, even if you use a hint: |
References
- Avoid passive voice overuse. (link)
| Partial indexes offer several advantages: | ||
|
|
||
| 1. **Reduced storage**: Only rows matching the predicate are indexed, saving storage space | ||
| 2. **Faster DML**: It'll be faster to maintain the index of a subset of data during INSERT, UPDATE, and DELETE operations |
There was a problem hiding this comment.
Avoid contractions ("It'll"), use active voice, and format SQL keywords (INSERT, UPDATE, DELETE) with backticks as required by the style guide.
| 2. **Faster DML**: It'll be faster to maintain the index of a subset of data during INSERT, UPDATE, and DELETE operations | |
| 2. **Faster DML**: Maintaining a partial index is faster during `INSERT`, `UPDATE`, and `DELETE` operations because TiDB only updates the index for a subset of data |
References
- Avoid passive voice overuse and use backticks for code snippets/command names. (link)
|
|
||
| Partial indexes offer several advantages: | ||
|
|
||
| 1. **Reduced storage**: Only rows matching the predicate are indexed, saving storage space |
There was a problem hiding this comment.
Rewrite in the active voice to improve readability.
| 1. **Reduced storage**: Only rows matching the predicate are indexed, saving storage space | |
| 1. **Reduced storage**: TiDB indexes only the rows that match the predicate, which saves storage space |
References
- Avoid passive voice overuse. (link)
| - The `WHERE` clause in partial indexes supports basic comparison operators (`=`, `!=`, `<`, `<=`, `>`, `>=`) and `IN` predicates with constant values | ||
| - The types of the column and constant value should be the same | ||
| - The predicate can only reference columns from the same table | ||
| - Partial indexes cannot be used on expression indexes |
There was a problem hiding this comment.
Rewrite in the active voice using the second person ("you") to align with the technical writing style guide.
| - Partial indexes cannot be used on expression indexes | |
| - You cannot create a partial index on an expression index |
References
- Avoid passive voice overuse and write in second person ('you') when addressing users. (link)
|
|
||
| - The `WHERE` clause in partial indexes supports basic comparison operators (`=`, `!=`, `<`, `<=`, `>`, `>=`) and `IN` predicates with constant values | ||
| - The types of the column and constant value should be the same | ||
| - The predicate can only reference columns from the same table |
There was a problem hiding this comment.
Use "must" instead of "can" to specify a strict requirement, and place "only" precisely before the phrase it modifies.
| - The predicate can only reference columns from the same table | |
| - The predicate must reference only columns from the same table |
| +-------------------------------+----------+-----------+-------------------------------------------+---------------------------------+ | ||
| 4 rows in set (0.00 sec) | ||
|
|
||
| mysql> explain SELECT * FROM users WHERE score > 10000 ORDER BY created_at; |
There was a problem hiding this comment.
Use uppercase EXPLAIN to maintain consistency with other examples in this document.
| mysql> explain SELECT * FROM users WHERE score > 10000 ORDER BY created_at; | |
| mysql> EXPLAIN SELECT * FROM users WHERE score > 10000 ORDER BY created_at; |
| +-------------------------------+---------+-----------+-------------------------------------------+-------------------------------------------------------+ | ||
| 4 rows in set (0.00 sec) | ||
|
|
||
| mysql> explain SELECT * FROM users WHERE status = 'active' ORDER BY name; |
There was a problem hiding this comment.
Use uppercase EXPLAIN to maintain consistency with other examples in this document.
| mysql> explain SELECT * FROM users WHERE status = 'active' ORDER BY name; | |
| mysql> EXPLAIN SELECT * FROM users WHERE status = 'active' ORDER BY name; |
| ALTER TABLE t1 ADD INDEX idx2 (c1, c2) WHERE c3 = 'abc'; | ||
| ``` | ||
|
|
||
| Or specify the partial index when creating the table: |
There was a problem hiding this comment.
Use the second person ("you") to address users, as recommended by the technical writing style guide.
| Or specify the partial index when creating the table: | |
| Or you can specify the partial index when creating the table: |
References
- Write in second person ('you') when addressing users. (link)
| ``` | ||
|
|
||
| Then the following queries can use the partial index: | ||
|
|
There was a problem hiding this comment.
Avoid unnecessary words like "Then" and use the plural "partial indexes" since the queries in the example use different partial indexes.
| The following queries can use the partial indexes: |
References
- Avoid unnecessary words and repetition. (link)
| CREATE TABLE users ( | ||
| id INT PRIMARY KEY AUTO_INCREMENT, | ||
| name VARCHAR(100), | ||
| status varchar(20), |
There was a problem hiding this comment.
Use uppercase VARCHAR(20) to maintain consistency with other SQL data types in the example.
| status varchar(20), | |
| status VARCHAR(20), |
|
@yudongusa: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn response to this: Instructions 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. |
2 participants
Pick from #21903
First-time contributors' checklist
What is changed, added or deleted? (Required)
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?