This is an automated email from the ASF dual-hosted git repository.
zhangstar333 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 48a6f2ffba1 [doc](lance) update the lance format doc (#4047)
48a6f2ffba1 is described below
commit 48a6f2ffba129f60dae1924fb866681aaba248ab
Author: zhangstar333 <[email protected]>
AuthorDate: Fri Aug 7 19:04:07 2026 +0800
[doc](lance) update the lance format doc (#4047)
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [ ] Chinese
- [ ] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
- [ ] Updated required version and language counterparts, or explained
why not
- [ ] If only one language changed, confirmed whether source/translation
counterparts need sync
---
docs/lakehouse/file-analysis.md | 2 +-
docs/lakehouse/file-formats/lance.md | 99 ++++++++--------------
.../current/lakehouse/file-analysis.md | 2 +-
.../current/lakehouse/file-formats/lance.md | 99 ++++++++--------------
.../version-4.x/lakehouse/file-analysis.md | 2 +-
.../version-4.x/lakehouse/file-formats/lance.md | 99 ++++++++--------------
.../version-4.x/lakehouse/file-analysis.md | 2 +-
.../version-4.x/lakehouse/file-formats/lance.md | 99 ++++++++--------------
8 files changed, 140 insertions(+), 264 deletions(-)
diff --git a/docs/lakehouse/file-analysis.md b/docs/lakehouse/file-analysis.md
index 82169c0053e..2c277f9eaa8 100644
--- a/docs/lakehouse/file-analysis.md
+++ b/docs/lakehouse/file-analysis.md
@@ -26,7 +26,7 @@ TVF supports reading and analyzing the following file
formats. Click the links f
- [Parquet](./file-formats/parquet.md)
- [ORC](./file-formats/orc.md)
- [Text / CSV / JSON](./file-formats/text.md)
-- [Lance](./file-formats/lance.md) (experimental, since version 5.0.0)
+- [Lance](./file-formats/lance.md) (supported since version 4.2)
## Use Cases
diff --git a/docs/lakehouse/file-formats/lance.md
b/docs/lakehouse/file-formats/lance.md
index 5fed5d04a89..a906718ad1b 100644
--- a/docs/lakehouse/file-formats/lance.md
+++ b/docs/lakehouse/file-formats/lance.md
@@ -2,97 +2,66 @@
{
"title": "Lance | File Formats",
"language": "en",
- "description": "This document introduces the support for reading Lance
file formats in Doris.",
+ "description": "This document introduces Apache Doris support for reading
the Lance file format.",
"sidebar_label": "Lance"
}
---
# Lance
-:::tip
-Lance format support is an **experimental feature** available since Apache
Doris **5.0.0**.
+:::note
+Lance support is available starting from Apache Doris 4.2.
:::
-[Lance](https://docs.lancedb.com/lance) is a modern columnar data format
designed for AI/ML workloads, with native support for vector search, multimodal
data (images, embeddings), and fast random access.
-
-Doris supports reading Lance format files through Table Valued Functions (TVF).
+[Lance](https://docs.lancedb.com/lance) is a columnar data format designed for
analytics and AI workloads. Doris can read Lance datasets through a Lance
Catalog or through the `s3()` and `local()` table-valued functions (TVFs).
## Supported Features
| Feature | Support |
-|---------|---------|
-| Reading data via Table Valued Function (`s3`, `local`) | Yes |
-| Automatic schema inference | Yes |
-| Column projection | Yes |
-| `WHERE` filter, `LIMIT`, `COUNT(*)`, aggregation | Yes |
-| Multi-fragment datasets | Yes |
-| Reading from Catalog | Not supported |
-| Writing data (Outfile/Export/INSERT INTO TVF) | Not supported |
-| Vector ANN search / Full-text search pushdown | Not supported |
-| Doris Data Cache integration | Not supported |
-
-## Dataset Layout
+|---|---|
+| Lance Catalog | Supports Filesystem Catalog and REST Catalog |
+| File TVFs | Supports `s3()` and `local()` |
+| Schema inference and column pruning | Supported |
+| Parallel Fragment scans | Supported by Catalog queries and S3 TVFs |
+| Predicate pushdown | Supports compatible scalar predicates |
+| Vector search | Supports Lance vector indexes and Flat Search through
`vector_search()` |
+| Writing to Lance | Not supported |
+| Time Travel | Not supported |
+| Full-Text Search / Hybrid Search | Not supported |
-A Lance dataset is a **directory** with the following typical structure:
+For Catalog configuration, type mapping, predicate pushdown, and vector search
details, see [Lance Catalog](../catalogs/lance-catalog.mdx).
-```
-my_dataset.lance/
-├── _transactions/
-├── _versions/
-└── data/
- ├── fragment-0.lance
- ├── fragment-1.lance
- └── ...
-```
+## Query a Lance Dataset with a File TVF
-When querying via TVF, the `uri` / `file_path` should match one or more
`.lance` data files inside the `data/` subdirectory of the dataset. Each scan
range reads exactly one fragment, and Doris automatically resolves the dataset
root from the matched path. To read an entire multi-fragment dataset, use a
glob such as `data/*.lance` so that every fragment file is assigned to its own
scan range. In practice, real Lance datasets use UUID-named fragment files, so
globbing is the natural way t [...]
+The `uri` or `file_path` must point directly to the **root directory of one
Lance dataset**, rather than an internal file such as `data/*.lance`.
-## Usage Examples
-
-### Read from S3
+The following example reads a Lance dataset from S3-compatible object storage:
```sql
-SELECT * FROM s3(
- "uri" = "s3://bucket/path/to/my_dataset.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
+SELECT user_id, name
+FROM s3(
+ "uri" = "s3://my-bucket/lance/user_profiles.lance",
+ "s3.endpoint" = "http://127.0.0.1:9000";,
+ "s3.access_key" = "admin",
+ "s3.secret_key" = "password",
"s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-) ORDER BY id LIMIT 10;
-```
-
-### Read from Local Disk
-
-```sql
--- Get backend_id via: SHOW BACKENDS;
-SELECT * FROM local(
- "file_path" = "data/my_dataset.lance/data/*.lance",
- "backend_id" = "<backend_id>",
+ "use_path_style" = "true",
"format" = "lance"
-) ORDER BY id LIMIT 10;
+)
+WHERE user_id > 100;
```
-### Aggregation over a Multi-Fragment Dataset
-
-```sql
-SELECT count(*), min(id), max(id) FROM s3(
- "uri" = "s3://bucket/path/to/large.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
- "s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-);
-```
+To read a local dataset, use `local()` and specify the dataset root with
`file_path` and the target BE with `backend_id`. Doris passes `file_path`
directly to the Lance Reader and does not prepend `user_files_secure_path` or
expand the path as a Glob. An absolute path is recommended.
## Limitations
-- **TVF only**: Only the `s3` and `local` TVFs are supported. `CREATE CATALOG`
is not supported yet.
-- **No data cache**: Lance reads bypass Doris's `BlockFileCache`; S3 reads are
not cached on the local disk.
-- **No predicate / vector pushdown**: `WHERE` filters, vector search, and
full-text search are not pushed down to the Lance reader.
-- **Read-only**: Writing Lance files via `OUTFILE`, `EXPORT`, or `INSERT INTO`
TVF is not supported.
+- Lance access is read-only. Creating, writing, updating, or deleting Lance
tables is not supported.
+- Only `s3()` and `local()` support the Lance format. Other file TVFs, such as
HDFS and HTTP, are not supported.
+- One TVF path can represent only one Lance dataset, and `path_partition_keys`
is not supported.
+- Queries read the current dataset version. SQL cannot select a Version or
perform Time Travel.
+- Local TVF Schema discovery and execution open the latest dataset version
independently. Avoid modifying the dataset while a Local TVF query is being
analyzed and executed.
## References
+- [Lance Catalog](../catalogs/lance-catalog.mdx)
- [Lance Format Documentation](https://docs.lancedb.com/lance)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-analysis.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-analysis.md
index 6f59bb03211..2a5970a078d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-analysis.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-analysis.md
@@ -26,7 +26,7 @@ TVF 支持读取和分析以下文件格式，点击链接可查看对应格式
- [Parquet](./file-formats/parquet.md)
- [ORC](./file-formats/orc.md)
- [Text / CSV / JSON](./file-formats/text.md)
-- [Lance](./file-formats/lance.md)（实验性功能，自 5.0.0 版本起支持）
+- [Lance](./file-formats/lance.md)（自 4.2 版本起支持）
## 使用场景
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-formats/lance.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-formats/lance.md
index 554a8b88448..7bac698894f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-formats/lance.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/file-formats/lance.md
@@ -2,97 +2,66 @@
{
"title": "Lance | File Formats",
"language": "zh-CN",
- "description": "本文档用于介绍 Doris 的 Lance 文件格式的读取支持情况。",
+ "description": "本文档介绍 Apache Doris 对 Lance 文件格式的读取支持。",
"sidebar_label": "Lance"
}
---
# Lance
-:::tip
-Lance 格式支持为 **实验性功能**，自 Apache Doris **5.0.0** 版本起提供。
+:::note
+Lance 支持自 Apache Doris 4.2 版本开始提供。
:::
-[Lance](https://docs.lancedb.com/lance) 是一种面向 AI/ML
场景设计的现代列式数据格式，原生支持向量检索、多模态数据（图像、Embedding）以及高效的随机访问。
-
-Doris 通过 Table Valued Function（TVF）支持读取 Lance 格式文件。
+[Lance](https://docs.lancedb.com/lance) 是面向分析和 AI 场景的列式数据格式。Doris 可以通过 Lance
Catalog，或通过 `s3()` 和 `local()` 表值函数（TVF）读取 Lance 数据集。
## 支持的功能
| 功能 | 支持情况 |
-|------|----------|
-| 通过 Table Valued Function（`s3`、`local`）读取数据 | 支持 |
-| 自动 Schema 推断 | 支持 |
-| 列裁剪 | 支持 |
-| `WHERE` 过滤、`LIMIT`、`COUNT(*)`、聚合 | 支持 |
-| 多 Fragment 数据集 | 支持 |
-| Catalog 读取 | 暂不支持 |
-| 数据写入（Outfile / Export / INSERT INTO TVF） | 暂不支持 |
-| 向量 ANN 检索 / 全文检索下推 | 暂不支持 |
-| Doris Data Cache 集成 | 暂不支持 |
-
-## 数据集结构
+|---|---|
+| Lance Catalog | 支持 Filesystem Catalog 和 REST Catalog |
+| 文件 TVF | 支持 `s3()` 和 `local()` |
+| Schema 推断和列裁剪 | 支持 |
+| 并行扫描 Fragment | Catalog 查询和 S3 TVF 支持 |
+| 谓词下推 | 支持兼容的标量谓词 |
+| 向量检索 | 支持通过 `vector_search()` 使用 Lance 向量索引或执行 Flat Search |
+| 写入 Lance | 暂不支持 |
+| Time Travel | 暂不支持 |
+| Full-Text Search / Hybrid Search | 暂不支持 |
-Lance 数据集是一个**目录**，典型结构如下：
+Catalog 配置、类型映射、谓词下推和向量检索的详细说明请参见 [Lance
Catalog](../catalogs/lance-catalog.mdx)。
-```
-my_dataset.lance/
-├── _transactions/
-├── _versions/
-└── data/
- ├── fragment-0.lance
- ├── fragment-1.lance
- └── ...
-```
+## 通过文件 TVF 查询 Lance 数据集
-通过 TVF 查询时，`uri` / `file_path` 应当匹配数据集目录下 `data/` 子目录中的一个或多个 `.lance` 数据文件。每个
Scan Range 会精确读取一个 Fragment，Doris 会自动从匹配到的路径中解析出数据集根目录。若要读取整个多 Fragment
数据集，请使用类似 `data/*.lance` 的通配符，使每个 Fragment 文件都被分配到独立的 Scan Range 上。由于真实 Lance
数据集的 Fragment 文件通常以 UUID 命名，使用通配符也是最自然的引用方式。
+`uri` 或 `file_path` 必须直接指向**单个 Lance 数据集的根目录**，不能指向 `data/*.lance` 等内部数据文件。
-## 使用示例
-
-### 从 S3 读取
+下面的示例从 S3 兼容对象存储读取 Lance 数据集：
```sql
-SELECT * FROM s3(
- "uri" = "s3://bucket/path/to/my_dataset.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
+SELECT user_id, name
+FROM s3(
+ "uri" = "s3://my-bucket/lance/user_profiles.lance",
+ "s3.endpoint" = "http://127.0.0.1:9000";,
+ "s3.access_key" = "admin",
+ "s3.secret_key" = "password",
"s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-) ORDER BY id LIMIT 10;
-```
-
-### 从本地磁盘读取
-
-```sql
--- 可通过 SHOW BACKENDS; 获取 backend_id
-SELECT * FROM local(
- "file_path" = "data/my_dataset.lance/data/*.lance",
- "backend_id" = "<backend_id>",
+ "use_path_style" = "true",
"format" = "lance"
-) ORDER BY id LIMIT 10;
+)
+WHERE user_id > 100;
```
-### 多 Fragment 数据集上的聚合查询
-
-```sql
-SELECT count(*), min(id), max(id) FROM s3(
- "uri" = "s3://bucket/path/to/large.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
- "s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-);
-```
+读取本地数据集时，使用 `local()`，通过 `file_path` 指定数据集根目录，并通过 `backend_id` 指定目标 BE。Doris
会将 `file_path` 直接传给 Lance Reader，不会自动拼接 `user_files_secure_path`，也不会对路径执行 Glob
展开；建议使用绝对路径。
## 使用限制
-- **仅支持 TVF 方式**：当前仅支持通过 `s3` 和 `local` TVF 读取，尚不支持 `CREATE CATALOG`。
-- **不支持 Data Cache**：Lance 读取不会经过 Doris `BlockFileCache`，S3 数据不会缓存到本地磁盘。
-- **不支持谓词 / 向量下推**：`WHERE` 过滤、向量检索、全文检索等条件不会下推到 Lance Reader。
-- **只读**：暂不支持通过 `OUTFILE`、`EXPORT` 或 `INSERT INTO` TVF 写入 Lance 文件。
+- Lance 当前仅支持读取，不支持创建、写入、更新或删除 Lance 表。
+- Lance 格式仅支持 `s3()` 和 `local()`，暂不支持 HDFS、HTTP 等其他文件 TVF。
+- 一个 TVF 路径只能表示一个 Lance 数据集，且不支持 `path_partition_keys`。
+- 查询读取数据集的当前版本，不支持通过 SQL 指定 Version 或执行 Time Travel。
+- Local TVF 的 Schema 发现和执行会分别打开数据集的最新版本，应避免在查询分析和执行期间修改数据集。
## 参考资料
+- [Lance Catalog](../catalogs/lance-catalog.mdx)
- [Lance 格式官方文档](https://docs.lancedb.com/lance)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-analysis.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-analysis.md
index 6f59bb03211..2a5970a078d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-analysis.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-analysis.md
@@ -26,7 +26,7 @@ TVF 支持读取和分析以下文件格式，点击链接可查看对应格式
- [Parquet](./file-formats/parquet.md)
- [ORC](./file-formats/orc.md)
- [Text / CSV / JSON](./file-formats/text.md)
-- [Lance](./file-formats/lance.md)（实验性功能，自 5.0.0 版本起支持）
+- [Lance](./file-formats/lance.md)（自 4.2 版本起支持）
## 使用场景
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-formats/lance.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-formats/lance.md
index 554a8b88448..7bac698894f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-formats/lance.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/file-formats/lance.md
@@ -2,97 +2,66 @@
{
"title": "Lance | File Formats",
"language": "zh-CN",
- "description": "本文档用于介绍 Doris 的 Lance 文件格式的读取支持情况。",
+ "description": "本文档介绍 Apache Doris 对 Lance 文件格式的读取支持。",
"sidebar_label": "Lance"
}
---
# Lance
-:::tip
-Lance 格式支持为 **实验性功能**，自 Apache Doris **5.0.0** 版本起提供。
+:::note
+Lance 支持自 Apache Doris 4.2 版本开始提供。
:::
-[Lance](https://docs.lancedb.com/lance) 是一种面向 AI/ML
场景设计的现代列式数据格式，原生支持向量检索、多模态数据（图像、Embedding）以及高效的随机访问。
-
-Doris 通过 Table Valued Function（TVF）支持读取 Lance 格式文件。
+[Lance](https://docs.lancedb.com/lance) 是面向分析和 AI 场景的列式数据格式。Doris 可以通过 Lance
Catalog，或通过 `s3()` 和 `local()` 表值函数（TVF）读取 Lance 数据集。
## 支持的功能
| 功能 | 支持情况 |
-|------|----------|
-| 通过 Table Valued Function（`s3`、`local`）读取数据 | 支持 |
-| 自动 Schema 推断 | 支持 |
-| 列裁剪 | 支持 |
-| `WHERE` 过滤、`LIMIT`、`COUNT(*)`、聚合 | 支持 |
-| 多 Fragment 数据集 | 支持 |
-| Catalog 读取 | 暂不支持 |
-| 数据写入（Outfile / Export / INSERT INTO TVF） | 暂不支持 |
-| 向量 ANN 检索 / 全文检索下推 | 暂不支持 |
-| Doris Data Cache 集成 | 暂不支持 |
-
-## 数据集结构
+|---|---|
+| Lance Catalog | 支持 Filesystem Catalog 和 REST Catalog |
+| 文件 TVF | 支持 `s3()` 和 `local()` |
+| Schema 推断和列裁剪 | 支持 |
+| 并行扫描 Fragment | Catalog 查询和 S3 TVF 支持 |
+| 谓词下推 | 支持兼容的标量谓词 |
+| 向量检索 | 支持通过 `vector_search()` 使用 Lance 向量索引或执行 Flat Search |
+| 写入 Lance | 暂不支持 |
+| Time Travel | 暂不支持 |
+| Full-Text Search / Hybrid Search | 暂不支持 |
-Lance 数据集是一个**目录**，典型结构如下：
+Catalog 配置、类型映射、谓词下推和向量检索的详细说明请参见 [Lance
Catalog](../catalogs/lance-catalog.mdx)。
-```
-my_dataset.lance/
-├── _transactions/
-├── _versions/
-└── data/
- ├── fragment-0.lance
- ├── fragment-1.lance
- └── ...
-```
+## 通过文件 TVF 查询 Lance 数据集
-通过 TVF 查询时，`uri` / `file_path` 应当匹配数据集目录下 `data/` 子目录中的一个或多个 `.lance` 数据文件。每个
Scan Range 会精确读取一个 Fragment，Doris 会自动从匹配到的路径中解析出数据集根目录。若要读取整个多 Fragment
数据集，请使用类似 `data/*.lance` 的通配符，使每个 Fragment 文件都被分配到独立的 Scan Range 上。由于真实 Lance
数据集的 Fragment 文件通常以 UUID 命名，使用通配符也是最自然的引用方式。
+`uri` 或 `file_path` 必须直接指向**单个 Lance 数据集的根目录**，不能指向 `data/*.lance` 等内部数据文件。
-## 使用示例
-
-### 从 S3 读取
+下面的示例从 S3 兼容对象存储读取 Lance 数据集：
```sql
-SELECT * FROM s3(
- "uri" = "s3://bucket/path/to/my_dataset.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
+SELECT user_id, name
+FROM s3(
+ "uri" = "s3://my-bucket/lance/user_profiles.lance",
+ "s3.endpoint" = "http://127.0.0.1:9000";,
+ "s3.access_key" = "admin",
+ "s3.secret_key" = "password",
"s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-) ORDER BY id LIMIT 10;
-```
-
-### 从本地磁盘读取
-
-```sql
--- 可通过 SHOW BACKENDS; 获取 backend_id
-SELECT * FROM local(
- "file_path" = "data/my_dataset.lance/data/*.lance",
- "backend_id" = "<backend_id>",
+ "use_path_style" = "true",
"format" = "lance"
-) ORDER BY id LIMIT 10;
+)
+WHERE user_id > 100;
```
-### 多 Fragment 数据集上的聚合查询
-
-```sql
-SELECT count(*), min(id), max(id) FROM s3(
- "uri" = "s3://bucket/path/to/large.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
- "s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-);
-```
+读取本地数据集时，使用 `local()`，通过 `file_path` 指定数据集根目录，并通过 `backend_id` 指定目标 BE。Doris
会将 `file_path` 直接传给 Lance Reader，不会自动拼接 `user_files_secure_path`，也不会对路径执行 Glob
展开；建议使用绝对路径。
## 使用限制
-- **仅支持 TVF 方式**：当前仅支持通过 `s3` 和 `local` TVF 读取，尚不支持 `CREATE CATALOG`。
-- **不支持 Data Cache**：Lance 读取不会经过 Doris `BlockFileCache`，S3 数据不会缓存到本地磁盘。
-- **不支持谓词 / 向量下推**：`WHERE` 过滤、向量检索、全文检索等条件不会下推到 Lance Reader。
-- **只读**：暂不支持通过 `OUTFILE`、`EXPORT` 或 `INSERT INTO` TVF 写入 Lance 文件。
+- Lance 当前仅支持读取，不支持创建、写入、更新或删除 Lance 表。
+- Lance 格式仅支持 `s3()` 和 `local()`，暂不支持 HDFS、HTTP 等其他文件 TVF。
+- 一个 TVF 路径只能表示一个 Lance 数据集，且不支持 `path_partition_keys`。
+- 查询读取数据集的当前版本，不支持通过 SQL 指定 Version 或执行 Time Travel。
+- Local TVF 的 Schema 发现和执行会分别打开数据集的最新版本，应避免在查询分析和执行期间修改数据集。
## 参考资料
+- [Lance Catalog](../catalogs/lance-catalog.mdx)
- [Lance 格式官方文档](https://docs.lancedb.com/lance)
diff --git a/versioned_docs/version-4.x/lakehouse/file-analysis.md
b/versioned_docs/version-4.x/lakehouse/file-analysis.md
index 82169c0053e..2c277f9eaa8 100644
--- a/versioned_docs/version-4.x/lakehouse/file-analysis.md
+++ b/versioned_docs/version-4.x/lakehouse/file-analysis.md
@@ -26,7 +26,7 @@ TVF supports reading and analyzing the following file
formats. Click the links f
- [Parquet](./file-formats/parquet.md)
- [ORC](./file-formats/orc.md)
- [Text / CSV / JSON](./file-formats/text.md)
-- [Lance](./file-formats/lance.md) (experimental, since version 5.0.0)
+- [Lance](./file-formats/lance.md) (supported since version 4.2)
## Use Cases
diff --git a/versioned_docs/version-4.x/lakehouse/file-formats/lance.md
b/versioned_docs/version-4.x/lakehouse/file-formats/lance.md
index 5fed5d04a89..a906718ad1b 100644
--- a/versioned_docs/version-4.x/lakehouse/file-formats/lance.md
+++ b/versioned_docs/version-4.x/lakehouse/file-formats/lance.md
@@ -2,97 +2,66 @@
{
"title": "Lance | File Formats",
"language": "en",
- "description": "This document introduces the support for reading Lance
file formats in Doris.",
+ "description": "This document introduces Apache Doris support for reading
the Lance file format.",
"sidebar_label": "Lance"
}
---
# Lance
-:::tip
-Lance format support is an **experimental feature** available since Apache
Doris **5.0.0**.
+:::note
+Lance support is available starting from Apache Doris 4.2.
:::
-[Lance](https://docs.lancedb.com/lance) is a modern columnar data format
designed for AI/ML workloads, with native support for vector search, multimodal
data (images, embeddings), and fast random access.
-
-Doris supports reading Lance format files through Table Valued Functions (TVF).
+[Lance](https://docs.lancedb.com/lance) is a columnar data format designed for
analytics and AI workloads. Doris can read Lance datasets through a Lance
Catalog or through the `s3()` and `local()` table-valued functions (TVFs).
## Supported Features
| Feature | Support |
-|---------|---------|
-| Reading data via Table Valued Function (`s3`, `local`) | Yes |
-| Automatic schema inference | Yes |
-| Column projection | Yes |
-| `WHERE` filter, `LIMIT`, `COUNT(*)`, aggregation | Yes |
-| Multi-fragment datasets | Yes |
-| Reading from Catalog | Not supported |
-| Writing data (Outfile/Export/INSERT INTO TVF) | Not supported |
-| Vector ANN search / Full-text search pushdown | Not supported |
-| Doris Data Cache integration | Not supported |
-
-## Dataset Layout
+|---|---|
+| Lance Catalog | Supports Filesystem Catalog and REST Catalog |
+| File TVFs | Supports `s3()` and `local()` |
+| Schema inference and column pruning | Supported |
+| Parallel Fragment scans | Supported by Catalog queries and S3 TVFs |
+| Predicate pushdown | Supports compatible scalar predicates |
+| Vector search | Supports Lance vector indexes and Flat Search through
`vector_search()` |
+| Writing to Lance | Not supported |
+| Time Travel | Not supported |
+| Full-Text Search / Hybrid Search | Not supported |
-A Lance dataset is a **directory** with the following typical structure:
+For Catalog configuration, type mapping, predicate pushdown, and vector search
details, see [Lance Catalog](../catalogs/lance-catalog.mdx).
-```
-my_dataset.lance/
-├── _transactions/
-├── _versions/
-└── data/
- ├── fragment-0.lance
- ├── fragment-1.lance
- └── ...
-```
+## Query a Lance Dataset with a File TVF
-When querying via TVF, the `uri` / `file_path` should match one or more
`.lance` data files inside the `data/` subdirectory of the dataset. Each scan
range reads exactly one fragment, and Doris automatically resolves the dataset
root from the matched path. To read an entire multi-fragment dataset, use a
glob such as `data/*.lance` so that every fragment file is assigned to its own
scan range. In practice, real Lance datasets use UUID-named fragment files, so
globbing is the natural way t [...]
+The `uri` or `file_path` must point directly to the **root directory of one
Lance dataset**, rather than an internal file such as `data/*.lance`.
-## Usage Examples
-
-### Read from S3
+The following example reads a Lance dataset from S3-compatible object storage:
```sql
-SELECT * FROM s3(
- "uri" = "s3://bucket/path/to/my_dataset.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
+SELECT user_id, name
+FROM s3(
+ "uri" = "s3://my-bucket/lance/user_profiles.lance",
+ "s3.endpoint" = "http://127.0.0.1:9000";,
+ "s3.access_key" = "admin",
+ "s3.secret_key" = "password",
"s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-) ORDER BY id LIMIT 10;
-```
-
-### Read from Local Disk
-
-```sql
--- Get backend_id via: SHOW BACKENDS;
-SELECT * FROM local(
- "file_path" = "data/my_dataset.lance/data/*.lance",
- "backend_id" = "<backend_id>",
+ "use_path_style" = "true",
"format" = "lance"
-) ORDER BY id LIMIT 10;
+)
+WHERE user_id > 100;
```
-### Aggregation over a Multi-Fragment Dataset
-
-```sql
-SELECT count(*), min(id), max(id) FROM s3(
- "uri" = "s3://bucket/path/to/large.lance/data/*.lance",
- "format" = "lance",
- "s3.access_key" = "ak",
- "s3.secret_key" = "sk",
- "s3.region" = "us-east-1",
- "s3.endpoint" = "https://s3.us-east-1.amazonaws.com";
-);
-```
+To read a local dataset, use `local()` and specify the dataset root with
`file_path` and the target BE with `backend_id`. Doris passes `file_path`
directly to the Lance Reader and does not prepend `user_files_secure_path` or
expand the path as a Glob. An absolute path is recommended.
## Limitations
-- **TVF only**: Only the `s3` and `local` TVFs are supported. `CREATE CATALOG`
is not supported yet.
-- **No data cache**: Lance reads bypass Doris's `BlockFileCache`; S3 reads are
not cached on the local disk.
-- **No predicate / vector pushdown**: `WHERE` filters, vector search, and
full-text search are not pushed down to the Lance reader.
-- **Read-only**: Writing Lance files via `OUTFILE`, `EXPORT`, or `INSERT INTO`
TVF is not supported.
+- Lance access is read-only. Creating, writing, updating, or deleting Lance
tables is not supported.
+- Only `s3()` and `local()` support the Lance format. Other file TVFs, such as
HDFS and HTTP, are not supported.
+- One TVF path can represent only one Lance dataset, and `path_partition_keys`
is not supported.
+- Queries read the current dataset version. SQL cannot select a Version or
perform Time Travel.
+- Local TVF Schema discovery and execution open the latest dataset version
independently. Avoid modifying the dataset while a Local TVF query is being
analyzed and executed.
## References
+- [Lance Catalog](../catalogs/lance-catalog.mdx)
- [Lance Format Documentation](https://docs.lancedb.com/lance)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
