ttl: document index scans for TTL jobs

[YangKeao]

What is changed, added, or deleted? (Required)

Document TTL index scans, including the system variable, eligible index requirements, fallback behavior, and task metadata.

Which TiDB version(s) do your changes apply to? (Required)

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

• Related code change PR links (if applicable): ttl: enhance TTL scan with secondary index tidb#68397
• This PR is translated from: N/A
• Other reference link(s): N/A

AI agent involvement

• The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

Summary by CodeRabbit

• Documentation
  • Added tidb_ttl_enable_index_scan to the system variable reference.
  • Documented its global scope, cluster persistence, default ON value, behavior, and TiDB Cloud availability.
  • Added guidance on using eligible indexes to scan expired rows, including fallback behavior and index requirements.
  • Documented the scan_index_id field in the TTL task table to clarify the selected scan path.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign lance6716 for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 51499fc6-74d7-4b59-ba43-073f7c18c6ec

📥 Commits

Reviewing files that changed from the base of the PR and between afc66a5 and a0d2d91.

📒 Files selected for processing (2)

• system-variables.md
• time-to-live.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation adds the tidb_ttl_enable_index_scan system variable and describes TTL index-based scanning, fallback behavior, index eligibility, and the scan_index_id task column.

Changes

TTL index scan documentation

Layer / File(s)	Summary
System variable documentation system-variable-reference.md, system-variables.md	Documents the variable’s scope, persistence, default value, type, and TTL scan behavior.
TTL scan behavior and task metadata time-to-live.md	Describes eligible indexes, table-key-order fallback, and the meaning of scan_index_id in mysql.tidb_ttl_task.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: qiancai, ti-chi-bot, lilin90

Merge Risk: ⚪ Minimal · up to a0d2d

This change documents TTL index-scan configuration, eligibility, fallback behavior, and task metadata. The documented task scan-path semantics are now clear, with no remaining current-head merge risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting index scans for TTL jobs.
Description check	✅ Passed	The description includes the required change summary, affected version, related PR link, AI involvement, and change-category checklist. The optional first-time contributor section is omitted appropria…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: b3739982-aa29-4e28-ac3a-da57471a7a0e

📥 Commits

Reviewing files that changed from the base of the PR and between 49d3949 and afeda1a.

📒 Files selected for processing (3)

• system-variable-reference.md
• system-variables.md
• time-to-live.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.