[abigpigishere]

First-time contributors' checklist

• I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added or deleted? (Required)

Add a troubleshooting workflow for vector searches that remain slow after a vector index has been created. The guide connects existing reference material into three checks: execution-plan index usage, unindexed Stable/Delta data, and first-versus-subsequent execution overhead. It includes diagnostic SQL, interpretation tables, and a compact checklist for reporting unresolved problems.

Add navigation in TOC-ai.md and a link from the existing performance guide. Query comparisons explicitly retain the original SQL, and the guide does not introduce benchmark claims or product behavior changes.

This PR targets release-8.5 because the repository's AI documentation workflow maintains the English source there and synchronizes Chinese AI documentation automatically.

Validation:

• Passed the repository Markdown configuration using markdownlint-cli@0.17.0 on all three changed files.
• Passed git diff --check.
• Verified the new guide's 11 internal links against tracked paths and the referenced section headings.
• No cluster or performance tests were run for this documentation-only addition. Full site rendering and repository-wide link checks are left to CI.

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.

• master (the latest development version)
• v8.5 (TiDB 8.5 versions)
• v8.4 (TiDB 8.4 versions)
• v8.3 (TiDB 8.3 versions)
• v8.2 (TiDB 8.2 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)?

• This PR is translated from: N/A (new English documentation).
• Other reference link(s): https://github.com/pingcap/docs/blob/release-8.5/ai/reference/vector-search-index.md

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 a guide to help troubleshoot slow vector searches, including checks for query plans, unindexed data, and first-run loading overhead.
  • Added links to the guide from the documentation table of contents and vector search performance guidance.

[ti-chi-bot]

Welcome @abigpigishere!

It looks like this is your first PR to pingcap/docs 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!



Thank you, and welcome to pingcap/docs. 😃

[ti-chi-bot]

Hi @abigpigishere. 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 /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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.

[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 breezewish 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

[pingcap-cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

Walkthrough

The changes add a troubleshooting guide for slow TiDB vector searches. The guide covers plan checks, index status, and execution timing. Links to the guide are added to the AI table of contents and vector-search performance guidance.

Changes: Vector-search troubleshooting

Layer / File(s)	Summary
Find vector-index plan use TOC-ai.md, ai/guides/vector-search-troubleshooting.md, ai/reference/vector-search-improve-performance.md	The guide explains how to capture the original query plan and check for the annIndex marker. The table of contents and performance guidance link to the guide.
Check index coverage ai/guides/vector-search-troubleshooting.md	The guide adds a TIFLASH_INDEXES query and guidance for interpreting its results, including unindexed Stable and Delta rows.
Compare execution timing and gather evidence ai/guides/vector-search-troubleshooting.md	The guide explains how to compare first and later executions and lists information to collect for investigation.

Priority: Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related issues

• pingcap/tidb#72174: The guide addresses troubleshooting slow searches after index creation, but it does not add per-query ef_search control.

Suggested labels: size/L, missing-translation-status

Suggested reviewers: qiancai

Merge Risk: Low · up to 75ca7

The documentation should preserve the production-use warning before merging.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: adding a vector search troubleshooting workflow.
Description check		The description is complete and covers the change, target TiDB version, related links, AI involvement, validation, and applicable change categories. It provides sufficient context for review.
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within survi…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (3 skipped: 3 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

• Source mode: Auto
• Repository: pingcap/docs
• Branch: release-8.5
• File: .coderabbit.yaml
• Commit: 032ff0c
• Layers: Repository YAML
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 3ea30161-475a-4cc5-8ddf-0551b8601e1c

Commits

Reviewing files that changed from the base of the PR and between 032ff0c and 75ca73b.

Files selected for processing: 3

• TOC-ai.md
• ai/guides/vector-search-troubleshooting.md
• ai/reference/vector-search-improve-performance.md

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

[coderabbitai]

Minor · Functional Correctness · Quick win

Preserve the upstream production-use warning for TIFLASH_INDEXES.

The reference marks this table as experimental and says it is not recommended for production use. This guide directs users to query the table during slow-query investigations but only mentions field changes. Keep the stronger warning so readers do not treat the result as a stable production interface. (raw.githubusercontent.com)

> **Warning:** `TIFLASH_INDEXES` is experimental and is not recommended for use in production environments. Its fields can change between TiDB versions. Check `DESC INFORMATION_SCHEMA.TIFLASH_INDEXES;` for your version before using this query. See [`TIFLASH_INDEXES`](/information-schema/information-schema-tiflash-indexes.md).