This is an automated email from the ASF dual-hosted git repository.
dataroaring 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 344885316a9 docs(table-design): make Index Overview default-first
(#3941)
344885316a9 is described below
commit 344885316a940e3286828e8770678d59e8168c74
Author: Yongqiang YANG <[email protected]>
AuthorDate: Thu Jun 18 05:20:34 2026 -0700
docs(table-design): make Index Overview default-first (#3941)
## What
Rewrite the top of Table Design > Indexes > Index Overview to be
default-first:
- **Lead with what every table already has**: an automatic prefix index
on the sort key and a ZoneMap index on every column.
- **Add a decision table** mapping query pattern → recommended index →
"when needed" (Always / Often / Sometimes / Rarely), so a reader can
tell which indexes are foundational versus situational.
- **Rename** "Choosing an Index by Query Scenario" to "How Each Index
Works", since selection now happens in the table up front and that
section is the deeper explanation.
## Why
The page previously opened with a prose "Quick Selection Guide" and then
four scenario explanations, without stating that two useful indexes
already exist by default. A reader could not quickly tell whether they
need to add anything. Leading with "you already have prefix + ZoneMap;
add a manual index only when a pattern is not covered" matches how an
experienced user actually decides.
## Scope
- English only.
- Applies to both current docs (`docs/`) and
`versioned_docs/version-4.x`.
- No new files, no sidebar changes; the page id is unchanged.
- The in-page anchor reference in "Index Design Principles" was updated
to point at the new "Start Here" section.
---
docs/table-design/index/index-overview.md | 32 ++++++++++++++--------
.../current/table-design/index/index-overview.md | 32 ++++++++++++++--------
.../table-design/index/index-overview.md | 32 ++++++++++++++--------
.../table-design/index/index-overview.md | 32 ++++++++++++++--------
4 files changed, 80 insertions(+), 48 deletions(-)
diff --git a/docs/table-design/index/index-overview.md
b/docs/table-design/index/index-overview.md
index b77147e1d88..0a175abd0a2 100644
--- a/docs/table-design/index/index-overview.md
+++ b/docs/table-design/index/index-overview.md
@@ -6,21 +6,29 @@
}
---
-Apache Doris provides multiple index types to accelerate different query
scenarios. This document starts from query scenarios to help you quickly
understand the principles, applicable scope, and selection strategy of each
type of index.
+Apache Doris accelerates queries with several index types. This page helps you
decide which index, if any, to add, and links to the details of each.
-## Quick Selection Guide
+## Start Here
-Before diving into the details of each index, you can refer to the following
principles to make a quick choice:
+Every table already has two indexes that Doris builds and maintains for you:
-1. **Most frequently used filter conditions**: Designate them as Key columns
to automatically build a prefix index. Prefix indexes deliver the best
filtering effect, but each table can only have one, so use it on the
highest-frequency filter condition.
-2. **Filter acceleration on non-Key fields**: Prefer the [inverted
index](./inverted-index/overview.md). It is widely applicable and supports
combining multiple conditions. If you have special needs, choose one of the
following two options:
- - String LIKE matching needs: add an NGram BloomFilter index
- - Sensitive to index storage space: use a BloomFilter index instead of an
inverted index
-3. **Full-text search on text**: Use the [inverted
index](./inverted-index/overview.md), combined with tokenizers to enable
keyword matching, phrase queries, multi-field combined search, and other
capabilities.
-4. **Vector similarity search**: Use the [vector index (ANN
index)](./vector-index/overview.md) to accelerate approximate nearest neighbor
queries for RAG, semantic search, recommendation, and image/audio/video
retrieval.
-5. **Performance below expectations**: Use QueryProfile to analyze how much
data the index filtered out and how much time it consumed. See the dedicated
documentation for each index for details.
+- A **[prefix index](./prefix-index.md)** on the sort key, which speeds up
filters on the leading Key columns. Make your most frequent filter a leading
Key column to use it.
+- A **ZoneMap index** on every column, which skips data blocks that fall
outside a range or equality filter.
-## Choosing an Index by Query Scenario
+Add a manual index only when these don't cover your query pattern:
+
+| Your query pattern | Recommended index | When needed |
+| --- | --- | --- |
+| Filter on your highest-frequency column | Make it a leading Key column
(prefix index) | Always design this first |
+| Equality or range filter on a non-Key column | [Inverted
index](./inverted-index/overview.md) | Often |
+| `LIKE` substring match on text | [NGram BloomFilter
index](./ngram-bloomfilter-index.md) | Sometimes |
+| Equality filter where index size matters more than flexibility |
[BloomFilter index](./bloomfilter.md) | Rarely; the inverted index is usually
preferred |
+| Full-text search: keyword, phrase, or multi-field | [Inverted
index](./inverted-index/overview.md) | When you search text |
+| Vector similarity (Top-K nearest neighbor) | [Vector index
(ANN)](./vector-index/overview.md) | For RAG, semantic search, recommendation,
and media retrieval |
+
+If a query is slower than expected, use QueryProfile to see how much each
index filtered out and how long it took. See each index's page for details.
+
+## How Each Index Works
Apache Doris provides four categories of indexes for different query
scenarios: **point-query indexes**, **skip indexes**, **full-text search
indexes**, and **vector indexes**.
@@ -130,4 +138,4 @@ The following table lists the acceleration support of each
index type for common
## Index Design Principles
-Index design and tuning for a database table are closely tied to data
characteristics and query patterns, and require testing and tuning based on the
actual scenario. Although there is no silver bullet, Apache Doris keeps
lowering the difficulty of using indexes. In actual design, you can refer to
the three principles in the [Quick Selection Guide](#quick-selection-guide)
above for index selection and testing.
+Index design and tuning for a database table are closely tied to data
characteristics and query patterns, and require testing and tuning based on the
actual scenario. Although there is no silver bullet, Apache Doris keeps
lowering the difficulty of using indexes. When designing indexes, use the
decision table in [Start Here](#start-here) to choose and test them.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/index-overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/index-overview.md
index 2f9ffe69ec9..b5297253f4b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/index-overview.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/index-overview.md
@@ -6,21 +6,29 @@
}
---
-Apache Doris 提供多种索引以加速不同的查询场景。本文将从查询场景出发，帮助你快速理解各类索引的原理、适用范围以及选择策略。
+Apache Doris 提供多种索引来加速查询。本文帮助你判断是否需要、以及需要哪一种索引，并提供各索引的详细链接。
-## 快速选型指南
+## 从这里开始
-在深入了解索引细节前，可以参考以下原则快速做出选型：
+每张表都已经拥有两种由 Doris 自动构建和维护的索引：
-1. **最频繁使用的过滤条件**：将其指定为 Key 列，自动建立前缀索引。前缀索引过滤效果最好，但每个表只能有一个，因此要用在最高频的过滤条件上。
-2. **非 Key
字段需要过滤加速**：首选[倒排索引](./inverted-index/overview.md)，它适用面广、支持多条件组合。如果有特殊需求可选用以下两种：
- - 字符串 LIKE 匹配需求：增加 NGram BloomFilter 索引
- - 对索引存储空间敏感：使用 BloomFilter 索引替代倒排索引
-3.
**文本全文检索**：使用[倒排索引](./inverted-index/overview.md)，配合分词器实现关键词匹配、短语查询、多字段联合检索等能力。
-4. **向量相似度检索**：使用[向量索引（ANN 索引）](./vector-index/overview.md)，加速
RAG、语义搜索、推荐、图像/音视频检索等近似最近邻查询。
-5. **性能不及预期**：通过 QueryProfile 分析索引过滤掉的数据量和消耗的时间，详见各个索引的专题文档。
+- **[前缀索引](./prefix-index.md)**：建立在排序键上，可加速对前导 Key 列的过滤。将你最频繁的过滤列设计为前导 Key
列即可利用它。
+- **ZoneMap 索引**：建立在每一列上，可跳过不满足范围或等值过滤条件的数据块。
-## 按查询场景选择索引
+仅当上述索引无法覆盖某种查询模式时，才需要添加手动索引：
+
+| 你的查询模式 | 推荐索引 | 使用频率 |
+| --- | --- | --- |
+| 在最高频的列上过滤 | 将其设为前导 Key 列（前缀索引） | 总是优先设计 |
+| 在非 Key 列上做等值或范围过滤 | [倒排索引](./inverted-index/overview.md) | 经常 |
+| 文本 `LIKE` 子串匹配 | [NGram BloomFilter 索引](./ngram-bloomfilter-index.md) | 有时 |
+| 等值过滤且更看重索引体积而非灵活性 | [BloomFilter 索引](./bloomfilter.md) | 很少；通常更推荐倒排索引 |
+| 全文检索：关键词、短语或多字段 | [倒排索引](./inverted-index/overview.md) | 需要文本检索时 |
+| 向量相似度（Top-K 最近邻） | [向量索引（ANN）](./vector-index/overview.md) | 用于
RAG、语义搜索、推荐、多媒体检索 |
+
+如果查询慢于预期，可用 QueryProfile 查看各索引过滤掉了多少数据、耗时多少。详见各索引的专题文档。
+
+## 各类索引的工作原理
Apache Doris 针对不同查询场景提供四类索引：**点查索引**、**跳数索引**、**全文检索索引** 与 **向量索引**。
@@ -130,4 +138,4 @@ Apache Doris 提供三种跳数索引：
## 索引设计原则
-数据库表的索引设计与优化跟数据特点和查询模式密切相关，需根据实际场景测试和调优。虽然没有“银弹”，Apache Doris
仍持续降低用户使用索引的难度。在实际设计时，可参考前文“[快速选型指南](#快速选型指南)”中的三条原则进行索引选择和测试。
+数据库表的索引设计与优化跟数据特点和查询模式密切相关，需根据实际场景测试和调优。虽然没有“银弹”，Apache Doris
仍持续降低用户使用索引的难度。在实际设计时，可参考前文“[从这里开始](#从这里开始)”中的决策表进行索引选择和测试。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/index/index-overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/index/index-overview.md
index 2f9ffe69ec9..b5297253f4b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/index/index-overview.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/table-design/index/index-overview.md
@@ -6,21 +6,29 @@
}
---
-Apache Doris 提供多种索引以加速不同的查询场景。本文将从查询场景出发，帮助你快速理解各类索引的原理、适用范围以及选择策略。
+Apache Doris 提供多种索引来加速查询。本文帮助你判断是否需要、以及需要哪一种索引，并提供各索引的详细链接。
-## 快速选型指南
+## 从这里开始
-在深入了解索引细节前，可以参考以下原则快速做出选型：
+每张表都已经拥有两种由 Doris 自动构建和维护的索引：
-1. **最频繁使用的过滤条件**：将其指定为 Key 列，自动建立前缀索引。前缀索引过滤效果最好，但每个表只能有一个，因此要用在最高频的过滤条件上。
-2. **非 Key
字段需要过滤加速**：首选[倒排索引](./inverted-index/overview.md)，它适用面广、支持多条件组合。如果有特殊需求可选用以下两种：
- - 字符串 LIKE 匹配需求：增加 NGram BloomFilter 索引
- - 对索引存储空间敏感：使用 BloomFilter 索引替代倒排索引
-3.
**文本全文检索**：使用[倒排索引](./inverted-index/overview.md)，配合分词器实现关键词匹配、短语查询、多字段联合检索等能力。
-4. **向量相似度检索**：使用[向量索引（ANN 索引）](./vector-index/overview.md)，加速
RAG、语义搜索、推荐、图像/音视频检索等近似最近邻查询。
-5. **性能不及预期**：通过 QueryProfile 分析索引过滤掉的数据量和消耗的时间，详见各个索引的专题文档。
+- **[前缀索引](./prefix-index.md)**：建立在排序键上，可加速对前导 Key 列的过滤。将你最频繁的过滤列设计为前导 Key
列即可利用它。
+- **ZoneMap 索引**：建立在每一列上，可跳过不满足范围或等值过滤条件的数据块。
-## 按查询场景选择索引
+仅当上述索引无法覆盖某种查询模式时，才需要添加手动索引：
+
+| 你的查询模式 | 推荐索引 | 使用频率 |
+| --- | --- | --- |
+| 在最高频的列上过滤 | 将其设为前导 Key 列（前缀索引） | 总是优先设计 |
+| 在非 Key 列上做等值或范围过滤 | [倒排索引](./inverted-index/overview.md) | 经常 |
+| 文本 `LIKE` 子串匹配 | [NGram BloomFilter 索引](./ngram-bloomfilter-index.md) | 有时 |
+| 等值过滤且更看重索引体积而非灵活性 | [BloomFilter 索引](./bloomfilter.md) | 很少；通常更推荐倒排索引 |
+| 全文检索：关键词、短语或多字段 | [倒排索引](./inverted-index/overview.md) | 需要文本检索时 |
+| 向量相似度（Top-K 最近邻） | [向量索引（ANN）](./vector-index/overview.md) | 用于
RAG、语义搜索、推荐、多媒体检索 |
+
+如果查询慢于预期，可用 QueryProfile 查看各索引过滤掉了多少数据、耗时多少。详见各索引的专题文档。
+
+## 各类索引的工作原理
Apache Doris 针对不同查询场景提供四类索引：**点查索引**、**跳数索引**、**全文检索索引** 与 **向量索引**。
@@ -130,4 +138,4 @@ Apache Doris 提供三种跳数索引：
## 索引设计原则
-数据库表的索引设计与优化跟数据特点和查询模式密切相关，需根据实际场景测试和调优。虽然没有“银弹”，Apache Doris
仍持续降低用户使用索引的难度。在实际设计时，可参考前文“[快速选型指南](#快速选型指南)”中的三条原则进行索引选择和测试。
+数据库表的索引设计与优化跟数据特点和查询模式密切相关，需根据实际场景测试和调优。虽然没有“银弹”，Apache Doris
仍持续降低用户使用索引的难度。在实际设计时，可参考前文“[从这里开始](#从这里开始)”中的决策表进行索引选择和测试。
diff --git a/versioned_docs/version-4.x/table-design/index/index-overview.md
b/versioned_docs/version-4.x/table-design/index/index-overview.md
index b77147e1d88..0a175abd0a2 100644
--- a/versioned_docs/version-4.x/table-design/index/index-overview.md
+++ b/versioned_docs/version-4.x/table-design/index/index-overview.md
@@ -6,21 +6,29 @@
}
---
-Apache Doris provides multiple index types to accelerate different query
scenarios. This document starts from query scenarios to help you quickly
understand the principles, applicable scope, and selection strategy of each
type of index.
+Apache Doris accelerates queries with several index types. This page helps you
decide which index, if any, to add, and links to the details of each.
-## Quick Selection Guide
+## Start Here
-Before diving into the details of each index, you can refer to the following
principles to make a quick choice:
+Every table already has two indexes that Doris builds and maintains for you:
-1. **Most frequently used filter conditions**: Designate them as Key columns
to automatically build a prefix index. Prefix indexes deliver the best
filtering effect, but each table can only have one, so use it on the
highest-frequency filter condition.
-2. **Filter acceleration on non-Key fields**: Prefer the [inverted
index](./inverted-index/overview.md). It is widely applicable and supports
combining multiple conditions. If you have special needs, choose one of the
following two options:
- - String LIKE matching needs: add an NGram BloomFilter index
- - Sensitive to index storage space: use a BloomFilter index instead of an
inverted index
-3. **Full-text search on text**: Use the [inverted
index](./inverted-index/overview.md), combined with tokenizers to enable
keyword matching, phrase queries, multi-field combined search, and other
capabilities.
-4. **Vector similarity search**: Use the [vector index (ANN
index)](./vector-index/overview.md) to accelerate approximate nearest neighbor
queries for RAG, semantic search, recommendation, and image/audio/video
retrieval.
-5. **Performance below expectations**: Use QueryProfile to analyze how much
data the index filtered out and how much time it consumed. See the dedicated
documentation for each index for details.
+- A **[prefix index](./prefix-index.md)** on the sort key, which speeds up
filters on the leading Key columns. Make your most frequent filter a leading
Key column to use it.
+- A **ZoneMap index** on every column, which skips data blocks that fall
outside a range or equality filter.
-## Choosing an Index by Query Scenario
+Add a manual index only when these don't cover your query pattern:
+
+| Your query pattern | Recommended index | When needed |
+| --- | --- | --- |
+| Filter on your highest-frequency column | Make it a leading Key column
(prefix index) | Always design this first |
+| Equality or range filter on a non-Key column | [Inverted
index](./inverted-index/overview.md) | Often |
+| `LIKE` substring match on text | [NGram BloomFilter
index](./ngram-bloomfilter-index.md) | Sometimes |
+| Equality filter where index size matters more than flexibility |
[BloomFilter index](./bloomfilter.md) | Rarely; the inverted index is usually
preferred |
+| Full-text search: keyword, phrase, or multi-field | [Inverted
index](./inverted-index/overview.md) | When you search text |
+| Vector similarity (Top-K nearest neighbor) | [Vector index
(ANN)](./vector-index/overview.md) | For RAG, semantic search, recommendation,
and media retrieval |
+
+If a query is slower than expected, use QueryProfile to see how much each
index filtered out and how long it took. See each index's page for details.
+
+## How Each Index Works
Apache Doris provides four categories of indexes for different query
scenarios: **point-query indexes**, **skip indexes**, **full-text search
indexes**, and **vector indexes**.
@@ -130,4 +138,4 @@ The following table lists the acceleration support of each
index type for common
## Index Design Principles
-Index design and tuning for a database table are closely tied to data
characteristics and query patterns, and require testing and tuning based on the
actual scenario. Although there is no silver bullet, Apache Doris keeps
lowering the difficulty of using indexes. In actual design, you can refer to
the three principles in the [Quick Selection Guide](#quick-selection-guide)
above for index selection and testing.
+Index design and tuning for a database table are closely tied to data
characteristics and query patterns, and require testing and tuning based on the
actual scenario. Although there is no silver bullet, Apache Doris keeps
lowering the difficulty of using indexes. When designing indexes, use the
decision table in [Start Here](#start-here) to choose and test them.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
