[docs](lance) Document automatic vector and BM25 SQL search

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 索引。
@@ -149,7 +237,7 @@
 4. **先构建，再发布。** 每次构建返回具有独立 UUID 的物理 Segment。收集成功结果，校验覆盖范围和兼容性，再分别提交每个逻辑索引。不同列或 Worker 输出不要共用一个物理 UUID。示例假设使用新的逻辑索引名，替换、重试和失败清理需要额外的协调策略。
 5. **验证最终 Manifest。** 对每个索引，将实际 Segment 到 Fragment 的覆盖关系与规划分组比较，检查遗漏和重叠。只比较 Segment 数量不够，应使用 Lance 索引元数据。Doris 对 Filesystem Catalog 表的 `SHOW INDEX` 有助于检查逻辑索引名、类型和字段，但不能代替覆盖关系检查。
 
 共享分组方案不要求把所有 Worker 输出合并为一个 Segment，否则会丢失刻意保留的边界。构建、提交 API 和支持的合并流程参见 [Lance 分布式索引指南](https://lance.org/guide/distributed_indexing/)。
 
 ### 在维护中保持对齐
 
@@ -160,7 +248,7 @@
 
 ### 逻辑索引与上游规划
 
 Lance 的[索引格式](https://lance.org/format/index/)定义逻辑索引和物理 Segment，[分布式索引跟踪 Issue](https://github.com/lance-format/lance/issues/6309) 跟踪各索引类型共享的 Segment 生命周期。该模型**不要求不同列拥有相同 Fragment 边界**。跨列分组和维护仍由编排方负责，不能把上游路线图理解成 Doris 已经提供自动对齐功能。
 
 ## 5. 同时调优过滤和内存 {#workload-tuning}
 

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/lance-catalog.mdx

@@ -1,8 +1,8 @@
 ---
 {
     "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 @@
 
 ## 向量检索
 
+包含 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。
 
 ### 语法和示例
@@ -879,7 +881,7 @@
 
 #### 准备数据并执行查询
 
 使用上文的 AWS S3 Filesystem Catalog 示例，Catalog 名称为 `lance_fs_s3`，warehouse 为 `s3://my-bucket/lance`。在写入环境中安装 Lance Python SDK（`pylance`）和 `pyarrow`，配置 S3 凭证和 region，例如设置 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_DEFAULT_REGION`。写入端需要写权限，Doris 需要同一位置的读权限。使用自定义 endpoint 或其他认证方式时，按 Catalog 配置对应的 SDK [对象存储选项](https://lance.org/guide/object_store/)。
 
 将 `documents.lance` 直接写在 warehouse 下，Doris 会将其发现为 `lance_fs_s3.default.documents`。请同时替换 Catalog 和 Python 示例中的 bucket，并使用尚不存在的数据集路径：
 
@@ -1012,7 +1014,7 @@
 
 ## FE 表访问缓存
 
 该配置要求 Doris 构建版本包含[表访问缓存变更](https://github.com/apache/doris/pull/68305)。
 
 每个 FE 可以在 Catalog 内缓存表解析后的 Dataset URI 和访问配置，避免查询规划时重复执行文件系统发现或 REST `describeTable` 请求。每个 Catalog 客户端最多保留 10,000 个条目。`lance.table_access_cache_ttl_seconds` 默认为 `60` 秒，命中缓存不会延长有效期。此缓存不保存 Dataset 版本：每次读取仍会打开 Dataset 并选择快照。
 
@@ -1116,7 +1118,7 @@
 
 满足以下条件时，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 前表达式使用的列必须在第一阶段读取。嵌套子列当前不能延迟读取。
 

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
+```

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
+```

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]
+```