This is an automated email from the ASF dual-hosted git repository.
yiguolei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 599816d20bd [codex] add ann practical guide docs for current and 4.x
(#3458)
599816d20bd is described below
commit 599816d20bd2effae48b2ef0e2723cabccbcd8a9
Author: zhiqiang <[email protected]>
AuthorDate: Fri Mar 13 13:10:17 2026 +0800
[codex] add ann practical guide docs for current and 4.x (#3458)
## Summary
This PR adds a practical ANN vector-search handbook to Apache Doris docs
## User Impact
Users now have a single hands-on guide for end-to-end ANN operations,
including:
- prerequisites and table constraints,
- table/index creation patterns,
- loading and index build workflows,
- TopN/range/filter query patterns,
- tuning checklist (`hnsw_ef_search`, `nprobe`, scan parallelism),
- troubleshooting and hybrid search practices.
The docs also explicitly explain how to handle cosine-similarity use
cases in Doris ANN:
- Doris ANN does not support `metric_type="cosine"` directly.
- Recommended approach: L2-normalize vectors, then index/query with
`inner_product`.
- Query pattern: `inner_product_approximate(...)` with `ORDER BY ...
DESC`.
## Cosine Principle (Why this works)
Cosine similarity is:
`cos(x, y) = (x · y) / (||x|| ||y||)`
After L2 normalization, `||x|| = ||y|| = 1`, so:
`cos(x, y) = x · y`
Therefore, maximizing cosine similarity is equivalent to maximizing
inner product on normalized vectors.
If vectors are not normalized, inner product is not equivalent to
cosine.
## Root Cause
Existing vector-search docs covered algorithm details and performance
data, but lacked one consolidated operational handbook that walks
through the complete production workflow from schema to diagnostics.
They also did not clearly state how cosine should be implemented under
current ANN metric support.
## Changes
- Added practical guide doc (current EN):
- `docs/ai/vector-search/practical-guide.md`
- Added practical guide doc (current ZH):
-
`i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/practical-guide.md`
- Added practical guide doc (4.x EN):
- `versioned_docs/version-4.x/ai/vector-search/practical-guide.md`
- Added practical guide doc (4.x ZH):
-
`i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/practical-guide.md`
- Updated cosine guidance in overview and practical-guide docs for
current + 4.x, EN + ZH.
- Updated sidebars:
- `sidebars.ts`: add `ai/vector-search/practical-guide`
- `versioned_sidebars/version-4.x-sidebars.json`: add
`ai/vector-search/practical-guide`
## Validation
- Verified new files are in expected current/4.x and i18n locations.
- Verified sidebar entries are present in both current and 4.x sidebars.
---
docs/ai/vector-search/overview.md | 29 ++-
docs/ai/vector-search/practical-guide.md | 285 +++++++++++++++++++++
.../current/ai/vector-search/overview.md | 28 ++
.../current/ai/vector-search/practical-guide.md | 282 ++++++++++++++++++++
.../version-4.x/ai/vector-search/overview.md | 29 +++
.../ai/vector-search/practical-guide.md | 282 ++++++++++++++++++++
sidebars.ts | 1 +
.../version-4.x/ai/vector-search/overview.md | 30 ++-
.../ai/vector-search/practical-guide.md | 285 +++++++++++++++++++++
versioned_sidebars/version-4.x-sidebars.json | 1 +
10 files changed, 1249 insertions(+), 3 deletions(-)
diff --git a/docs/ai/vector-search/overview.md
b/docs/ai/vector-search/overview.md
index 539f0a56da8..b2b7c95e7cb 100644
--- a/docs/ai/vector-search/overview.md
+++ b/docs/ai/vector-search/overview.md
@@ -74,6 +74,34 @@ PROPERTIES (
| `pq_m` | Required when 'quantizer=pq' | Positive integer | (none) |
Specifies how many subvectors are used (vector dimension dim must be divisible
by pq_m). |
| `pq_nbits` | Required when 'quantizer=pq' | Positive integer | (none) | The
number of bits used to represent each subvector, in faiss pq_nbits is generally
required to be no greater than 24. |
+## If You Need Cosine Similarity
+
+ANN index `metric_type` in Doris supports `l2_distance` and `inner_product`,
but not `cosine` directly.
+
+If your business metric is cosine similarity, the recommended approach is:
+
+1. L2-normalize vectors to unit length before writing data.
+2. Build ANN index with `metric_type="inner_product"`.
+3. Query with `inner_product_approximate(...)` and `ORDER BY ... DESC`.
+
+Example DDL:
+
+```sql
+CREATE INDEX idx_emb_cosine ON your_table (embedding) USING ANN PROPERTIES (
+ "index_type"="hnsw",
+ "metric_type"="inner_product",
+ "dim"="768"
+);
+```
+
+Why this works:
+
+- Cosine similarity: `cos(x, y) = (x · y) / (||x|| ||y||)`
+- After L2 normalization (`||x|| = ||y|| = 1`): `cos(x, y) = x · y`
+
+So maximizing cosine similarity is equivalent to maximizing inner product on
normalized vectors.
+If vectors are not normalized, inner product is no longer equivalent to cosine.
+
Import via S3 TVF:
```sql
@@ -383,4 +411,3 @@ In the era of AI, Python has become the mainstream language
for data processing
4. If the distance function in SQL does not match the metric type defined in
the index DDL, Doris cannot use the ANN index for TopN—even if you call
`l2_distance_approximate` / `inner_product_approximate`.
5. For metric type `inner_product`, only `ORDER BY
inner_product_approximate(...) DESC LIMIT N` (DESC required) can be accelerated
by the ANN index.
6. The first parameter of `xxx_approximate()` must be a ColumnArray, and the
second must be a CAST or ArrayLiteral. Reversing them triggers brute-force
search.
-
diff --git a/docs/ai/vector-search/practical-guide.md
b/docs/ai/vector-search/practical-guide.md
new file mode 100644
index 00000000000..d2b051c9a8f
--- /dev/null
+++ b/docs/ai/vector-search/practical-guide.md
@@ -0,0 +1,285 @@
+---
+{
+ "title": "Practical Guide",
+ "language": "en",
+ "description": "Hands-on guide for Apache Doris ANN vector search: table
design, index creation, data loading, index build, query tuning, and
troubleshooting."
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+This guide provides a production-oriented workflow for Apache Doris ANN vector
search, from schema design to tuning and troubleshooting.
+
+## 1. Scope and Typical Scenarios
+
+Apache Doris 4.x supports ANN indexing on high-dimensional vectors for
scenarios such as:
+
+- Semantic search
+- RAG retrieval
+- Recommendation
+- Image or multimodal retrieval
+- Outlier detection
+
+Supported index types:
+
+- `hnsw`: high recall and online query performance
+- `ivf`: lower memory and faster build in large-scale cases
+
+Supported approximate distance functions:
+
+- `l2_distance_approximate` (`ORDER BY ... ASC`)
+- `inner_product_approximate` (`ORDER BY ... DESC`)
+
+Cosine note:
+
+- ANN index does not support `metric_type="cosine"` directly.
+- For cosine-based retrieval, normalize vectors first, then use
`inner_product`.
+
+## 2. Prerequisites and Constraints
+
+Before using ANN indexes, confirm the following:
+
+1. Doris version: `>= 4.0.0`
+2. Table model: only `DUPLICATE KEY` is supported for ANN
+3. Vector column: must be `ARRAY<FLOAT> NOT NULL`
+4. Dimension consistency: input vector dimension must match index `dim`
+
+Example table model:
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ embedding ARRAY<FLOAT> NOT NULL
+)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+## 2.1 Using Cosine Similarity in Doris ANN
+
+If your ranking metric is cosine similarity, use this pattern:
+
+1. Normalize every vector to unit length before ingestion.
+2. Build ANN index with `metric_type="inner_product"`.
+3. Query with `inner_product_approximate(...)` and `ORDER BY ... DESC`.
+
+Reason:
+
+- `cos(x, y) = (x · y) / (||x|| ||y||)`
+- After normalization, `||x|| = ||y|| = 1`, so `cos(x, y) = x · y`
+
+That is why cosine ranking can be implemented through inner product in Doris
ANN.
+
+## 3. End-to-End Workflow
+
+### Step 1: Create Table
+
+You can choose one of two patterns:
+
+1. Define ANN index when creating table.
+ - Index is built during ingest.
+ - Faster time-to-query after loading.
+ - Slower ingest throughput.
+2. Create table first, then `CREATE INDEX` and `BUILD INDEX` later.
+ - Better for large batch import.
+ - More control over compaction and build timing.
+
+Example (index defined in `CREATE TABLE`):
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ title VARCHAR(500),
+ content TEXT,
+ category VARCHAR(100),
+ embedding ARRAY<FLOAT> NOT NULL,
+ INDEX idx_embedding (embedding) USING ANN PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768"
+ )
+)
+ENGINE = OLAP
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+### Step 2: Configure ANN Index
+
+Common properties:
+
+- `index_type`: `hnsw` or `ivf`
+- `metric_type`: `l2_distance` or `inner_product`
+- `dim`: vector dimension
+- `quantizer`: `flat`, `sq8`, `sq4`, `pq` (optional)
+
+HNSW-specific:
+
+- `max_degree` (default `32`)
+- `ef_construction` (default `40`)
+
+IVF-specific:
+
+- `nlist` (default `1024`)
+
+Example:
+
+```sql
+CREATE INDEX idx_embedding ON document_vectors (embedding) USING ANN
PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768",
+ "max_degree" = "64",
+ "ef_construction" = "128"
+);
+```
+
+### Step 3: Load Data
+
+Recommended order for bulk workloads:
+
+1. Create table (without ANN index or without `BUILD INDEX` yet)
+2. Import data in batch (Stream Load, S3 TVF, or SDK)
+3. Trigger index build
+
+For production, prefer batch loading approaches such as Stream Load or SDK
batch insert.
+
+### Step 4: Build and Monitor Index
+
+When index is created after table creation, run `BUILD INDEX` manually:
+
+```sql
+BUILD INDEX idx_embedding ON document_vectors;
+SHOW BUILD INDEX WHERE TableName = "document_vectors";
+```
+
+Build states include `PENDING`, `RUNNING`, `FINISHED`, and `CANCELLED`.
+
+## 4. Query Patterns
+
+### TopN search
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+ORDER BY dist
+LIMIT 10;
+```
+
+### Range search
+
+```sql
+SELECT id, title
+FROM document_vectors
+WHERE l2_distance_approximate(embedding, [0.1, 0.2, ...]) < 0.5;
+```
+
+### Search with filters
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+WHERE category = 'AI'
+ORDER BY dist
+LIMIT 10;
+```
+
+Doris uses pre-filtering in vector search plans, which helps preserve recall
in mixed filter scenarios.
+
+## 5. Tuning Checklist
+
+### Query-side parameters
+
+- HNSW: `hnsw_ef_search` (higher recall vs higher latency)
+- IVF: `nprobe` (or `ivf_nprobe`, depending on version/session variables)
+
+Example:
+
+```sql
+SET hnsw_ef_search = 100;
+SET nprobe = 128;
+SET optimize_index_scan_parallelism = true;
+```
+
+### Build-side recommendations
+
+1. Run compaction before final index build on large datasets.
+2. Avoid oversized segments when targeting high recall.
+3. Benchmark several parameter groups (`max_degree`, `ef_construction`,
`ef_search`) on the same dataset.
+
+### Capacity planning
+
+As a practical baseline, estimate vector memory with `dim * 4 bytes *
row_count`, then add ANN structure overhead and reserve memory headroom for
non-vector columns and execution operators.
+For single-node and distributed sizing references at 10M/100M scale, see
[Large-scale Performance Benchmark](./performance-large-scale.md).
+
+## 6. Index Operations
+
+Common management SQL:
+
+```sql
+SHOW INDEX FROM document_vectors;
+SHOW DATA ALL FROM document_vectors;
+ALTER TABLE document_vectors DROP INDEX idx_embedding;
+```
+
+When changing index parameters, use drop-and-recreate workflow, then rebuild
index.
+
+## 7. Troubleshooting
+
+### Index not used
+
+Check:
+
+1. Index exists: `SHOW INDEX`
+2. Build finished: `SHOW BUILD INDEX`
+3. Correct function: use `_approximate` functions
+
+### Low recall
+
+Check:
+
+- HNSW parameters (`max_degree`, `ef_construction`, `hnsw_ef_search`)
+- IVF probe parameters (`nprobe`/`ivf_nprobe`)
+- Segment size and post-compaction rebuild
+
+### High latency
+
+Check:
+
+- Cold vs warm query behavior (index loading)
+- Overly large `hnsw_ef_search`
+- Parallel scan setting
+- BE memory pressure
+
+### Data import errors
+
+Common causes:
+
+- dimension mismatch (`dim` vs actual data)
+- null vector values
+- invalid array format
+
+## 8. Hybrid Search Pattern
+
+You can combine ANN with text search by defining both ANN and inverted indexes
in the same table, then filtering with text predicates and ordering with vector
distance. This is a common approach for production RAG pipelines.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/overview.md
index 33debeba859..207a42303b4 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/overview.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/overview.md
@@ -66,6 +66,34 @@ PROPERTIES (
| `pq_m` | 'quantizer=pq' 时需要指定 | 正整数 | （无） | 指定将原始的高维向量分割成多少个子向量(向量维度 dim
必须能被 pq_m 整除)。 |
| `pq_nbits` | 'quantizer=pq' 时需要指定 | 正整数 | （无） | 指定每个子向量量化的比特数,
它决定了每个子空间码本的大小(k = 2 ^ pq_nbits), 在faiss中pq_nbits值一般要求不大于24。 |
+## 如果业务需要使用 Cosine 相似度
+
+Doris 的 ANN 索引 `metric_type` 目前只支持 `l2_distance` 和 `inner_product`，不直接支持
`cosine`。
+
+当业务指标是 cosine 相似度时，推荐做法是：
+
+1. 写入前对向量做 L2 归一化（归一化到单位长度）。
+2. 建索引时使用 `metric_type="inner_product"`。
+3. 查询时使用 `inner_product_approximate(...)`，并按 `ORDER BY ... DESC` 排序。
+
+示例：
+
+```sql
+CREATE INDEX idx_emb_cosine ON your_table (embedding) USING ANN PROPERTIES (
+ "index_type"="hnsw",
+ "metric_type"="inner_product",
+ "dim"="768"
+);
+```
+
+原理如下：
+
+- Cosine 相似度公式：`cos(x, y) = (x · y) / (||x|| ||y||)`
+- 当向量已做 L2 归一化时（`||x|| = ||y|| = 1`）：`cos(x, y) = x · y`
+
+因此，在单位向量空间里，最大化 cosine 相似度等价于最大化 inner product。
+如果不做归一化，inner product 与 cosine 不再等价。
+
通过 S3 TVF 导入数据：
```sql
INSERT INTO sift_1M
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/practical-guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/practical-guide.md
new file mode 100644
index 00000000000..cc648beb2dd
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/vector-search/practical-guide.md
@@ -0,0 +1,282 @@
+---
+{
+ "title": "实用手册",
+ "sidebar_label": "实用手册",
+ "language": "zh-CN",
+ "description": "Apache Doris 向量索引实战手册，覆盖建表、建索引、导入、构建、查询调优和常见问题排查。"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+本文给出 Apache Doris 向量检索（ANN）的生产实践流程，覆盖从表设计到参数调优、问题排查的完整链路。
+
+## 1. 适用范围
+
+Apache Doris 4.x 支持 ANN 向量索引，常见场景包括：
+
+- 语义搜索
+- RAG 检索
+- 推荐系统
+- 图像或多模态检索
+- 异常检测
+
+支持的索引类型：
+
+- `hnsw`：高召回、在线查询性能好
+- `ivf`：构建更快、内存更省，适合大规模场景
+
+支持的近似距离函数：
+
+- `l2_distance_approximate`（`ORDER BY ... ASC`）
+- `inner_product_approximate`（`ORDER BY ... DESC`）
+
+Cosine 说明：
+
+- ANN 索引不支持直接配置 `metric_type=\"cosine\"`。
+- 如果业务指标是 cosine，请先归一化向量，再使用 `inner_product`。
+
+## 2. 前置条件与限制
+
+使用 ANN 索引前请确认：
+
+1. Doris 版本：`>= 4.0.0`
+2. 表模型：ANN 仅支持 `DUPLICATE KEY`
+3. 向量列：必须为 `ARRAY<FLOAT> NOT NULL`
+4. 维度一致：导入向量维度必须与索引 `dim` 一致
+
+建表示例：
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ embedding ARRAY<FLOAT> NOT NULL
+)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+## 2.1 Doris ANN 中如何使用 Cosine 相似度
+
+如果业务按 cosine 相似度排序，建议使用以下模式：
+
+1. 数据写入前将向量做 L2 归一化（单位向量）。
+2. 建 ANN 索引时使用 `metric_type=\"inner_product\"`。
+3. 查询时使用 `inner_product_approximate(...)`，并按 `ORDER BY ... DESC` 排序。
+
+原理：
+
+- `cos(x, y) = (x · y) / (||x|| ||y||)`
+- 归一化后 `||x|| = ||y|| = 1`，则 `cos(x, y) = x · y`
+
+因此在单位向量空间中，cosine 排序与 inner product 排序等价。
+
+## 3. 端到端操作流程
+
+### Step 1：创建向量表
+
+常用两种方式：
+
+1. 建表时直接定义 ANN 索引。
+ - 数据写入时同步建索引。
+ - 导入完成即可查询。
+ - 导入速度通常更慢。
+2. 先建表导入数据，再 `CREATE INDEX` + `BUILD INDEX`。
+ - 更适合批量导入。
+ - 对 compaction 和构建时机控制更灵活。
+
+示例（建表时定义索引）：
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ title VARCHAR(500),
+ content TEXT,
+ category VARCHAR(100),
+ embedding ARRAY<FLOAT> NOT NULL,
+ INDEX idx_embedding (embedding) USING ANN PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768"
+ )
+)
+ENGINE = OLAP
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+### Step 2：配置向量索引
+
+通用参数：
+
+- `index_type`：`hnsw` 或 `ivf`
+- `metric_type`：`l2_distance` 或 `inner_product`
+- `dim`：向量维度
+- `quantizer`：`flat`、`sq8`、`sq4`、`pq`（可选）
+
+HNSW 参数：
+
+- `max_degree`（默认 `32`）
+- `ef_construction`（默认 `40`）
+
+IVF 参数：
+
+- `nlist`（默认 `1024`）
+
+示例：
+
+```sql
+CREATE INDEX idx_embedding ON document_vectors (embedding) USING ANN
PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768",
+ "max_degree" = "64",
+ "ef_construction" = "128"
+);
+```
+
+### Step 3：导入数据
+
+批量场景建议顺序：
+
+1. 建表（暂不构建索引）
+2. 批量导入（Stream Load / S3 TVF / SDK）
+3. 统一构建索引
+
+生产环境建议优先使用批量导入方式。
+
+### Step 4：构建索引与监控
+
+如果索引是后建方式，需要手动执行：
+
+```sql
+BUILD INDEX idx_embedding ON document_vectors;
+SHOW BUILD INDEX WHERE TableName = "document_vectors";
+```
+
+状态包括：`PENDING`、`RUNNING`、`FINISHED`、`CANCELLED`。
+
+## 4. 查询模式
+
+### TopN 近邻搜索
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+ORDER BY dist
+LIMIT 10;
+```
+
+### 范围搜索
+
+```sql
+SELECT id, title
+FROM document_vectors
+WHERE l2_distance_approximate(embedding, [0.1, 0.2, ...]) < 0.5;
+```
+
+### 带过滤条件搜索
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+WHERE category = 'AI'
+ORDER BY dist
+LIMIT 10;
+```
+
+Doris 在混合过滤场景中采用 pre-filtering，有助于兼顾性能和召回。
+
+## 5. 调优清单
+
+### 查询参数
+
+- HNSW：`hnsw_ef_search`（越大通常召回更高，延迟也更高）
+- IVF：`nprobe`（或 `ivf_nprobe`，视版本而定）
+
+```sql
+SET hnsw_ef_search = 100;
+SET nprobe = 128;
+SET optimize_index_scan_parallelism = true;
+```
+
+### 构建建议
+
+1. 大规模数据建议先 compaction 再做最终索引构建。
+2. 控制 segment 规模，避免过大影响召回。
+3. 在同一数据集上对多组参数做 A/B 压测。
+
+容量评估可先按 `dim * 4 bytes * row_count` 估算向量内存，再叠加 ANN 结构开销，并为非向量列和执行算子预留内存水位。
+10M/100M 规模下单机与分布式的容量参考可见[大规模性能测试](./performance-large-scale.md)。
+
+## 6. 索引管理
+
+常用管理 SQL：
+
+```sql
+SHOW INDEX FROM document_vectors;
+SHOW DATA ALL FROM document_vectors;
+ALTER TABLE document_vectors DROP INDEX idx_embedding;
+```
+
+如需调整参数，建议删除旧索引后重建。
+
+## 7. 常见问题排查
+
+### 索引未生效
+
+检查：
+
+1. 是否存在索引：`SHOW INDEX`
+2. 是否构建完成：`SHOW BUILD INDEX`
+3. 是否使用了 `_approximate` 距离函数
+
+### 召回率低
+
+排查方向：
+
+- HNSW 参数（`max_degree`、`ef_construction`、`hnsw_ef_search`）
+- IVF 探测参数（`nprobe`/`ivf_nprobe`）
+- Segment 大小及 compaction 后重建
+
+### 查询延迟高
+
+排查方向：
+
+- 冷查询与热查询差异（索引加载）
+- `hnsw_ef_search` 是否过大
+- 并行扫描设置是否开启
+- BE 是否存在内存压力
+
+### 导入失败
+
+常见原因：
+
+- 维度不一致（`dim` 与实际向量）
+- 向量列出现 NULL
+- 向量数组格式非法
+
+## 8. 混合检索建议
+
+可在同一张表中同时建立 ANN 索引和倒排索引，结合文本过滤与向量排序实现混合检索，这也是 RAG 线上常见模式。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/overview.md
index e7d84f464e4..207a42303b4 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/overview.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/overview.md
@@ -66,6 +66,34 @@ PROPERTIES (
| `pq_m` | 'quantizer=pq' 时需要指定 | 正整数 | （无） | 指定将原始的高维向量分割成多少个子向量(向量维度 dim
必须能被 pq_m 整除)。 |
| `pq_nbits` | 'quantizer=pq' 时需要指定 | 正整数 | （无） | 指定每个子向量量化的比特数,
它决定了每个子空间码本的大小(k = 2 ^ pq_nbits), 在faiss中pq_nbits值一般要求不大于24。 |
+## 如果业务需要使用 Cosine 相似度
+
+Doris 的 ANN 索引 `metric_type` 目前只支持 `l2_distance` 和 `inner_product`，不直接支持
`cosine`。
+
+当业务指标是 cosine 相似度时，推荐做法是：
+
+1. 写入前对向量做 L2 归一化（归一化到单位长度）。
+2. 建索引时使用 `metric_type="inner_product"`。
+3. 查询时使用 `inner_product_approximate(...)`，并按 `ORDER BY ... DESC` 排序。
+
+示例：
+
+```sql
+CREATE INDEX idx_emb_cosine ON your_table (embedding) USING ANN PROPERTIES (
+ "index_type"="hnsw",
+ "metric_type"="inner_product",
+ "dim"="768"
+);
+```
+
+原理如下：
+
+- Cosine 相似度公式：`cos(x, y) = (x · y) / (||x|| ||y||)`
+- 当向量已做 L2 归一化时（`||x|| = ||y|| = 1`）：`cos(x, y) = x · y`
+
+因此，在单位向量空间里，最大化 cosine 相似度等价于最大化 inner product。
+如果不做归一化，inner product 与 cosine 不再等价。
+
通过 S3 TVF 导入数据：
```sql
INSERT INTO sift_1M
@@ -344,6 +372,7 @@ ANN TopN 查询返回行数很少，无需高并行度，建议 `SET parallel_pi
* https://github.com/uchenily/doris_vector_search: 针对向量距离检索做了性能优化，是目前市面上性能最好的
doris vector search python sdk
+
## 使用限制
1. Doris 要求 ANN Index 对应的列必须是 NOT NULLABLE 的
`Array<Float>`，并且在后续的导入过程中，需要确保该列的每一个向量的长度均等于索引属性中指定的维度（dim），否则会报错。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/practical-guide.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/practical-guide.md
new file mode 100644
index 00000000000..cc648beb2dd
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/vector-search/practical-guide.md
@@ -0,0 +1,282 @@
+---
+{
+ "title": "实用手册",
+ "sidebar_label": "实用手册",
+ "language": "zh-CN",
+ "description": "Apache Doris 向量索引实战手册，覆盖建表、建索引、导入、构建、查询调优和常见问题排查。"
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+本文给出 Apache Doris 向量检索（ANN）的生产实践流程，覆盖从表设计到参数调优、问题排查的完整链路。
+
+## 1. 适用范围
+
+Apache Doris 4.x 支持 ANN 向量索引，常见场景包括：
+
+- 语义搜索
+- RAG 检索
+- 推荐系统
+- 图像或多模态检索
+- 异常检测
+
+支持的索引类型：
+
+- `hnsw`：高召回、在线查询性能好
+- `ivf`：构建更快、内存更省，适合大规模场景
+
+支持的近似距离函数：
+
+- `l2_distance_approximate`（`ORDER BY ... ASC`）
+- `inner_product_approximate`（`ORDER BY ... DESC`）
+
+Cosine 说明：
+
+- ANN 索引不支持直接配置 `metric_type=\"cosine\"`。
+- 如果业务指标是 cosine，请先归一化向量，再使用 `inner_product`。
+
+## 2. 前置条件与限制
+
+使用 ANN 索引前请确认：
+
+1. Doris 版本：`>= 4.0.0`
+2. 表模型：ANN 仅支持 `DUPLICATE KEY`
+3. 向量列：必须为 `ARRAY<FLOAT> NOT NULL`
+4. 维度一致：导入向量维度必须与索引 `dim` 一致
+
+建表示例：
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ embedding ARRAY<FLOAT> NOT NULL
+)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+## 2.1 Doris ANN 中如何使用 Cosine 相似度
+
+如果业务按 cosine 相似度排序，建议使用以下模式：
+
+1. 数据写入前将向量做 L2 归一化（单位向量）。
+2. 建 ANN 索引时使用 `metric_type=\"inner_product\"`。
+3. 查询时使用 `inner_product_approximate(...)`，并按 `ORDER BY ... DESC` 排序。
+
+原理：
+
+- `cos(x, y) = (x · y) / (||x|| ||y||)`
+- 归一化后 `||x|| = ||y|| = 1`，则 `cos(x, y) = x · y`
+
+因此在单位向量空间中，cosine 排序与 inner product 排序等价。
+
+## 3. 端到端操作流程
+
+### Step 1：创建向量表
+
+常用两种方式：
+
+1. 建表时直接定义 ANN 索引。
+ - 数据写入时同步建索引。
+ - 导入完成即可查询。
+ - 导入速度通常更慢。
+2. 先建表导入数据，再 `CREATE INDEX` + `BUILD INDEX`。
+ - 更适合批量导入。
+ - 对 compaction 和构建时机控制更灵活。
+
+示例（建表时定义索引）：
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ title VARCHAR(500),
+ content TEXT,
+ category VARCHAR(100),
+ embedding ARRAY<FLOAT> NOT NULL,
+ INDEX idx_embedding (embedding) USING ANN PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768"
+ )
+)
+ENGINE = OLAP
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+### Step 2：配置向量索引
+
+通用参数：
+
+- `index_type`：`hnsw` 或 `ivf`
+- `metric_type`：`l2_distance` 或 `inner_product`
+- `dim`：向量维度
+- `quantizer`：`flat`、`sq8`、`sq4`、`pq`（可选）
+
+HNSW 参数：
+
+- `max_degree`（默认 `32`）
+- `ef_construction`（默认 `40`）
+
+IVF 参数：
+
+- `nlist`（默认 `1024`）
+
+示例：
+
+```sql
+CREATE INDEX idx_embedding ON document_vectors (embedding) USING ANN
PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768",
+ "max_degree" = "64",
+ "ef_construction" = "128"
+);
+```
+
+### Step 3：导入数据
+
+批量场景建议顺序：
+
+1. 建表（暂不构建索引）
+2. 批量导入（Stream Load / S3 TVF / SDK）
+3. 统一构建索引
+
+生产环境建议优先使用批量导入方式。
+
+### Step 4：构建索引与监控
+
+如果索引是后建方式，需要手动执行：
+
+```sql
+BUILD INDEX idx_embedding ON document_vectors;
+SHOW BUILD INDEX WHERE TableName = "document_vectors";
+```
+
+状态包括：`PENDING`、`RUNNING`、`FINISHED`、`CANCELLED`。
+
+## 4. 查询模式
+
+### TopN 近邻搜索
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+ORDER BY dist
+LIMIT 10;
+```
+
+### 范围搜索
+
+```sql
+SELECT id, title
+FROM document_vectors
+WHERE l2_distance_approximate(embedding, [0.1, 0.2, ...]) < 0.5;
+```
+
+### 带过滤条件搜索
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+WHERE category = 'AI'
+ORDER BY dist
+LIMIT 10;
+```
+
+Doris 在混合过滤场景中采用 pre-filtering，有助于兼顾性能和召回。
+
+## 5. 调优清单
+
+### 查询参数
+
+- HNSW：`hnsw_ef_search`（越大通常召回更高，延迟也更高）
+- IVF：`nprobe`（或 `ivf_nprobe`，视版本而定）
+
+```sql
+SET hnsw_ef_search = 100;
+SET nprobe = 128;
+SET optimize_index_scan_parallelism = true;
+```
+
+### 构建建议
+
+1. 大规模数据建议先 compaction 再做最终索引构建。
+2. 控制 segment 规模，避免过大影响召回。
+3. 在同一数据集上对多组参数做 A/B 压测。
+
+容量评估可先按 `dim * 4 bytes * row_count` 估算向量内存，再叠加 ANN 结构开销，并为非向量列和执行算子预留内存水位。
+10M/100M 规模下单机与分布式的容量参考可见[大规模性能测试](./performance-large-scale.md)。
+
+## 6. 索引管理
+
+常用管理 SQL：
+
+```sql
+SHOW INDEX FROM document_vectors;
+SHOW DATA ALL FROM document_vectors;
+ALTER TABLE document_vectors DROP INDEX idx_embedding;
+```
+
+如需调整参数，建议删除旧索引后重建。
+
+## 7. 常见问题排查
+
+### 索引未生效
+
+检查：
+
+1. 是否存在索引：`SHOW INDEX`
+2. 是否构建完成：`SHOW BUILD INDEX`
+3. 是否使用了 `_approximate` 距离函数
+
+### 召回率低
+
+排查方向：
+
+- HNSW 参数（`max_degree`、`ef_construction`、`hnsw_ef_search`）
+- IVF 探测参数（`nprobe`/`ivf_nprobe`）
+- Segment 大小及 compaction 后重建
+
+### 查询延迟高
+
+排查方向：
+
+- 冷查询与热查询差异（索引加载）
+- `hnsw_ef_search` 是否过大
+- 并行扫描设置是否开启
+- BE 是否存在内存压力
+
+### 导入失败
+
+常见原因：
+
+- 维度不一致（`dim` 与实际向量）
+- 向量列出现 NULL
+- 向量数组格式非法
+
+## 8. 混合检索建议
+
+可在同一张表中同时建立 ANN 索引和倒排索引，结合文本过滤与向量排序实现混合检索，这也是 RAG 线上常见模式。
diff --git a/sidebars.ts b/sidebars.ts
index 5c22c675163..6a55db0c664 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -328,6 +328,7 @@ const sidebars: SidebarsConfig = {
label: 'Vector Search',
items: [
'ai/vector-search/overview',
+ 'ai/vector-search/practical-guide',
'ai/vector-search/hnsw',
'ai/vector-search/ivf',
'ai/vector-search/index-management',
diff --git a/versioned_docs/version-4.x/ai/vector-search/overview.md
b/versioned_docs/version-4.x/ai/vector-search/overview.md
index 5d2cd669100..b2b7c95e7cb 100644
--- a/versioned_docs/version-4.x/ai/vector-search/overview.md
+++ b/versioned_docs/version-4.x/ai/vector-search/overview.md
@@ -74,6 +74,34 @@ PROPERTIES (
| `pq_m` | Required when 'quantizer=pq' | Positive integer | (none) |
Specifies how many subvectors are used (vector dimension dim must be divisible
by pq_m). |
| `pq_nbits` | Required when 'quantizer=pq' | Positive integer | (none) | The
number of bits used to represent each subvector, in faiss pq_nbits is generally
required to be no greater than 24. |
+## If You Need Cosine Similarity
+
+ANN index `metric_type` in Doris supports `l2_distance` and `inner_product`,
but not `cosine` directly.
+
+If your business metric is cosine similarity, the recommended approach is:
+
+1. L2-normalize vectors to unit length before writing data.
+2. Build ANN index with `metric_type="inner_product"`.
+3. Query with `inner_product_approximate(...)` and `ORDER BY ... DESC`.
+
+Example DDL:
+
+```sql
+CREATE INDEX idx_emb_cosine ON your_table (embedding) USING ANN PROPERTIES (
+ "index_type"="hnsw",
+ "metric_type"="inner_product",
+ "dim"="768"
+);
+```
+
+Why this works:
+
+- Cosine similarity: `cos(x, y) = (x · y) / (||x|| ||y||)`
+- After L2 normalization (`||x|| = ||y|| = 1`): `cos(x, y) = x · y`
+
+So maximizing cosine similarity is equivalent to maximizing inner product on
normalized vectors.
+If vectors are not normalized, inner product is no longer equivalent to cosine.
+
Import via S3 TVF:
```sql
@@ -122,7 +150,6 @@ LIMIT 10;
```
To compare with exact ground truth, use `l2_distance` or `inner_product`
(without the `_approximate` suffix). In this example, exact search takes ~290
ms:
-
```
10 rows in set (0.29 sec)
```
@@ -384,4 +411,3 @@ In the era of AI, Python has become the mainstream language
for data processing
4. If the distance function in SQL does not match the metric type defined in
the index DDL, Doris cannot use the ANN index for TopN—even if you call
`l2_distance_approximate` / `inner_product_approximate`.
5. For metric type `inner_product`, only `ORDER BY
inner_product_approximate(...) DESC LIMIT N` (DESC required) can be accelerated
by the ANN index.
6. The first parameter of `xxx_approximate()` must be a ColumnArray, and the
second must be a CAST or ArrayLiteral. Reversing them triggers brute-force
search.
-
diff --git a/versioned_docs/version-4.x/ai/vector-search/practical-guide.md
b/versioned_docs/version-4.x/ai/vector-search/practical-guide.md
new file mode 100644
index 00000000000..d2b051c9a8f
--- /dev/null
+++ b/versioned_docs/version-4.x/ai/vector-search/practical-guide.md
@@ -0,0 +1,285 @@
+---
+{
+ "title": "Practical Guide",
+ "language": "en",
+ "description": "Hands-on guide for Apache Doris ANN vector search: table
design, index creation, data loading, index build, query tuning, and
troubleshooting."
+}
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+This guide provides a production-oriented workflow for Apache Doris ANN vector
search, from schema design to tuning and troubleshooting.
+
+## 1. Scope and Typical Scenarios
+
+Apache Doris 4.x supports ANN indexing on high-dimensional vectors for
scenarios such as:
+
+- Semantic search
+- RAG retrieval
+- Recommendation
+- Image or multimodal retrieval
+- Outlier detection
+
+Supported index types:
+
+- `hnsw`: high recall and online query performance
+- `ivf`: lower memory and faster build in large-scale cases
+
+Supported approximate distance functions:
+
+- `l2_distance_approximate` (`ORDER BY ... ASC`)
+- `inner_product_approximate` (`ORDER BY ... DESC`)
+
+Cosine note:
+
+- ANN index does not support `metric_type="cosine"` directly.
+- For cosine-based retrieval, normalize vectors first, then use
`inner_product`.
+
+## 2. Prerequisites and Constraints
+
+Before using ANN indexes, confirm the following:
+
+1. Doris version: `>= 4.0.0`
+2. Table model: only `DUPLICATE KEY` is supported for ANN
+3. Vector column: must be `ARRAY<FLOAT> NOT NULL`
+4. Dimension consistency: input vector dimension must match index `dim`
+
+Example table model:
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ embedding ARRAY<FLOAT> NOT NULL
+)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+## 2.1 Using Cosine Similarity in Doris ANN
+
+If your ranking metric is cosine similarity, use this pattern:
+
+1. Normalize every vector to unit length before ingestion.
+2. Build ANN index with `metric_type="inner_product"`.
+3. Query with `inner_product_approximate(...)` and `ORDER BY ... DESC`.
+
+Reason:
+
+- `cos(x, y) = (x · y) / (||x|| ||y||)`
+- After normalization, `||x|| = ||y|| = 1`, so `cos(x, y) = x · y`
+
+That is why cosine ranking can be implemented through inner product in Doris
ANN.
+
+## 3. End-to-End Workflow
+
+### Step 1: Create Table
+
+You can choose one of two patterns:
+
+1. Define ANN index when creating table.
+ - Index is built during ingest.
+ - Faster time-to-query after loading.
+ - Slower ingest throughput.
+2. Create table first, then `CREATE INDEX` and `BUILD INDEX` later.
+ - Better for large batch import.
+ - More control over compaction and build timing.
+
+Example (index defined in `CREATE TABLE`):
+
+```sql
+CREATE TABLE document_vectors (
+ id BIGINT NOT NULL,
+ title VARCHAR(500),
+ content TEXT,
+ category VARCHAR(100),
+ embedding ARRAY<FLOAT> NOT NULL,
+ INDEX idx_embedding (embedding) USING ANN PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768"
+ )
+)
+ENGINE = OLAP
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 8
+PROPERTIES ("replication_num" = "1");
+```
+
+### Step 2: Configure ANN Index
+
+Common properties:
+
+- `index_type`: `hnsw` or `ivf`
+- `metric_type`: `l2_distance` or `inner_product`
+- `dim`: vector dimension
+- `quantizer`: `flat`, `sq8`, `sq4`, `pq` (optional)
+
+HNSW-specific:
+
+- `max_degree` (default `32`)
+- `ef_construction` (default `40`)
+
+IVF-specific:
+
+- `nlist` (default `1024`)
+
+Example:
+
+```sql
+CREATE INDEX idx_embedding ON document_vectors (embedding) USING ANN
PROPERTIES (
+ "index_type" = "hnsw",
+ "metric_type" = "l2_distance",
+ "dim" = "768",
+ "max_degree" = "64",
+ "ef_construction" = "128"
+);
+```
+
+### Step 3: Load Data
+
+Recommended order for bulk workloads:
+
+1. Create table (without ANN index or without `BUILD INDEX` yet)
+2. Import data in batch (Stream Load, S3 TVF, or SDK)
+3. Trigger index build
+
+For production, prefer batch loading approaches such as Stream Load or SDK
batch insert.
+
+### Step 4: Build and Monitor Index
+
+When index is created after table creation, run `BUILD INDEX` manually:
+
+```sql
+BUILD INDEX idx_embedding ON document_vectors;
+SHOW BUILD INDEX WHERE TableName = "document_vectors";
+```
+
+Build states include `PENDING`, `RUNNING`, `FINISHED`, and `CANCELLED`.
+
+## 4. Query Patterns
+
+### TopN search
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+ORDER BY dist
+LIMIT 10;
+```
+
+### Range search
+
+```sql
+SELECT id, title
+FROM document_vectors
+WHERE l2_distance_approximate(embedding, [0.1, 0.2, ...]) < 0.5;
+```
+
+### Search with filters
+
+```sql
+SELECT id, title,
+ l2_distance_approximate(embedding, [0.1, 0.2, ...]) AS dist
+FROM document_vectors
+WHERE category = 'AI'
+ORDER BY dist
+LIMIT 10;
+```
+
+Doris uses pre-filtering in vector search plans, which helps preserve recall
in mixed filter scenarios.
+
+## 5. Tuning Checklist
+
+### Query-side parameters
+
+- HNSW: `hnsw_ef_search` (higher recall vs higher latency)
+- IVF: `nprobe` (or `ivf_nprobe`, depending on version/session variables)
+
+Example:
+
+```sql
+SET hnsw_ef_search = 100;
+SET nprobe = 128;
+SET optimize_index_scan_parallelism = true;
+```
+
+### Build-side recommendations
+
+1. Run compaction before final index build on large datasets.
+2. Avoid oversized segments when targeting high recall.
+3. Benchmark several parameter groups (`max_degree`, `ef_construction`,
`ef_search`) on the same dataset.
+
+### Capacity planning
+
+As a practical baseline, estimate vector memory with `dim * 4 bytes *
row_count`, then add ANN structure overhead and reserve memory headroom for
non-vector columns and execution operators.
+For single-node and distributed sizing references at 10M/100M scale, see
[Large-scale Performance Benchmark](./performance-large-scale.md).
+
+## 6. Index Operations
+
+Common management SQL:
+
+```sql
+SHOW INDEX FROM document_vectors;
+SHOW DATA ALL FROM document_vectors;
+ALTER TABLE document_vectors DROP INDEX idx_embedding;
+```
+
+When changing index parameters, use drop-and-recreate workflow, then rebuild
index.
+
+## 7. Troubleshooting
+
+### Index not used
+
+Check:
+
+1. Index exists: `SHOW INDEX`
+2. Build finished: `SHOW BUILD INDEX`
+3. Correct function: use `_approximate` functions
+
+### Low recall
+
+Check:
+
+- HNSW parameters (`max_degree`, `ef_construction`, `hnsw_ef_search`)
+- IVF probe parameters (`nprobe`/`ivf_nprobe`)
+- Segment size and post-compaction rebuild
+
+### High latency
+
+Check:
+
+- Cold vs warm query behavior (index loading)
+- Overly large `hnsw_ef_search`
+- Parallel scan setting
+- BE memory pressure
+
+### Data import errors
+
+Common causes:
+
+- dimension mismatch (`dim` vs actual data)
+- null vector values
+- invalid array format
+
+## 8. Hybrid Search Pattern
+
+You can combine ANN with text search by defining both ANN and inverted indexes
in the same table, then filtering with text predicates and ordering with vector
distance. This is a common approach for production RAG pipelines.
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index f8e9f824462..769ffbfe76f 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -328,6 +328,7 @@
"label": "Vector Search",
"items": [
"ai/vector-search/overview",
+ "ai/vector-search/practical-guide",
"ai/vector-search/hnsw",
"ai/vector-search/ivf",
"ai/vector-search/index-management",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
