This is an automated email from the ASF dual-hosted git repository.
Gabriel39 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 bd9be5831bb [docs](lance) Document radius and range vector search
(#4200)
bd9be5831bb is described below
commit bd9be5831bb854a9822845d7ed2e6f372d4c765f
Author: Gabriel <[email protected]>
AuthorDate: Sat Oct 10 09:49:03 2026 +0800
[docs](lance) Document radius and range vector search (#4200)
Companion to https://github.com/apache/doris/pull/68815. Merge the
documentation with the implementation.
Document `distance_lower_bound` and `distance_upper_bound` in the
English and Chinese 4.x Lance Catalog guides, including FLOAT and
squared-L2 semantics, expected results, filtering and offset order,
Top-K limits, and prepared-statement bound parameters.
Explain that only two-sided ranges on explicitly identified IVF_FLAT
indexes use indexed search. Single-sided ranges and quantized or unknown
index types fall back to exact Flat Search, with
`DISTANCE_RANGE_FALLBACK` in EXPLAIN and potentially higher scan cost.
Remove the schema-version upgrade requirement; the implementation
retains the existing protocol version.
Validation: the modified range sections compile as MDX in both locales,
and `git diff --check` passes. A full website build was not run.
---
.../lakehouse/catalogs/lance-catalog.mdx | 47 ++++++++++++++++++++++
.../lakehouse/catalogs/lance-catalog.mdx | 47 ++++++++++++++++++++++
2 files changed, 94 insertions(+)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
index dc8df14cec5..88383ab8990 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
@@ -747,6 +747,8 @@ ORDER BY _distance ASC, user_id;
| `top_k` | 否 | `10` | 跳过 `offset` 后返回的结果数，必须为正整数。 |
| `offset` | 否 | `0` | 在向量检索内部跳过的最近邻数量，必须为非负整数。`top_k + offset` 不能超过无符号 32
位整数上限。 |
| `metric` | 否 | `l2` | 距离类型：`l2`、`cosine`、`dot` 或 `hamming`。`dot_product` 是
`dot` 的别名。`uint8` 向量仅支持 `hamming`；其他当前支持的向量元素类型支持 `l2`、`cosine` 和 `dot`。查询
`cosine`、`dot` 或 `hamming` 索引时必须显式设置 `metric`。不支持整数多向量列及多向量 `hamming` 检索。 |
+| `distance_lower_bound` | 否 | 无下界 | 单向量检索的距离下界，包含边界值，必须是有限的 `FLOAT`。 |
+| `distance_upper_bound` | 否 | 无上界 | 单向量检索的距离上界，不包含边界值，必须是有限的
`FLOAT`。同时设置上下界时，转换为 `FLOAT` 后下界必须小于上界。 |
| `filter` | 否 | - | Lance SQL 条件，在生成候选向量之前执行，即 Prefilter。 |
| `nprobes` | 否 | 最少 `1`，不限制最大值 | IVF 索引探测的分区数量，必须为正整数。不设置时从 1 个分区开始；使用
Prefilter 且候选不足时，Lance 可以继续探测更多分区。显式设置为 `N` 时，最少和最多探测数都会固定为 `N`。 |
| `refine_factor` | 否 | 单向量不启用；多向量为 `1` |
候选集精排倍数，必须为正整数。对于单向量检索，不设置时不基于原始向量重新计算距离，量化索引返回的 `_distance` 可能是近似距离；设置为 `N`
后，Lance 先获取 `(top_k + offset) × N` 个候选，再用原始向量计算真实距离并重新排序。**精排会读取这些候选的原始向量数据；`N`
越大，读取和计算的候选越多，可能显著增加 I/O 并降低查询性能。** 对于单向量检索，设为 `1`
会执行精排，与不设置不同。多向量检索始终使用原始向量精排，默认倍数为 `1`。 |
@@ -756,6 +758,51 @@ ORDER BY _distance ASC, user_id;
不设置 `metric` 时，索引检索和 Flat Search 均使用 `l2`。`uint8` 列必须显式设置 `"metric" =
"hamming"`，不支持默认的 `l2`。多向量检索还需要满足下文的[候选预算限制](#multi-vector-search)。
+### 半径与范围检索
+
+设置 `distance_upper_bound` 可执行半径检索，同时设置上下界可查询区间 `[lower,
upper)`，未设置的一侧不限制距离。距离含义由所选 metric 决定：`l2` 是**欧氏距离的平方**，因此几何半径 `r` 对应的距离上界为 `r
* r`。允许负数边界，适用于 `dot` 等度量。即使存储向量为 Float64，边界也使用 `FLOAT` 精度；非有限值、溢出、相等或反向区间都会被拒绝。
+
+例如，已有 Lance Catalog 表 `lance_catalog.default.items` 包含 `user_id` 和三维 Float32
`embedding` 列，数据如下：
+
+| user_id | embedding | 到 `[0, 0, 0]` 的平方 L2 距离 |
+|---|---|---|
+| 1 | `[0, 0, 0]` | 0 |
+| 2 | `[1, 0, 0]` | 1 |
+| 3 | `[2, 0, 0]` | 4 |
+
+```sql
+SELECT user_id, _distance
+FROM vector_search(
+ "table" = "lance_catalog.default.items",
+ "column" = "embedding",
+ "query_vector" = "[0, 0, 0]",
+ "metric" = "l2",
+ "top_k" = "10",
+ "use_index" = "false",
+ "distance_lower_bound" = "1",
+ "distance_upper_bound" = "4"
+)
+ORDER BY _distance;
+```
+
+```text
++---------+-----------+
+| user_id | _distance |
++---------+-----------+
+| 2 | 1 |
++---------+-----------+
+```
+
+去掉下界后还会返回第 1 行。仅设置上界为 `0` 则返回空结果。`filter` 仍在向量检索前限制候选行，`offset`
在应用距离范围后跳过结果。输出 Schema 不变，包含表中的列和 `FLOAT` 类型的 `_distance`。`EXPLAIN` 会显示
`lanceDistanceRange=[1.0, 4.0)`。
+
+距离边界支持预编译语句中的 `?` 参数，每次执行都会校验并使用当次绑定值，不接受 NULL。若不限制某一侧距离，请省略对应属性。
+
+该功能仍是 **Top-K 查询**，并非返回半径内所有行的接口：返回行数最多为 `top_k`，也可能不足。
+
+对于范围查询，只有同时提供上下界且选中索引明确为 IVF_FLAT 时，Doris 才使用索引检索。单边范围、量化索引以及子类型不明确的索引均回退到精确
Flat Search，即使设置了 `use_index=true`。因距离范围的正确性要求而未选择索引时，`EXPLAIN` 显示
`lanceVectorIndexStatus=DISTANCE_RANGE_FALLBACK`。回退可能增加扫描开销。
+
+IVF_FLAT 索引查询的候选仍取决于 `nprobes` 选择的分区；需要遍历全部候选时使用
`use_index=false`。索引未覆盖的追加数据使用 Flat Search。多向量列不支持距离边界。
+
### 支持的向量索引类型
对于单向量列，Doris 支持以下 Lance 向量索引组合。多向量的索引限制见[多向量检索](#multi-vector-search)。
diff --git a/versioned_docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
b/versioned_docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
index b65c8471e71..a31f05fe3d2 100644
--- a/versioned_docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
+++ b/versioned_docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
@@ -747,6 +747,8 @@ Do not use the unquoted form
`lance_catalog.doris.analytics.items`; it parses as
| `top_k` | No | `10` | Number of results returned after skipping `offset`. It
must be a positive integer. |
| `offset` | No | `0` | Number of nearest neighbors skipped inside the vector
search. It must be a non-negative integer. `top_k + offset` must not exceed the
maximum unsigned 32-bit integer. |
| `metric` | No | `l2` | Distance metric: `l2`, `cosine`, `dot`, or `hamming`.
`dot_product` is an alias for `dot`. `uint8` vectors support only `hamming`;
the other currently supported vector element types support `l2`, `cosine`, and
`dot`. Set `metric` explicitly when querying a `cosine`, `dot`, or `hamming`
index. Integer multi-vector columns and multi-vector `hamming` are unsupported.
|
+| `distance_lower_bound` | No | Unbounded | Inclusive lower distance bound for
single-vector search. Must be a finite `FLOAT`. |
+| `distance_upper_bound` | No | Unbounded | Exclusive upper distance bound for
single-vector search. Must be a finite `FLOAT`. When both bounds are set, the
lower bound must be smaller after conversion to `FLOAT`. |
| `filter` | No | - | Lance SQL condition evaluated before vector candidates
are generated; that is, a Prefilter. |
| `nprobes` | No | Minimum `1`, with no maximum | Number of IVF index
partitions to probe. It must be a positive integer. When unset, Lance starts
with one partition and can probe additional partitions when a Prefilter leaves
too few candidates. Setting it explicitly to `N` fixes both the minimum and
maximum number of probes to `N`. |
| `refine_factor` | No | Single-vector: disabled; multi-vector: `1` |
Candidate refinement multiplier. It must be a positive integer. For
single-vector search, when unset, Lance does not recompute distances from the
original vectors, so `_distance` from a quantized index may be approximate.
When set to `N`, Lance first retrieves `(top_k + offset) × N` candidates,
recomputes their exact distances from the original vectors, and reorders them.
**Refinement reads the original vector data for [...]
@@ -756,6 +758,51 @@ Do not use the unquoted form
`lance_catalog.doris.analytics.items`; it parses as
Omitting `metric` selects `l2` for both indexed and Flat Search paths. For
`uint8` columns, explicitly set `"metric" = "hamming"`; the default `l2` is
unsupported. Multi-vector searches also enforce the [candidate
budgets](#multi-vector-search) described below.
+### Radius and Range Search
+
+Set `distance_upper_bound` for a radius query, or combine both bounds for an
interval `[lower, upper)`. Omitted bounds are unbounded. Distances use the
selected metric: `l2` is **squared Euclidean distance**, so a geometric radius
of `r` corresponds to an upper bound of `r * r`. Negative bounds are accepted,
which is useful for metrics such as `dot`. Bounds use `FLOAT` precision even
when the stored vectors use Float64; non-finite bounds, overflow, equal bounds,
and reversed intervals ar [...]
+
+For example, given an existing Lance Catalog table
`lance_catalog.default.items` with `user_id` and a three-dimensional Float32
`embedding` column:
+
+| user_id | embedding | Squared L2 distance to `[0, 0, 0]` |
+|---|---|---|
+| 1 | `[0, 0, 0]` | 0 |
+| 2 | `[1, 0, 0]` | 1 |
+| 3 | `[2, 0, 0]` | 4 |
+
+```sql
+SELECT user_id, _distance
+FROM vector_search(
+ "table" = "lance_catalog.default.items",
+ "column" = "embedding",
+ "query_vector" = "[0, 0, 0]",
+ "metric" = "l2",
+ "top_k" = "10",
+ "use_index" = "false",
+ "distance_lower_bound" = "1",
+ "distance_upper_bound" = "4"
+)
+ORDER BY _distance;
+```
+
+```text
++---------+-----------+
+| user_id | _distance |
++---------+-----------+
+| 2 | 1 |
++---------+-----------+
+```
+
+Removing the lower bound also returns row 1. Using only an upper bound of `0`
returns no rows. `filter` continues to restrict candidates before vector
search, and `offset` skips results after applying the distance range. The
output schema is unchanged: table columns plus `_distance` of type `FLOAT`.
`EXPLAIN` displays `lanceDistanceRange=[1.0, 4.0)`.
+
+Distance bounds support `?` parameters in prepared statements. Each execution
validates and uses its own bound values; NULL bounds are rejected. Omit the
property to leave that side unbounded.
+
+This remains a **Top-K query**, not an API for returning every row in a
radius: results are capped by `top_k` and can contain fewer rows.
+
+For range queries, Doris uses index search only when both bounds are provided
and the selected index is explicitly identified as IVF_FLAT. Single-sided
ranges, quantized indexes, and indexes with unknown subtypes fall back to exact
Flat Search, even with `use_index=true`. `EXPLAIN` reports
`lanceVectorIndexStatus=DISTANCE_RANGE_FALLBACK` when range safety prevents
index selection. This fallback can increase scan cost.
+
+Indexed IVF_FLAT queries still depend on the partitions selected by `nprobes`;
use `use_index=false` for exhaustive candidate evaluation. Unindexed appended
data is searched with Flat Search. Multi-vector columns do not support distance
bounds.
+
### Supported Vector Index Types
For single-vector columns, Doris supports the following Lance vector index
combinations. Multi-vector index restrictions are described under [Multi-Vector
Search](#multi-vector-search).
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
