This is an automated email from the ASF dual-hosted git repository.
morningman 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 a0312e41f13f [docs](lance) Document automatic vector and BM25 SQL
search (#4441)
a0312e41f13f is described below
commit a0312e41f13f47ff7da7855759d0d6f7ed3b5fc1
Author: Gabriel <[email protected]>
AuthorDate: Fri Oct 23 16:40:47 2026 +0800
[docs](lance) Document automatic vector and BM25 SQL search (#4441)
Ordinary SQL search over Lance is not described in the current 4.x
reference. This documents the branch-4.2 behavior introduced by
https://github.com/apache/doris/pull/69346 (implementation PR is still
open; this documentation depends on it).
For example, an eligible `ORDER BY
cosine_similarity_approximate(embedding, [0.1,0.2,0.3,0.4]) DESC LIMIT
10` becomes native Lance cosine retrieval, with `1 - _distance`
projected as similarity. Exact functions and ACL/EXISTS queries retain
scalar distance evaluation and global Top-N.
- Add matching English/Chinese guidance for five approximate vector
functions, MATCH/BM25, ordering and result conversion, native versus
scalar NULL/NaN/zero-vector semantics, UInt8 Hamming validation, bounded
row-ID prefilters, and JOIN/EXISTS boundaries.
- Add English/Chinese SQL references for `cosine_distance_approximate`,
`cosine_similarity_approximate`, `hamming_distance`, and
`hamming_distance_approximate`, including normal, zero/empty, NULL, and
out-of-range examples.
- Add navigation entries, link from Lance Catalog, and clarify that
ordinary SQL rewritten to search TVFs can qualify for two-phase output
reads.
Version scope: this change intentionally updates **4.x English and
Chinese only**. The implementation targets `branch-4.2`, not Doris
master; current/development and older-version pages are not being
advertised as supporting it. This explains the governance
version-counterpart warnings. Availability wording requires a Doris 4.2
build containing this capability, rather than implying every build with
the explicit TVFs already supports rewriting.
Validation: all 12 changed documentation pages compiled with the
Docusaurus MDX processor; changed-page link checks found no broken
links; SQL-function structure checks passed; paired English/Chinese SQL
blocks match; all six added sidebar references resolve; whitespace and
added-content disclosure checks passed. SEO descriptions satisfy the
configured length range. Remaining SEO duplicate-title warnings reflect
shared SQL identifiers across locales and existing versioned titles.
Full-repository sidebar lint reports unrelated existing findings. Full
site build and live SQL execution were not run.
---
.../best-practices/lance-hybrid-search.mdx | 90 +++++++++++++++++++++-
.../lakehouse/catalogs/lance-catalog.mdx | 6 +-
.../cosine-distance-approximate.md | 66 ++++++++++++++++
.../cosine-similarity-approximate.md | 66 ++++++++++++++++
.../hamming-distance-approximate.md | 74 ++++++++++++++++++
.../distance-functions/hamming-distance.md | 74 ++++++++++++++++++
.../best-practices/lance-hybrid-search.mdx | 90 +++++++++++++++++++++-
.../lakehouse/catalogs/lance-catalog.mdx | 6 +-
.../cosine-distance-approximate.md | 66 ++++++++++++++++
.../cosine-similarity-approximate.md | 66 ++++++++++++++++
.../hamming-distance-approximate.md | 74 ++++++++++++++++++
.../distance-functions/hamming-distance.md | 74 ++++++++++++++++++
versioned_sidebars/version-4.x-sidebars.json | 6 ++
13 files changed, 752 insertions(+), 6 deletions(-)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
index 042f8ed89735..5684fd5dd382 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
@@ -2,7 +2,7 @@
{
"title": "Lance 混合检索性能最佳实践",
"language": "zh-CN",
- "description": "指导 Apache Doris 用户优化 Lance 标量过滤与向量、全文混合检索：对齐索引 Fragment
覆盖范围、选择 Segment 粒度、配置共享缓存并分析查询 Profile。"
+ "description": "指导 Apache Doris 用户使用 Lance 向量与 BM25 自动检索下推，理解近似函数、预过滤、NULL
与零向量语义以及 JOIN 边界，并通过对齐索引 Fragment 范围、选择 Segment 粒度和分析 Profile 优化性能。"
}
---
@@ -12,6 +12,94 @@
Lance Catalog 为实验性功能，从 Apache Doris 4.2 开始支持。请先按 [Lance
Catalog](../catalogs/lance-catalog.mdx) 配置访问并确认读写版本兼容性。Doris 读取已有 Lance
索引，索引构建和维护由兼容的 Lance 工具完成。最新 Lance SDK 或上游提案不代表当前 Doris 内置读取器已经支持对应能力。
:::
+## 普通 SQL 的自动检索下推 {#automatic-search}
+
+在包含 Lance 自动检索能力的 Doris 4.2 构建中，符合条件的普通 SQL 可以使用与显式 TVF 相同的原生检索路径。这与直接调用 TVF
是两个层次的能力，不能因为较早构建支持 `vector_search()` 就认为它也支持自动改写。无需单独的自动检索会话开关。
+
+### 函数映射
+
+| SQL 表达式 | 要求的排序方向 | Lance 度量及 SQL 返回值 |
+|---|---|---|
+|
[l2_distance_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/l2-distance-approximate.md)
| `ASC` | `l2`；返回 `CAST(sqrt(_distance) AS FLOAT)`，即欧氏距离，而非原生平方 L2。 |
+|
[inner_product_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/inner-product-approximate.md)
| `DESC` | `dot`；返回 `1.0f - _distance`，即内积相似度。 |
+|
[cosine_distance_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md)
| `ASC` | `cosine`；返回原生余弦距离。 |
+|
[cosine_similarity_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md)
| `DESC` | `cosine`；返回 `1.0f - _distance`。 |
+|
[hamming_distance_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md)
| `ASC` | `hamming`；返回不同 bit 的数量。 |
+| `score()` 配合 `MATCH_ANY`、`MATCH_ALL` 或 `MATCH_PHRASE` | `DESC` | Lance
BM25；分别对应 Match OR、Match AND 或 Phrase。 |
+
+精确距离和相似度函数保留标量执行，包括 `cosine_distance()`、`cosine_similarity()` 和
[hamming_distance](../../sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md)。`l1_distance()`
也保留标量执行，当前内置 Lance 向量检索 API 未提供 L1 度量。
+
+### 向量与 BM25 示例
+
+配置 Catalog 后，假设 `lance_catalog.default.items` 包含 `id`、`category`、`content`、四维
Float32 fixed-size-list 列 `embedding`，以及三字节 UInt8 fixed-size-list 列
`binary_embedding`。需要索引加速时，通过 Lance 工具构建兼容的向量索引，并为 `content` 创建已提交的 FTS 索引。
+
+```sql
+SELECT id, cosine_distance_approximate(embedding, [0.1,0.2,0.3,0.4]) AS
distance
+FROM lance_catalog.default.items
+WHERE category = 'book'
+ORDER BY distance ASC LIMIT 10 OFFSET 5;
+
+SELECT id, cosine_similarity_approximate(embedding, [0.1,0.2,0.3,0.4]) AS
similarity
+FROM lance_catalog.default.items
+ORDER BY similarity DESC LIMIT 10;
+
+SELECT id, hamming_distance_approximate(binary_embedding, [0,255,170]) AS
distance
+FROM lance_catalog.default.items
+ORDER BY distance ASC LIMIT 10;
+
+SELECT id, score() AS relevance
+FROM lance_catalog.default.items
+WHERE content MATCH_ALL 'storage engine' AND category = 'book'
+ORDER BY relevance DESC LIMIT 10;
+```
+
+第一条查询先在 `category = 'book'` 范围内检索，再裁剪候选。每个 Split 请求 15 个候选且 offset 为零，Doris
合并后执行最终的 `OFFSET 5 LIMIT 10`。其余查询按各自顺序返回最多 10 个邻居或 BM25
命中。索引检索可能是近似的，实际行数也可能少于请求值。已有兼容索引会被复用，未覆盖数据沿用 Flat Search 路径；BM25 必须有已有 FTS 索引。
+
+### 下推条件与回退
+
+- 查询形状必须是直接 Lance Catalog 表扫描、可选过滤、投影以及仅有一个检索排序键且 `LIMIT` 为正的
Top-N。JOIN/EXISTS、第二排序键、DISTINCT、表采样及不可移动的投影表达式都会阻止此改写。
+- 浮点度量要求物理 Float32 fixed-size-list，Hamming 要求物理 UInt8
fixed-size-list。查询向量必须是维度匹配的常量数组。Float16/Float64、多向量列及任意改变元素值的 cast
不会自动改写。UInt8 在 Doris 中映射为 SMALLINT，安全扩宽到 Hamming 函数的 BIGINT 参数不会改变 byte 值。
+- 向量查询存在不可下推的残余谓词、反向检索排序、缺失原生元数据或原生向量/Schema 校验未通过时，保留标量执行。自动改写要求 `LIMIT +
OFFSET` 不超过原生 UINT32 候选预算，该限制不约束普通标量 SQL。
+- BM25 要求直接字符串列上有一个顶层受支持 MATCH 谓词、字面量查询、使用索引存储的 analyzer，并按 `score()`
降序排列。其余标量谓词必须全部可下推。允许将 `score() > literal`、`score() >= literal`
作为分数下界残余条件，不支持分数上界或其他分数谓词。不支持的带分数查询形状会报错，不会悄悄将 `score()` 当成普通标量计算。
+- 分数取决于 Lance 已存储的 analyzer、索引及快照全局统计，不保证与独立建立的 Doris
内表索引得到相同数值。此改写不会启用模糊检索、analyzer 覆盖或多列 `SEARCH()` 表达式。受支持的多向量查询及
`nprobes`、`refine_factor`、`ef` 等调优应使用显式 TVF。
+
+### 原生近似检索语义
+
+`_approximate` 后缀表示符合条件的 Top-N 可以采用 Lance
原生候选语义；未改写时执行标量内核。若必须穷举排名或对所有存储行执行标量输入校验，应使用精确函数。
+
+| 输入 | 标量执行 | 符合条件的原生检索 |
+|---|---|---|
+| 存储的 NULL 向量 | 报错 | 不进入候选集。 |
+| 存储向量产生 NaN 距离 | 可能返回 NaN | 被排除，因此可能少返回行。 |
+| 向量元素为 NULL | 报错 | 不属于受支持的原生输入范围，必须保证元素非 NULL。 |
+| 存储的零范数余弦向量 | 距离为 2，相似度为 0 | 产生未定义/NaN 原生距离时被排除。 |
+| 余弦查询范数为零或非有限值，包括 Float32 平方范数上溢/下溢 | 保留标量行为 | 跳过自动改写。 |
+| Hamming 输入 | 整数数组，元素均在 `[0,255]` | 物理 UInt8 向量及合法的 byte 查询。 |
+
+原生余弦计算和索引估计的数值可能与标量结果不同。Hamming 统计不同 bit，而非不同
byte：`hamming_distance([0,255,170], [255,0,85])` 返回 24。Hamming 在隐式 cast
前拒绝浮点、Decimal 和 LARGEINT 数组，并在 byte 转换前拒绝越界值。精确函数继续提供标量执行语义。
+
+### WHERE 预过滤与 JOIN 边界
+
+Lance 表自身完全可下推的谓词在同一固定快照上先于检索执行。Doris 先尝试仅扫描 row ID，并在查询内的检索 Reader 之间共享完整
allowlist；空列表表示无行。超过 65,536 个 ID
时，丢弃部分列表，改为保留完整原生谓词预过滤。临时与缓存列表的容量均计入查询内存限额，停止或失败的收集不会进入缓存。这与普通扫描中的 JOIN Runtime
Filter 下推是不同机制。
+
+以下 ACL 示例假设 `internal.auth.allowed_items` 包含 `item_id` 和 `principal_id`。
+
+```sql
+SELECT d.id,
+ l2_distance_approximate(d.embedding, [0.1,0.2,0.3,0.4]) AS distance
+FROM lance_catalog.default.items d
+WHERE EXISTS (
+ SELECT 1 FROM internal.auth.allowed_items a
+ WHERE a.item_id = d.id AND a.principal_id = 42
+)
+ORDER BY distance ASC
+LIMIT 10;
+```
+
+该查询保留 JOIN、标量距离计算和全局 Top-N。此改写不会跨越 ACL 半连接，也不会把业务 ID 映射为 Lance 原生 `_rowid`。在
ACL 过滤前直接选择未过滤 Top-K 可能遗漏最近的授权行。增加第二排序键同样会阻止自动改写。
+
+对实际查询运行 `EXPLAIN`，确认 `externalSearchType=VECTOR` 及
`lanceMetric=l2|dot|cosine|hamming`，或
`externalSearchType=FULL_TEXT`。`LanceRowIdPrefilterTime`、`LanceRowIdPrefilterRows`、`LanceRowIdPrefilterCacheHits`
和 `LanceRowIdPrefilterFallbacks` 反映 Doris allowlist 工作，与下文原生 row-ID loader
指标不同。需要检索调参或此规则之外的受支持查询形状时，使用显式 TVF。自动改写后的检索满足相应条件时，也可以使用已有两阶段输出读取。
+
## 1. 将候选生成所需的过滤条件放在检索内部 {#candidate-filters}
假设已配置的表包含整数列 `id`、字符串列 `category`、字符串列 `content` 和四维向量列
`embedding`，对必须影响候选生成的条件，应使用 TVF 的 `filter` 参数。向量索引需要匹配维度和距离度量；文本列需要已有提交完成的 FTS
索引。
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 18504b391dcd..3457a7e1b371 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
@@ -2,7 +2,7 @@
{
"title": "Lance Catalog",
"language": "zh-CN",
- "description": "Apache Doris Lance Catalog 使用指南：通过 Filesystem 或 REST
Namespace 访问 Lance 数据集，支持并行读取、谓词下推、S3/Local TVF、索引查看、向量检索以及全文检索。"
+ "description": "了解 Apache Doris Lance Catalog 的配置与查询方法，涵盖 Filesystem 和
REST Namespace、向量与 BM25 检索、普通 SQL 自动下推，以及数据类型和版本兼容性限制。"
}
---
@@ -729,6 +729,8 @@ Lance 文件 TVF 还有以下限制：
## 向量检索
+包含 Doris 4.2 Lance 自动检索能力的构建也支持对符合条件的普通 SQL 下推原生向量 Top-N 和 MATCH/BM25
检索。五种近似函数、度量转换、输入语义及 JOIN/EXISTS 边界参见[普通 SQL
的自动检索下推](../best-practices/lance-hybrid-search.mdx#automatic-search)。下文 TVF
继续用于显式调参及自动改写范围之外的受支持查询形状。
+
`vector_search()` 是一个关系型 TVF，用于对 Lance 表的向量列执行 Top-K 检索。它既可以使用 Lance
中已建立的向量索引，也可以执行 Flat Search。
### 语法和示例
@@ -1116,7 +1118,7 @@ BE 的 `/metrics` 还提供以
`doris_be_lance_session_index_cache_` 和 `doris_
满足以下条件时，Doris 才会使用两阶段读取：
-1. 查询通过 `vector_search()` 或 `full_text_search()` 读取 Lance，且执行计划中存在可进行延迟物化的
TopN。普通 Lance 表扫描和 Lance 文件 TVF 当前不适用此开关。
+1. 查询通过 `vector_search()` 或 `full_text_search()` 读取 Lance，且执行计划中存在可进行延迟物化的
TopN。普通 SQL 被改写为上述检索 TVF 后也可能符合条件；未改写的标量表扫描和 Lance 文件 TVF 不适用。
2. Boolean 类型的会话变量 `enable_lance_lazy_materialization` 为 `true`，默认开启。
3. 查询至少包含一个可以延迟读取的顶层列。仅用于最终 `SELECT` 输出的列可以延迟；Post-filter、`ORDER BY` 或其他 TopN
前表达式使用的列必须在第一阶段读取。嵌套子列当前不能延迟读取。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md
new file mode 100644
index 000000000000..74921aee2c6b
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "COSINE_DISTANCE_APPROXIMATE",
+ "language": "zh-CN",
+ "description": "介绍 Apache Doris 4.2 COSINE_DISTANCE_APPROXIMATE 的语法、FLOAT
返回值、零向量和 NULL 行为，以及 Lance Top-N 自动下推的排序方向、查询向量类型与近似检索边界。"
+}
+---
+
+## 描述
+
+计算两个向量的余弦距离。 NULL 数组或 NULL 元素会报错。
+
+在包含此能力的 Doris 4.2 构建中可用。 符合条件的 Lance Top-N 可使用原生近似检索；其他查询执行标量内核。
+
+## 语法
+
+```sql
+COSINE_DISTANCE_APPROXIMATE(<array1>, <array2>)
+```
+
+## 参数
+
+| 参数 | 描述 |
+|---|---|
+| `<array1>` | 数值数组，隐式转换为 ARRAY<FLOAT>，转换可能影响精度。 |
+| `<array2>` | 数值数组，隐式转换为 ARRAY<FLOAT>，转换可能影响精度。 两个数组的长度必须相同。 |
+
+## 返回值
+
+返回 `FLOAT`，值越小越接近。标量计算为 `1 - dot(x,y) / (norm(x) * norm(y))`；任一向量范数为零时返回
2，包括空数组对。 长度不匹配、NULL 数组或 NULL 元素会报错，不返回 NULL。 原生检索的候选范围、数值精度及 NULL/NaN
行为可能与标量执行不同，详见[自动检索下推](../../../../lakehouse/best-practices/lance-hybrid-search.mdx#automatic-search)。
+
+## 示例
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE([1,0], [0,1]) AS value;
+```
+
+```text
+value
+1
+```
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE([0,0], [1,0]) AS value;
+```
+
+```text
+value
+2
+```
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_distance_approximate cannot be null
+```
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_distance_approximate cannot have null
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md
new file mode 100644
index 000000000000..a01e6ab353d6
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "COSINE_SIMILARITY_APPROXIMATE",
+ "language": "zh-CN",
+ "description": "介绍 Apache Doris 4.2 COSINE_SIMILARITY_APPROXIMATE
的语法、FLOAT 返回值、零向量和 NULL 行为，以及 Lance Top-N 自动下推的排序方向、查询向量类型与近似检索边界。"
+}
+---
+
+## 描述
+
+计算两个向量的余弦相似度。 NULL 数组或 NULL 元素会报错。
+
+在包含此能力的 Doris 4.2 构建中可用。 符合条件的 Lance Top-N 可使用原生近似检索；其他查询执行标量内核。
+
+## 语法
+
+```sql
+COSINE_SIMILARITY_APPROXIMATE(<array1>, <array2>)
+```
+
+## 参数
+
+| 参数 | 描述 |
+|---|---|
+| `<array1>` | 数值数组，隐式转换为 ARRAY<FLOAT>，转换可能影响精度。 |
+| `<array2>` | 数值数组，隐式转换为 ARRAY<FLOAT>，转换可能影响精度。 两个数组的长度必须相同。 |
+
+## 返回值
+
+返回 `FLOAT`，值越大越相似。标量计算为 `dot(x,y) / (norm(x) * norm(y))`；任一向量范数为零时返回 0，包括空数组对。
长度不匹配、NULL 数组或 NULL 元素会报错，不返回 NULL。 原生检索的候选范围、数值精度及 NULL/NaN
行为可能与标量执行不同，详见[自动检索下推](../../../../lakehouse/best-practices/lance-hybrid-search.mdx#automatic-search)。
+
+## 示例
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE([1,0], [0,1]) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE([0,0], [1,0]) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_similarity_approximate cannot be null
+```
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_similarity_approximate cannot have
null
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md
new file mode 100644
index 000000000000..7d593c3dd68a
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md
@@ -0,0 +1,74 @@
+---
+{
+ "title": "HAMMING_DISTANCE_APPROXIMATE",
+ "language": "zh-CN",
+ "description": "介绍 Apache Doris 4.2 的近似 Hamming 距离函数，涵盖整数 byte 数组参数、XOR 后
bit 计数、NULL 与越界校验，以及 Lance UInt8 向量 Top-N 自动下推条件和标量回退语义。"
+}
+---
+
+## 描述
+
+计算两个 byte 向量的 Hamming 距离，即按位 XOR 后不同 bit 的数量。 NULL 数组或 NULL 元素会报错。
+
+在包含此能力的 Doris 4.2 构建中可用。 符合条件的 Lance Top-N 可使用原生近似检索；其他查询执行标量内核。
+
+## 语法
+
+```sql
+HAMMING_DISTANCE_APPROXIMATE(<array1>, <array2>)
+```
+
+## 参数
+
+| 参数 | 描述 |
+|---|---|
+| `<array1>` | 整数数组，允许 TINYINT、SMALLINT、INT、BIGINT，统一转换为 ARRAY<BIGINT>；每个元素必须在
`[0,255]`。不接受浮点、Decimal、LARGEINT 数组。 |
+| `<array2>` | 整数数组，允许 TINYINT、SMALLINT、INT、BIGINT，统一转换为 ARRAY<BIGINT>；每个元素必须在
`[0,255]`。不接受浮点、Decimal、LARGEINT 数组。 两个数组的长度必须相同。 |
+
+## 返回值
+
+返回 `FLOAT`，值越小越接近。空数组对返回 0；N 字节向量的最大距离是 8N。 长度不匹配、NULL 数组或 NULL 元素会报错，不返回
NULL。 越界元素也会报错。 原生检索的候选范围、数值精度及 NULL/NaN
行为可能与标量执行不同，详见[自动检索下推](../../../../lakehouse/best-practices/lance-hybrid-search.mdx#automatic-search)。
+
+## 示例
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([0,255,170], [255,0,85]) AS value;
+```
+
+```text
+value
+24
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([], []) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance_approximate cannot be null
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance_approximate cannot have
null
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([256], [0]);
+```
+
+```text
+ERROR: Hamming vector elements must be integers in [0, 255]
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md
new file mode 100644
index 000000000000..ad74ec8156c8
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md
@@ -0,0 +1,74 @@
+---
+{
+ "title": "HAMMING_DISTANCE",
+ "language": "zh-CN",
+ "description": "介绍 Apache Doris 4.2 HAMMING_DISTANCE 精确距离函数：对整数 byte 数组执行
XOR 和 bit 计数，说明参数范围、返回类型、空数组、NULL 与越界输入的报错行为。"
+}
+---
+
+## 描述
+
+计算两个 byte 向量的 Hamming 距离，即按位 XOR 后不同 bit 的数量。 NULL 数组或 NULL 元素会报错。
+
+在包含此能力的 Doris 4.2 构建中可用。 始终执行精确标量计算，不自动改写为 ANN 检索。
+
+## 语法
+
+```sql
+HAMMING_DISTANCE(<array1>, <array2>)
+```
+
+## 参数
+
+| 参数 | 描述 |
+|---|---|
+| `<array1>` | 整数数组，允许 TINYINT、SMALLINT、INT、BIGINT，统一转换为 ARRAY<BIGINT>；每个元素必须在
`[0,255]`。不接受浮点、Decimal、LARGEINT 数组。 |
+| `<array2>` | 整数数组，允许 TINYINT、SMALLINT、INT、BIGINT，统一转换为 ARRAY<BIGINT>；每个元素必须在
`[0,255]`。不接受浮点、Decimal、LARGEINT 数组。 两个数组的长度必须相同。 |
+
+## 返回值
+
+返回 `FLOAT`，值越小越接近。空数组对返回 0；N 字节向量的最大距离是 8N。 长度不匹配、NULL 数组或 NULL 元素会报错，不返回
NULL。 越界元素也会报错。
+
+## 示例
+
+```sql
+SELECT HAMMING_DISTANCE([0,255,170], [255,0,85]) AS value;
+```
+
+```text
+value
+24
+```
+
+```sql
+SELECT HAMMING_DISTANCE([], []) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT HAMMING_DISTANCE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance cannot be null
+```
+
+```sql
+SELECT HAMMING_DISTANCE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance cannot have null
+```
+
+```sql
+SELECT HAMMING_DISTANCE([256], [0]);
+```
+
+```text
+ERROR: Hamming vector elements must be integers in [0, 255]
+```
diff --git
a/versioned_docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
b/versioned_docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
index 8273b82fb27d..eab05875414a 100644
---
a/versioned_docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
+++
b/versioned_docs/version-4.x/lakehouse/best-practices/lance-hybrid-search.mdx
@@ -2,7 +2,7 @@
{
"title": "Lance Hybrid Search Performance Best Practices",
"language": "en",
- "description": "Tune filtered vector and full-text search over Lance in
Apache Doris: align index coverage, size segments, budget shared caches, and
diagnose query profiles."
+ "description": "Use Lance vector and BM25 SQL pushdown in Apache Doris,
understand approximate semantics and filters, and tune index coverage,
segments, caches, and profiles."
}
---
@@ -12,6 +12,94 @@ Use this guide when scalar conditions participate in vector
or full-text retriev
Lance Catalog is experimental and supported starting from Apache Doris 4.2.
Configure access and check the reader/writer compatibility requirements in
[Lance Catalog](../catalogs/lance-catalog.mdx) first. Doris reads existing
Lance indexes; build and maintain them with compatible Lance tooling. The
latest Lance SDK or an upstream proposal does not guarantee support in the
reader bundled with your Doris build.
:::
+## Automatic Search from Ordinary SQL {#automatic-search}
+
+In Doris 4.2 builds that include automatic Lance search, eligible ordinary SQL
can use the same native search path as the explicit TVFs. This feature is
independent of calling the TVFs directly; do not assume an earlier build
supports it merely because `vector_search()` works. No separate
automatic-search session switch is required.
+
+### Function mapping
+
+| SQL expression | Required order | Lance metric and SQL result |
+|---|---|---|
+|
[l2_distance_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/l2-distance-approximate.md)
| `ASC` | `l2`; returns `CAST(sqrt(_distance) AS FLOAT)`, Euclidean distance
rather than native squared L2. |
+|
[inner_product_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/inner-product-approximate.md)
| `DESC` | `dot`; returns `1.0f - _distance`, an inner-product similarity. |
+|
[cosine_distance_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md)
| `ASC` | `cosine`; returns native cosine distance. |
+|
[cosine_similarity_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md)
| `DESC` | `cosine`; returns `1.0f - _distance`. |
+|
[hamming_distance_approximate](../../sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md)
| `ASC` | `hamming`; returns the number of differing bits. |
+| `score()` with `MATCH_ANY`, `MATCH_ALL`, or `MATCH_PHRASE` | `DESC` | Lance
BM25; Match OR, Match AND, or Phrase respectively. |
+
+Exact distance/similarity functions remain scalar, including
`cosine_distance()`, `cosine_similarity()`, and
[hamming_distance](../../sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md).
`l1_distance()` also remains scalar: the bundled Lance vector-search API does
not expose an L1 metric.
+
+### Vector and BM25 examples
+
+After configuring the Catalog, assume `lance_catalog.default.items` has `id`,
`category`, `content`, a four-dimensional Float32 fixed-size-list `embedding`,
and a three-byte UInt8 fixed-size-list `binary_embedding`. Build compatible
vector indexes and a committed FTS index on `content` with Lance tooling when
index acceleration is needed.
+
+```sql
+SELECT id, cosine_distance_approximate(embedding, [0.1,0.2,0.3,0.4]) AS
distance
+FROM lance_catalog.default.items
+WHERE category = 'book'
+ORDER BY distance ASC LIMIT 10 OFFSET 5;
+
+SELECT id, cosine_similarity_approximate(embedding, [0.1,0.2,0.3,0.4]) AS
similarity
+FROM lance_catalog.default.items
+ORDER BY similarity DESC LIMIT 10;
+
+SELECT id, hamming_distance_approximate(binary_embedding, [0,255,170]) AS
distance
+FROM lance_catalog.default.items
+ORDER BY distance ASC LIMIT 10;
+
+SELECT id, score() AS relevance
+FROM lance_catalog.default.items
+WHERE content MATCH_ALL 'storage engine' AND category = 'book'
+ORDER BY relevance DESC LIMIT 10;
+```
+
+The first query searches within `category = 'book'` before pruning candidates.
Each split requests 15 candidates with offset zero; Doris merges candidates and
applies the final `OFFSET 5 LIMIT 10`. The other queries return up to 10
neighbors or BM25 matches in their respective order. Index-based retrieval can
be approximate, and fewer than the requested number of rows can be returned.
Existing compatible indexes are reused; uncovered data uses the existing Flat
Search path. BM25 requires [...]
+
+### Eligibility and fallback
+
+- The query must have a direct Lance Catalog table scan, an optional filter, a
projection, and Top-N with one search ordering key and a positive `LIMIT`.
JOIN/EXISTS, secondary sort keys, DISTINCT, table sampling, and non-movable
projection expressions prevent this rewrite.
+- Floating metrics require physical Float32 fixed-size-list vectors; Hamming
requires physical UInt8 fixed-size-list vectors. Query vectors must be constant
arrays with matching dimensions. Float16/Float64, multi-vector columns, and
arbitrary element-changing casts are not automatically rewritten. UInt8 is
exposed as Doris SMALLINT, and widening it to the Hamming function's BIGINT
arguments is safe.
+- Vector queries with unsupported residual predicates, reversed search
ordering, missing native metadata, or rejected native vector/schema validation
retain scalar evaluation. `LIMIT + OFFSET` must fit the native UINT32 candidate
budget for rewriting; this limit does not restrict ordinary scalar SQL.
+- BM25 requires one top-level supported MATCH predicate on a direct string
column, a literal query, the index's stored analyzer, and descending `score()`.
Remaining scalar predicates must be fully pushable. `score() > literal` and
`score() >= literal` are supported as residual lower bounds; upper bounds and
other score predicates are rejected. Unsupported scored-query shapes report an
error rather than silently evaluating `score()` as a scalar.
+- Scores come from Lance's stored analyzer/index and snapshot-wide statistics.
They need not numerically match a separately indexed Doris internal table.
Fuzzy search, analyzer overrides, and multi-column `SEARCH()` expressions are
not enabled by this rewrite. Use explicit TVFs for supported multi-vector
queries and tuning such as `nprobes`, `refine_factor`, or `ef`.
+
+### Native approximate semantics
+
+The `_approximate` suffix opts an eligible Top-N query into native Lance
candidate semantics. Without rewriting, the functions execute scalar kernels.
Do not use approximate functions when exhaustive ranking or scalar validation
of every stored row is required.
+
+| Input | Scalar evaluation | Eligible native search |
+|---|---|---|
+| Stored NULL vector | Error | Excluded from candidates. |
+| Stored vector producing NaN distance | May return NaN | Excluded, so the
query may return fewer rows. |
+| NULL vector element | Error | Outside the supported native input domain;
ensure elements contain no NULLs. |
+| Stored zero-norm cosine vector | Distance 2, similarity 0 | Excluded when it
produces an undefined/NaN native distance. |
+| Zero/non-finite cosine query norm, including Float32 squared-norm
overflow/underflow | Scalar behavior | Automatic rewrite is skipped. |
+| Hamming input | Integer arrays, each element in `[0,255]` | Physical UInt8
vectors and a valid byte query. |
+
+Cosine native arithmetic/index estimates can differ from scalar results.
Hamming counts different bits, not unequal bytes:
`hamming_distance([0,255,170], [255,0,85])` returns 24. Hamming rejects
floating-point, decimal, and LARGEINT arrays before implicit casts, and rejects
out-of-range values before byte conversion. Exact functions remain available
for scalar execution.
+
+### WHERE prefilter and JOIN boundary
+
+Fully pushable predicates on the Lance table are evaluated against the same
pinned snapshot before search. Doris first attempts a row-ID-only scan and
shares the complete allowlist across search readers in the query. An empty list
selects no rows. At more than 65,536 IDs, Doris discards the partial list and
keeps the complete native predicate prefilter. Both temporary and cached list
capacity count toward query memory limits; stopped or failed collections are
not cached. This is separate [...]
+
+For this ACL example, assume `internal.auth.allowed_items` contains `item_id`
and `principal_id`.
+
+```sql
+SELECT d.id,
+ l2_distance_approximate(d.embedding, [0.1,0.2,0.3,0.4]) AS distance
+FROM lance_catalog.default.items d
+WHERE EXISTS (
+ SELECT 1 FROM internal.auth.allowed_items a
+ WHERE a.item_id = d.id AND a.principal_id = 42
+)
+ORDER BY distance ASC
+LIMIT 10;
+```
+
+This retains the join, scalar distance evaluation, and global Top-N. The
rewrite does not cross the ACL semi-join or map business IDs to native Lance
`_rowid`. Selecting an unfiltered Top-K before ACL filtering could miss the
nearest authorized rows. Adding a secondary ordering key would also prevent
automatic rewriting.
+
+Use `EXPLAIN` on the exact query to verify `externalSearchType=VECTOR` with
`lanceMetric=l2|dot|cosine|hamming`, or `externalSearchType=FULL_TEXT`.
`LanceRowIdPrefilterTime`, `LanceRowIdPrefilterRows`,
`LanceRowIdPrefilterCacheHits`, and `LanceRowIdPrefilterFallbacks` report Doris
allowlist work; they are distinct from the native row-ID loader metrics below.
Use explicit TVFs for search tuning or supported shapes outside this rule.
Rewritten searches can use the existing two-phase output [...]
+
## 1. Put Candidate Filters Inside the Search {#candidate-filters}
For a configured table containing an integer `id`, string `category`, string
`content`, and a four-dimensional vector `embedding`, use the TVF's `filter`
parameter for conditions that must affect candidate generation. The vector
index must match the dimension and metric; the text column must have a
committed FTS index.
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 b403731678ba..3a952fff3a95 100644
--- a/versioned_docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
+++ b/versioned_docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx
@@ -2,7 +2,7 @@
{
"title": "Lance Catalog",
"language": "en",
- "description": "Apache Doris Lance Catalog guide: access Lance datasets
through Filesystem or REST Namespace catalogs, with parallel reads, predicate
pushdown, S3/Local TVFs, index inspection, vector search, and full-text search."
+ "description": "Query Lance datasets with Apache Doris: configure
catalogs, use native vector and BM25 search, and understand automatic SQL
pushdown and type compatibility."
}
---
@@ -729,6 +729,8 @@ Lance file TVFs have the following additional limitations:
## Vector Search
+In builds with Doris 4.2 automatic Lance search, eligible ordinary SQL can
also use native vector Top-N and MATCH/BM25 retrieval. See [Automatic Search
from Ordinary SQL](../best-practices/lance-hybrid-search.mdx#automatic-search)
for the five approximate functions, metric conversion, input semantics, and
JOIN/EXISTS boundaries. The TVFs below remain the interface for explicit search
tuning and supported shapes outside automatic rewriting.
+
`vector_search()` is a relational TVF that performs Top-K search on a vector
column in a Lance table. It can use an existing Lance vector index or perform
Flat Search.
### Syntax and Example
@@ -1116,7 +1118,7 @@ This reduces storage I/O, network transfer, and memory
usage. The benefit is usu
Doris uses two-phase reading only when all of the following conditions are met:
-1. The query reads Lance through `vector_search()` or `full_text_search()` and
its plan contains a TopN eligible for lazy materialization. This switch does
not currently apply to ordinary Lance table scans or Lance file TVFs.
+1. The query reads Lance through `vector_search()` or `full_text_search()` and
its plan contains a TopN eligible for lazy materialization. An ordinary SQL
query rewritten to these search TVFs can also qualify; unreplaced scalar table
scans and Lance file TVFs do not.
2. The Boolean session variable `enable_lance_lazy_materialization` is `true`,
its default value.
3. At least one top-level column can be deferred. A column used only by the
final `SELECT` projection can be deferred. A column used by a Post-filter,
`ORDER BY`, or another expression before TopN must be read in Phase 1. Nested
subcolumns cannot currently be deferred.
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md
new file mode 100644
index 000000000000..f529df2129c5
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "COSINE_DISTANCE_APPROXIMATE",
+ "language": "en",
+ "description": "Calculates cosine distance between two vectors. NULL
arrays or NULL elements raise an error."
+}
+---
+
+## Description
+
+Calculates cosine distance between two vectors. NULL arrays or NULL elements
raise an error.
+
+Available in Doris 4.2 builds that include this function.Eligible Lance Top-N
queries can use native approximate retrieval; other queries execute scalar
kernels.
+
+## Syntax
+
+```sql
+COSINE_DISTANCE_APPROXIMATE(<array1>, <array2>)
+```
+
+## Parameters
+
+| Parameter | Description |
+|---|---|
+| `<array1>` | Numeric array, implicitly converted to ARRAY<FLOAT>; conversion
can affect precision. |
+| `<array2>` | Numeric array, implicitly converted to ARRAY<FLOAT>; conversion
can affect precision. The two arrays must have the same length. |
+
+## Return Value
+
+Returns FLOAT; smaller means closer. Scalar evaluation computes `1 - dot(x,y)
/ (norm(x) * norm(y))`. If either norm is zero, including two empty arrays, it
returns 2.Unequal lengths, NULL arrays, or NULL elements raise an error rather
than return NULL.Native candidate eligibility, numerical precision, and
NULL/NaN behavior can differ from scalar execution; see [automatic
search](../../../../lakehouse/best-practices/lance-hybrid-search.mdx#automatic-search).
+
+## Example
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE([1,0], [0,1]) AS value;
+```
+
+```text
+value
+1
+```
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE([0,0], [1,0]) AS value;
+```
+
+```text
+value
+2
+```
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_distance_approximate cannot be null
+```
+
+```sql
+SELECT COSINE_DISTANCE_APPROXIMATE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_distance_approximate cannot have null
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md
new file mode 100644
index 000000000000..01730e7bb55c
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate.md
@@ -0,0 +1,66 @@
+---
+{
+ "title": "COSINE_SIMILARITY_APPROXIMATE",
+ "language": "en",
+ "description": "Calculates cosine similarity between two vectors. NULL
arrays or NULL elements raise an error."
+}
+---
+
+## Description
+
+Calculates cosine similarity between two vectors. NULL arrays or NULL elements
raise an error.
+
+Available in Doris 4.2 builds that include this function.Eligible Lance Top-N
queries can use native approximate retrieval; other queries execute scalar
kernels.
+
+## Syntax
+
+```sql
+COSINE_SIMILARITY_APPROXIMATE(<array1>, <array2>)
+```
+
+## Parameters
+
+| Parameter | Description |
+|---|---|
+| `<array1>` | Numeric array, implicitly converted to ARRAY<FLOAT>; conversion
can affect precision. |
+| `<array2>` | Numeric array, implicitly converted to ARRAY<FLOAT>; conversion
can affect precision. The two arrays must have the same length. |
+
+## Return Value
+
+Returns FLOAT; larger means more similar. Scalar evaluation computes `dot(x,y)
/ (norm(x) * norm(y))`. If either norm is zero, including two empty arrays, it
returns 0.Unequal lengths, NULL arrays, or NULL elements raise an error rather
than return NULL.Native candidate eligibility, numerical precision, and
NULL/NaN behavior can differ from scalar execution; see [automatic
search](../../../../lakehouse/best-practices/lance-hybrid-search.mdx#automatic-search).
+
+## Example
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE([1,0], [0,1]) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE([0,0], [1,0]) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_similarity_approximate cannot be null
+```
+
+```sql
+SELECT COSINE_SIMILARITY_APPROXIMATE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function cosine_similarity_approximate cannot have
null
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md
new file mode 100644
index 000000000000..d3181c1b1df7
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate.md
@@ -0,0 +1,74 @@
+---
+{
+ "title": "HAMMING_DISTANCE_APPROXIMATE",
+ "language": "en",
+ "description": "Calculates Hamming distance between two byte vectors: the
number of differing bits after bitwise XOR. NULL arrays or NULL elements raise
an error."
+}
+---
+
+## Description
+
+Calculates Hamming distance between two byte vectors: the number of differing
bits after bitwise XOR. NULL arrays or NULL elements raise an error.
+
+Available in Doris 4.2 builds that include this function.Eligible Lance Top-N
queries can use native approximate retrieval; other queries execute scalar
kernels.
+
+## Syntax
+
+```sql
+HAMMING_DISTANCE_APPROXIMATE(<array1>, <array2>)
+```
+
+## Parameters
+
+| Parameter | Description |
+|---|---|
+| `<array1>` | Integer array of TINYINT, SMALLINT, INT, or BIGINT, coerced to
ARRAY<BIGINT>. Every element must be in `[0,255]`; floating-point, decimal, and
LARGEINT arrays are rejected. |
+| `<array2>` | Integer array of TINYINT, SMALLINT, INT, or BIGINT, coerced to
ARRAY<BIGINT>. Every element must be in `[0,255]`; floating-point, decimal, and
LARGEINT arrays are rejected. The two arrays must have the same length. |
+
+## Return Value
+
+Returns FLOAT; smaller means closer. Two empty arrays return 0; N-byte vectors
have a maximum distance of 8N.Unequal lengths, NULL arrays, or NULL elements
raise an error rather than return NULL.Out-of-range elements also raise an
error.Native candidate eligibility, numerical precision, and NULL/NaN behavior
can differ from scalar execution; see [automatic
search](../../../../lakehouse/best-practices/lance-hybrid-search.mdx#automatic-search).
+
+## Example
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([0,255,170], [255,0,85]) AS value;
+```
+
+```text
+value
+24
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([], []) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance_approximate cannot be null
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance_approximate cannot have
null
+```
+
+```sql
+SELECT HAMMING_DISTANCE_APPROXIMATE([256], [0]);
+```
+
+```text
+ERROR: Hamming vector elements must be integers in [0, 255]
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md
new file mode 100644
index 000000000000..76b1a70a12e2
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance.md
@@ -0,0 +1,74 @@
+---
+{
+ "title": "HAMMING_DISTANCE",
+ "language": "en",
+ "description": "Calculates Hamming distance between two byte vectors: the
number of differing bits after bitwise XOR. NULL arrays or NULL elements raise
an error."
+}
+---
+
+## Description
+
+Calculates Hamming distance between two byte vectors: the number of differing
bits after bitwise XOR. NULL arrays or NULL elements raise an error.
+
+Available in Doris 4.2 builds that include this function.Always uses exact
scalar evaluation; it is not automatically substituted with ANN search.
+
+## Syntax
+
+```sql
+HAMMING_DISTANCE(<array1>, <array2>)
+```
+
+## Parameters
+
+| Parameter | Description |
+|---|---|
+| `<array1>` | Integer array of TINYINT, SMALLINT, INT, or BIGINT, coerced to
ARRAY<BIGINT>. Every element must be in `[0,255]`; floating-point, decimal, and
LARGEINT arrays are rejected. |
+| `<array2>` | Integer array of TINYINT, SMALLINT, INT, or BIGINT, coerced to
ARRAY<BIGINT>. Every element must be in `[0,255]`; floating-point, decimal, and
LARGEINT arrays are rejected. The two arrays must have the same length. |
+
+## Return Value
+
+Returns FLOAT; smaller means closer. Two empty arrays return 0; N-byte vectors
have a maximum distance of 8N.Unequal lengths, NULL arrays, or NULL elements
raise an error rather than return NULL.Out-of-range elements also raise an
error.
+
+## Example
+
+```sql
+SELECT HAMMING_DISTANCE([0,255,170], [255,0,85]) AS value;
+```
+
+```text
+value
+24
+```
+
+```sql
+SELECT HAMMING_DISTANCE([], []) AS value;
+```
+
+```text
+value
+0
+```
+
+```sql
+SELECT HAMMING_DISTANCE(NULL, [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance cannot be null
+```
+
+```sql
+SELECT HAMMING_DISTANCE([0,NULL], [0,1]);
+```
+
+```text
+ERROR: First argument for function hamming_distance cannot have null
+```
+
+```sql
+SELECT HAMMING_DISTANCE([256], [0]);
+```
+
+```text
+ERROR: Hamming vector elements must be integers in [0, 255]
+```
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index 48497bb81ecb..7a81436940ce 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -1618,10 +1618,16 @@
"label": "Vector Distance Functions",
"items": [
"sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance",
+
"sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance-approximate",
"sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity",
+
"sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity-approximate",
+
"sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance",
+
"sql-manual/sql-functions/ai-functions/distance-functions/hamming-distance-approximate",
"sql-manual/sql-functions/ai-functions/distance-functions/inner-product",
+
"sql-manual/sql-functions/ai-functions/distance-functions/inner-product-approximate",
"sql-manual/sql-functions/ai-functions/distance-functions/l1-distance",
"sql-manual/sql-functions/ai-functions/distance-functions/l2-distance",
+
"sql-manual/sql-functions/ai-functions/distance-functions/l2-distance-approximate",
"sql-manual/sql-functions/ai-functions/distance-functions/embed"
]
},
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
