You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@doris.apache.org by yi...@apache.org on 2026/10/10 02:49:38 UTC

(doris) 11/28: [feature](lance) Search historical versions, tags and branches with vector_search and full_text_search (#68707)

This is an automated email from the ASF dual-hosted git repository.

yiguolei pushed a commit to branch branch-4.2
in repository https://gitbox.apache.org/repos/asf/doris.git

commit c552df550f44c6e4ecb6200895a9e209ab9b8d6d
Author: zy-kkk <zh...@gmail.com>
AuthorDate: Fri Oct 9 14:36:26 2026 +0800

    [feature](lance) Search historical versions, tags and branches with vector_search and full_text_search (#68707)
    
    ### What problem does this PR solve?
    
    Issue Number: close #68625
    
    Related PR: #68453 (time travel, tags, branches and managed versioning
    for Lance table scans)
    
    Problem Summary:
    
    `vector_search()` and `full_text_search()` always searched the latest
    version of `main`, and their `table` argument rejected `FOR VERSION AS
    OF`, `@tag` and `@branch`. A search could not be reproduced against a
    released tag, compared across versions, or run on an experimental
    branch.
    
    Both TVFs now take four optional properties, with the semantics of the
    table syntax from #68453:
    
    | Property | Value | Table syntax | Combines with |
    |-|-|-|-|
    | `version` | positive integer | `FOR VERSION AS OF N` | `branch` |
    | `timestamp` | `yyyy-MM-dd HH:mm:ss[.SSS]`, session time zone | `FOR
    TIME AS OF` | `branch` |
    | `tag` | tag name | `@tag(name)` | none |
    | `branch` | branch name, `main` is the main chain | `@branch(name)` |
    `version` or `timestamp` |
    
    ```sql
    SELECT id, _distance FROM vector_search(
        "table" = "lance_catalog.db.documents", "column" = "embedding",
        "query_vector" = "[0.1, 0.2, 0.3]", "version" = "3")
    ORDER BY _distance;
    
    SELECT id, _score FROM full_text_search(
        "table" = "lance_catalog.db.documents", "column" = "content", "query" = "database",
        "branch" = "dev", "timestamp" = "2026-09-20 12:00:00")
    ORDER BY _score DESC;
    ```
    
    How it works:
    
    - **FE.** The TVF parses the properties into a `LanceRefSelector` and
    loads its metadata through the same
    `LanceCatalogClient.readTableSnapshot` as table scans, so
    storage-versioned and namespace-managed tables follow the #68453 rules
    unchanged. Schema, search column and field id, vector type and
    dimension, fragments and index segments all come from the selected
    snapshot, and planning never reopens the dataset. The splits carry the
    branch directory URI and the version, so no thrift change is needed.
    - **Each execution resolves again.** A bound TVF is never cached,
    prepared statements re-analyze on every `EXECUTE`, and TVF statements
    skip the SQL cache, so the latest version, a future time, a branch head
    and a moved tag are resolved per execution and stay fixed within its
    plan. `CREATE TABLE AS SELECT` plans its query twice (schema, then
    rows), so there a moving selector can resolve twice, as it already can
    for a table scan with an explicit selector; pinning `version` gives an
    exact copy. This is documented.
    - **No fallback.** A snapshot that cannot be selected, or whose index
    files are missing, is an error; nothing falls back to the latest
    version.
    - **EXPLAIN** of a search node now shows `lanceCatalogType`,
    `lanceManagedVersioning` and `lanceBranch` next to `lanceVersion`, as
    table scans do. Planner errors that name "dataset version N" also name
    the branch, since branch versions overlap main's.
    
    Decisions worth calling out:
    
    - `version` takes only a number. `FOR VERSION AS OF 'x'` names a tag
    because SQL has one clause for both; the TVF has a `tag` property, and
    Lance allows tag names made of digits, which `FOR VERSION AS OF` cannot
    reach.
    - An empty selector value is an error rather than "not set", so an empty
    client-side variable cannot silently search the latest version of
    `main`.
    - The selector properties must be constants. Accepting `?` would leave
    PREPARE without a snapshot to take the result schema from.
    `full_text_search` now rejects `?` in any property: until now a
    placeholder reached it as the literal text "?", so `'query'=?` searched
    for "?".
    - Each search relation resolves its own snapshot, as each explicit
    selector already does for table scans. `vector_search(t) JOIN t` can
    read two versions if a commit lands in between; pinning both with
    `version` / `FOR VERSION AS OF` avoids that. This is documented.
    - A managed table's branch is opened by a URI Doris joins
    (`<table>/tree/<branch>`), which Lance does not validate on that path,
    so Doris now rejects names that could leave the table's `tree/`
    directory or change that URI: empty segments, `..`, `\`, and ASCII
    characters other than letters, digits, `.`, `-`, `_` and `/`, so
    `../other` and a percent-encoded dot segment are rejected before the
    branch is opened. Outside ASCII only whitespace and control characters
    are rejected, so no name Lance accepts is rejected, whichever Unicode
    version the JDK and Lance's Rust use. Other tables check a branch out
    through Lance, which validates the name itself.
    
    BE changes:
    
    - A search split or a two-phase row fetch without a positive version is
    rejected instead of opening the latest version.
    - Errors from opening the dataset, reading batches, preparing the FTS
    query context and the two-phase row fetch name the snapshot: "... at
    Lance dataset version N at <uri>", with the query string and any
    password removed from the URI. Missing index files surface at execution
    because Lance loads indexes lazily.
    - Fragment ids from the FE must exist in the opened snapshot. lance-c
    silently skips unknown fragment ids, which would drop rows without an
    error.
    - The profile records `LanceDatasetVersion` and `LanceDatasetUri`, the
    snapshot an execution actually read. EXPLAIN cannot show this for moving
    selectors because it resolves again.
    - **Behavior change for every vector search:** a split without index
    segments now always runs flat (`use_index=false`). The FE plans such
    splits as flat search, and EXPLAIN and the profile count them as flat,
    but Lance used to search them with the first index on the column in
    manifest order, which need not be the index the FE selected (for example
    while an index is rebuilt under a new name). Indexes the FE cannot plan
    with (no fragment coverage metadata, no recorded metric, or a legacy
    index whose details Lance cannot infer from its files, which the FE
    skips; `lanceVectorIndexStatus=UNKNOWN_COVERAGE` / `METRIC_MISMATCH` /
    `NO_MATCH`) are therefore no longer used implicitly, and such searches
    become exact flat searches. Results can change only where the unplanned
    index was approximate; latency can grow on such datasets. Legacy indexes
    that lack details but whose details Lance infers, such as those written
    by Lance 0.10 to 0.24, are planned and searched as before
    (`test_lance_vector_search_legacy_index`).
    - A vector split that carries index segments while the request says
    `use_index=false` is rejected. The FE plans segments only when
    `use_index` allows them, so it never sends such a split; the BE now
    takes `use_index` from the segments and would otherwise have to override
    either the plan or the request.
    
    Known limitations (documented):
    
    - A branch of a branch, or a branch of a shallow clone, can fail to find
    the index files it inherited, because Lance writers before v13 record
    them under the intermediate branch (lance-format/lance#9176). The search
    fails with an error.
    - After a branch is deleted and recreated under the same name, or a
    dataset is replaced at the same URI, version numbers repeat. Since
    #68615 the BE's Lance keys the index list and the row-id index by the
    manifest e_tag (lance-format/lance#8904, #8930), but the BE's
    process-wide Lance session still keys two entries by version alone,
    until eviction or restart. On datasets with stable row ids, the live-row
    mask that vector and full-text search prefilter with can come from the
    old data, so rows deleted in the new data can reappear or live rows can
    be missing (lance-format/lance#9079, open). For a manifest without an
    e_tag (V1 naming, or a store that returns no ETag), the index list can
    come from the old data, on the BE and in the FE's Lance session until
    the catalog is refreshed. Neither is introduced by this PR.
    - `SHOW INDEX` and `lance_index_entries()` keep showing the latest
    version of `main`.
    
    ### Release note
    
    `vector_search()` and `full_text_search()` accept `version`,
    `timestamp`, `tag` and `branch` to search a historical version, the
    version at a time, a tag or a branch of a Lance table, including REST
    Namespace managed tables. Vector search no longer uses an index the
    planner did not select, and `full_text_search()` rejects
    prepared-statement placeholders.
    
    ### Check List (For Author)
    
    - Test: Regression test / Unit Test
    - Regression: `external_table_p0/lance/test_lance_search_snapshot`
    (filesystem catalog) and `test_lance_rest_search_snapshot` (REST,
    storage-versioned and managed) on a new fixture `search_snapshot.lance`.
    It has seven versions (appends, a vector index, an FTS index, an append
    no index covers, a delete, a vector index rebuild), a tag, and a branch
    `dev` whose versions and fragment ids overlap main's with different
    rows, plus a tag at a non-latest branch version.
    `search_snapshot_pruned.lance` lost a version to cleanup and the index
    files of a tagged version. `search_snapshot_evolved.lance` adds a column
    and renames the vector column after its index is built, then appends
    data the index does not cover. The suites check rows, distances,
    two-phase reads (on a branch, a tag, the columns of a version before and
    after a rename, and a managed table through REST), EXPLAIN, full-text
    search across a delete, `use_index=false` with a selector, every
    selector error, and a managed branch named with a Unicode 16 letter
    (`unicode_branch.lance`, built by pylance 12.0.0) through a table scan,
    a search and a two-phase read. `test_lance_rest_catalog.out` and
    `test_lance_rest_time_travel.out` list the new REST tables.
    `test_lance_vector_search_legacy_index` searches a vector index written
    by pylance 0.18.2 without index details and checks that it is planned
    (`USED`, one segment) and returns the flat search's rows. All 30 suites
    in `external_table_p0/lance` pass locally.
    - FE unit tests: `LanceSearchSelectorTest` (property rules, time zones,
    selector forwarding), `LancePreparedSearchTest` (both TVFs pass their
    selector to the table; each analysis resolves it exactly once, and a
    moved tag is resolved again on the next `EXECUTE`; search statements
    bypass the SQL cache; placeholders rejected), `LanceScanNodeTest`
    (EXPLAIN, errors naming the branch), `LanceCatalogClientTest` (branch
    names, including letters newer than JDK 17's Unicode tables), and, with
    real datasets and locally only like the other JNI tests,
    `LanceSearchSnapshotTest` (historical index coverage, branches, tags,
    schema evolution, cleanup, a snapshot planned before later commits) and
    `LanceManagedVersioningTest` (managed versions, tags, branches,
    unfinalized heads through the search entry points).
    - BE unit tests in `lance_reader_test.cpp`: missing fragment ids on
    normal, vector and FTS splits, unpinned versions, error and profile
    contents, a split without index segments searching flat although an
    index covers it, and a split with index segments under `use_index=false`
    being rejected. The indexed variants of the existing multi-vector tests
    now pass the index segments the FE would plan.
    - Behavior changed: Yes. New TVF properties; vector splits without index
    segments always search flat; `full_text_search` rejects `?`; managed
    branch names are validated; the error for a time in removed history now
    reads "Lance cannot select the version at or before '...'" instead of
    "Lance cannot resolve FOR TIME AS OF '...'", because the TVF reaches it
    too; BE errors name the dataset version and URI.
    - Does this need documentation: Yes (apache/doris-website#4185)
---
 be/src/format_v2/table/lance_reader.cpp            | 141 +++++-
 be/src/format_v2/table/lance_reader.h              |   8 +
 be/test/format_v2/table/lance_reader_test.cpp      | 368 ++++++++++++++-
 .../docker-compose/iceberg/iceberg.yaml.tpl        |  17 +-
 .../scripts/lance_build_legacy_vector_index.py     | 100 ++++
 .../scripts/lance_build_preinstalled_catalog.py    |  41 +-
 .../iceberg/scripts/lance_build_search_snapshot.py | 329 ++++++++++++++
 .../iceberg/scripts/lance_build_unicode_branch.py  | 135 ++++++
 .../iceberg/scripts/lance_fixture_requirements.txt |   6 +
 .../bc324f21-a15a-45bf-8d9e-09538f895f55/index.idx | Bin 0 -> 9341 bytes
 .../0-c5e3be90-3de0-44fb-95b1-bd46928ae0f2.txn     | Bin 0 -> 184 bytes
 .../1-9c8d1a85-5125-46ad-aeb8-8370bba30617.txn     | Bin 0 -> 99 bytes
 .../legacy_vector_index.lance/_versions/1.manifest | Bin 0 -> 253 bytes
 .../legacy_vector_index.lance/_versions/2.manifest | Bin 0 -> 315 bytes
 .../02cdc0ff-ceee-44ef-bccd-6cb6f4b50779.lance     | Bin 0 -> 10641 bytes
 .../_deletions/0-5-1267712482458982649.arrow       | Bin 0 -> 698 bytes
 .../_deletions/1-5-6394601565774866848.arrow       | Bin 0 -> 698 bytes
 .../auxiliary.idx                                  | Bin 0 -> 1201 bytes
 .../85880db4-716d-49b3-8eb2-fdadcc900e25/index.idx | Bin 0 -> 332 bytes
 .../auxiliary.idx                                  | Bin 0 -> 1265 bytes
 .../984593f1-89f1-4849-83f9-d3e45462c244/index.idx | Bin 0 -> 332 bytes
 .../metadata.lance                                 | Bin 0 -> 654 bytes
 .../part_0_docs.lance                              | Bin 0 -> 626 bytes
 .../part_0_invert.lance                            | Bin 0 -> 3479 bytes
 .../part_0_tokens.lance                            | Bin 0 -> 731 bytes
 .../search_snapshot.lance/_refs/branches/dev.json  |  15 +
 .../search_snapshot.lance/_refs/tags/dev_rel.json  |   8 +
 .../search_snapshot.lance/_refs/tags/rel.json      |   8 +
 .../0-154ed129-09cd-48de-89ac-618fc1060501.txn     | Bin 0 -> 237 bytes
 .../1-d6645060-096c-4335-8bd9-c595a08fdd34.txn     | Bin 0 -> 124 bytes
 .../2-1518405c-5551-4e8f-b615-a0ca0d754255.txn     | Bin 0 -> 372 bytes
 .../3-c7c138f8-03a8-4564-9fc5-d59c25c2223c.txn     | Bin 0 -> 278 bytes
 .../4-1cbab51a-2c2d-41c4-8025-30daa3cc11a4.txn     | Bin 0 -> 124 bytes
 .../5-630bd020-d3af-4be8-b5e8-33388c068adc.txn     | Bin 0 -> 259 bytes
 .../6-9a8f0e65-3b5d-49ac-b232-5990ddd60891.txn     | Bin 0 -> 702 bytes
 .../_versions/18446744073709551608.manifest        | Bin 0 -> 1789 bytes
 .../_versions/18446744073709551609.manifest        | Bin 0 -> 1343 bytes
 .../_versions/18446744073709551610.manifest        | Bin 0 -> 1173 bytes
 .../_versions/18446744073709551611.manifest        | Bin 0 -> 1244 bytes
 .../_versions/18446744073709551612.manifest        | Bin 0 -> 1104 bytes
 .../_versions/18446744073709551613.manifest        | Bin 0 -> 521 bytes
 .../_versions/18446744073709551614.manifest        | Bin 0 -> 551 bytes
 .../_versions/latest_version_hint.json             |   1 +
 ...11110000001111167198a47f9880a55a8085ebb87.lance | Bin 0 -> 1211 bytes
 ...010111000101110284ca44e90bfc0c56be666a32f.lance | Bin 0 -> 1211 bytes
 ...111011110010100fc3e5d485e9c40f5a217eaa59e.lance | Bin 0 -> 1211 bytes
 .../metadata.lance                                 | Bin 0 -> 654 bytes
 .../part_0_docs.lance                              | Bin 0 -> 690 bytes
 .../part_0_invert.lance                            | Bin 0 -> 2987 bytes
 .../part_0_tokens.lance                            | Bin 0 -> 731 bytes
 .../4-a99a47e7-aae1-46cf-87f7-4cc649db3aa1.txn     |   1 +
 .../4-d995fee3-982e-4e43-8e30-94537a9b0de2.txn     | Bin 0 -> 124 bytes
 .../5-6028c4ff-0a8e-4938-9d58-8a13524f6812.txn     | Bin 0 -> 516 bytes
 .../dev/_versions/18446744073709551609.manifest    | Bin 0 -> 1632 bytes
 .../dev/_versions/18446744073709551610.manifest    | Bin 0 -> 1240 bytes
 .../dev/_versions/18446744073709551611.manifest    | Bin 0 -> 1128 bytes
 ...01010111100101014250f4aa0a70d3d926f124125.lance | Bin 0 -> 1211 bytes
 .../auxiliary.idx                                  | Bin 0 -> 1008 bytes
 .../72e585d1-b843-4463-aba0-ffabc76017c1/index.idx | Bin 0 -> 332 bytes
 .../0-fecb1851-f6b0-496c-bfb8-f4dbe7f649f1.txn     | Bin 0 -> 237 bytes
 .../1-5a98fef6-06a5-457c-b1b1-a9c830eafd2b.txn     | Bin 0 -> 370 bytes
 .../2-9bdddb95-2dc3-4e77-95b9-f67ed6e6387e.txn     | Bin 0 -> 346 bytes
 .../3-954a5d41-5fc9-4e39-96d9-864e1ac233bc.txn     |   5 +
 .../4-a41517b8-29a3-410f-b3ae-768c33b38cf5.txn     | Bin 0 -> 126 bytes
 .../_versions/18446744073709551610.manifest        | Bin 0 -> 970 bytes
 .../_versions/18446744073709551611.manifest        | Bin 0 -> 956 bytes
 .../_versions/18446744073709551612.manifest        | Bin 0 -> 1099 bytes
 .../_versions/18446744073709551613.manifest        | Bin 0 -> 1016 bytes
 .../_versions/18446744073709551614.manifest        | Bin 0 -> 551 bytes
 .../_versions/latest_version_hint.json             |   1 +
 ...001001000111000634254483b82696db0b43cee8b.lance | Bin 0 -> 1576 bytes
 ...0111000011010107529f744f0b515d3cc0aaf4111.lance | Bin 0 -> 416 bytes
 ...0000010110100009494424b38a01956f50baa341d.lance | Bin 0 -> 1211 bytes
 .../auxiliary.idx                                  | Bin 0 -> 1008 bytes
 .../961caf93-b3e9-45b9-b1a7-8944a37213ea/index.idx | Bin 0 -> 332 bytes
 .../_refs/tags/kept.json                           |   8 +
 .../1-5c4816b8-2e0a-46bb-aa6c-0879630399b4.txn     | Bin 0 -> 370 bytes
 .../2-b57c17ad-85a6-415b-a250-4b2efe8d3f8c.txn     | Bin 0 -> 696 bytes
 .../_versions/18446744073709551612.manifest        | Bin 0 -> 1343 bytes
 .../_versions/18446744073709551613.manifest        | Bin 0 -> 1017 bytes
 .../_versions/latest_version_hint.json             |   1 +
 ...110111001110011284b0f491a947f1b18c7abddff.lance | Bin 0 -> 1211 bytes
 .../_refs/branches/dev%E1%B2%89.json               |  15 +
 .../0-420a1091-b61a-4cfb-8006-0b8f1e322ef8.txn     | Bin 0 -> 237 bytes
 .../_versions/18446744073709551614.manifest        | Bin 0 -> 552 bytes
 .../_versions/latest_version_hint.json             |   1 +
 ...101111000101000a13eb949eca41d69d17f9ea5a6.lance | Bin 0 -> 1146 bytes
 .../1-1be00bd2-8443-4851-9ab8-4bdcee3ffa5e.txn"    | Bin 0 -> 124 bytes
 .../1-c1998c6f-6213-4b7e-ae7c-cc00cde3b7de.txn"    |   1 +
 .../_versions/18446744073709551613.manifest"       | Bin 0 -> 585 bytes
 .../_versions/18446744073709551614.manifest"       | Bin 0 -> 476 bytes
 ...1000100001111040aa57401ab473a6a921298540.lance" | Bin 0 -> 1017 bytes
 .../doris/datasource/lance/LanceCatalogClient.java |  78 +++-
 .../datasource/lance/LanceExternalCatalog.java     |  12 +-
 .../doris/datasource/lance/LanceExternalTable.java |  15 +-
 .../lance/index/LanceDatasetIndexDiscovery.java    |   6 +-
 .../lance/metadata/LanceRefSelector.java           |  11 +-
 .../lance/metadata/LanceSnapshotResolver.java      |  25 +
 .../datasource/lance/source/LanceScanNode.java     |  22 +-
 .../datasource/lance/source/LanceScanPlan.java     |  11 +-
 .../datasource/lance/source/LanceScanPlanner.java  |  14 +-
 .../doris/nereids/parser/LogicalPlanBuilder.java   |  10 +
 .../FullTextSearchTableValuedFunction.java         |   2 +-
 .../LanceExternalSearchTableValuedFunction.java    |  89 +++-
 .../VectorSearchTableValuedFunction.java           |   2 +-
 .../datasource/lance/LanceCatalogClientTest.java   |  26 ++
 .../lance/LanceManagedVersioningTest.java          |  82 +++-
 .../datasource/lance/LanceSearchSnapshotTest.java  | 506 +++++++++++++++++++++
 .../datasource/lance/source/LanceScanNodeTest.java |  61 ++-
 .../tablefunction/LancePreparedSearchTest.java     | 202 +++++++-
 .../tablefunction/LanceSearchSelectorTest.java     | 189 ++++++++
 .../VectorSearchTableValuedFunctionTest.java       |   3 +-
 .../lance/test_lance_rest_catalog.out              |   5 +
 .../lance/test_lance_rest_search_snapshot.out      |  59 +++
 .../lance/test_lance_rest_time_travel.out          |   5 +
 .../lance/test_lance_search_snapshot.out           | 182 ++++++++
 .../test_lance_vector_search_legacy_index.out      |  11 +
 .../lance/test_lance_rest_search_snapshot.groovy   | 202 ++++++++
 .../lance/test_lance_search_snapshot.groovy        | 452 ++++++++++++++++++
 .../test_lance_vector_search_legacy_index.groovy   |  90 ++++
 120 files changed, 3479 insertions(+), 103 deletions(-)

diff --git a/be/src/format_v2/table/lance_reader.cpp b/be/src/format_v2/table/lance_reader.cpp
index b9e5054a2a6..73d68332f49 100644
--- a/be/src/format_v2/table/lance_reader.cpp
+++ b/be/src/format_v2/table/lance_reader.cpp
@@ -74,6 +74,37 @@ Status LanceTableReader::fetch_schema(const TFileRangeDesc& range,
     return convert_arrow_schema_to_doris(schema, column_names, column_types);
 }
 
+namespace {
+// A dataset URI without its query string or a password in its user information, either of which
+// may carry credentials, for errors and profiles. A user part without a password stays: Azure
+// URIs name the container there (abfss://container@account...).
+std::string display_uri(const std::string& uri) {
+    std::string display = uri.substr(0, uri.find('?'));
+    const auto authority = display.find("://");
+    if (authority != std::string::npos) {
+        const auto start = authority + 3;
+        const auto at = display.find('@', start);
+        const auto colon = display.find(':', start);
+        if (at != std::string::npos && at < display.find('/', start) && colon < at) {
+            display.erase(start, at + 1 - start);
+        }
+    }
+    return display;
+}
+
+// A Lance version of 0 opens the latest version, which would silently leave the snapshot FE
+// planned. Search splits and row-id fetches always carry FE's pinned version.
+Status require_fixed_version(const TFileRangeDesc& range, std::string_view what) {
+    const auto& params = range.table_format_params.lance_params;
+    if (!params.__isset.version || params.version <= 0) {
+        return Status::InvalidArgument(
+                "Lance {} requires a fixed positive dataset version, but got {}", what,
+                params.__isset.version ? std::to_string(params.version) : std::string("none"));
+    }
+    return Status::OK();
+}
+} // namespace
+
 Status LanceTableReader::init(TableReadOptions&& options) {
     RETURN_IF_ERROR(TableReader::init(std::move(options)));
     DORIS_CHECK(_runtime_state != nullptr);
@@ -161,6 +192,9 @@ Status LanceTableReader::prepare_split(const SplitReadOptions& options) {
                 "Lance global row id requested without global row id context");
     }
 
+    if (_search_kind != SearchKind::NORMAL) {
+        RETURN_IF_ERROR(require_fixed_version(options.current_range, "search split"));
+    }
     RETURN_IF_ERROR(_ensure_dataset_open(options.current_range));
     RETURN_IF_ERROR(_open_scanner(options.current_range));
     return Status::OK();
@@ -209,7 +243,7 @@ Status LanceTableReader::get_block(Block* block, bool* eos) {
                 break;
             }
             if (scan_status != 0 || raw_batch == nullptr) {
-                return lance_error("read next Lance batch");
+                return lance_error("read next Lance batch at " + _snapshot_description());
             }
 
             std::unique_ptr<LanceBatch, LanceBatchDeleter> batch(raw_batch);
@@ -261,6 +295,8 @@ Status LanceTableReader::read_by_row_ids(const TFileRangeDesc& range,
                                                     TUnit::UNIT, LANCE_READER_PROFILE, 1);
     SCOPED_TIMER(_row_id_fetch_total_time);
 
+    // Row IDs mean something only within the snapshot phase one read.
+    RETURN_IF_ERROR(require_fixed_version(range, "row-id fetch"));
     // Phase-two row fetch does not execute FTS, so a reader created only for take_rows must not
     // collect query-specific global statistics.
     RETURN_IF_ERROR(_ensure_dataset_open(range, false));
@@ -283,15 +319,15 @@ Status LanceTableReader::read_by_row_ids(const TFileRangeDesc& range,
         if (stream.release != nullptr) {
             stream.release(&stream);
         }
-        return lance_error("take Lance rows by row id");
+        return lance_error("take Lance rows by row id at " + _snapshot_description());
     }
     auto imported_reader = arrow::ImportRecordBatchReader(&stream);
     if (!imported_reader.ok()) {
         if (stream.release != nullptr) {
             stream.release(&stream);
         }
-        return Status::InternalError("import Lance take-rows stream failed: {}",
-                                     imported_reader.status().message());
+        return Status::InternalError("import Lance take-rows stream at {} failed: {}",
+                                     _snapshot_description(), imported_reader.status().message());
     }
 
     size_t fetched_rows = 0;
@@ -305,8 +341,8 @@ Status LanceTableReader::read_by_row_ids(const TFileRangeDesc& range,
             read_status = batch_reader->ReadNext(&record_batch);
         }
         if (!read_status.ok()) {
-            return Status::InternalError("read Lance take-rows batch failed: {}",
-                                         read_status.message());
+            return Status::InternalError("read Lance take-rows batch at {} failed: {}",
+                                         _snapshot_description(), read_status.message());
         }
         if (record_batch == nullptr) {
             break;
@@ -321,8 +357,9 @@ Status LanceTableReader::read_by_row_ids(const TFileRangeDesc& range,
         COUNTER_UPDATE(fetch_rows, rows);
     }
     if (fetched_rows != row_ids.size()) {
-        return Status::InternalError("Lance row-id fetch returned {} rows for {} requested row ids",
-                                     fetched_rows, row_ids.size());
+        return Status::InternalError(
+                "Lance row-id fetch at {} returned {} rows for {} requested row ids",
+                _snapshot_description(), fetched_rows, row_ids.size());
     }
     return Status::OK();
 }
@@ -593,15 +630,66 @@ Status LanceTableReader::_open_dataset(const DatasetKey& key) {
     {
         SCOPED_TIMER(_dataset_open_time);
         LanceDataset* raw_dataset = nullptr;
-        RETURN_IF_ERROR(LanceSessionManager::instance().open_dataset(
+        Status status = LanceSessionManager::instance().open_dataset(
                 key.uri.c_str(), key.storage_options.empty() ? nullptr : storage_option_ptrs.data(),
-                static_cast<uint64_t>(key.version), &raw_dataset));
+                static_cast<uint64_t>(key.version), &raw_dataset);
+        if (!status.ok()) {
+            return status.prepend(fmt::format("Lance dataset version {} at {}: ", key.version,
+                                              display_uri(key.uri)));
+        }
         dataset.reset(raw_dataset);
     }
+
+    // EXPLAIN plans a moving selector separately, so only the profile shows what this execution
+    // read. The version is the one opened, which version 0 (the latest) resolves.
+    _opened_version = static_cast<int64_t>(lance_dataset_version(dataset.get()));
+    _scanner_profile->add_info_string("LanceDatasetVersion", std::to_string(_opened_version));
+    _scanner_profile->add_info_string("LanceDatasetUri", display_uri(key.uri));
     _dataset = dataset.release();
     return Status::OK();
 }
 
+Status LanceTableReader::_check_fragment_ids(const std::vector<uint64_t>& fragment_ids) const {
+    if (fragment_ids.empty()) {
+        return Status::OK();
+    }
+    if (!_dataset_fragment_ids.has_value()) {
+        // A count of 0 is also lance-c's error value; a failed listing then leaves the list empty,
+        // so every fragment id FE sends is still rejected rather than skipped.
+        const uint64_t fragment_count = lance_dataset_fragment_count(_dataset);
+        std::vector<uint64_t> ids(fragment_count);
+        if (fragment_count > 0 && lance_dataset_fragment_ids(_dataset, ids.data()) != 0) {
+            return lance_error("list fragments of " + _snapshot_description());
+        }
+        std::sort(ids.begin(), ids.end());
+        _dataset_fragment_ids = std::move(ids);
+    }
+    std::vector<uint64_t> missing;
+    for (uint64_t id : fragment_ids) {
+        if (!std::binary_search(_dataset_fragment_ids->begin(), _dataset_fragment_ids->end(), id)) {
+            missing.emplace_back(id);
+        }
+    }
+    if (!missing.empty()) {
+        return Status::InternalError(
+                "Lance split references fragment ids [{}] that {} does not contain",
+                fmt::join(missing, ", "), _snapshot_description());
+    }
+    return Status::OK();
+}
+
+std::string LanceTableReader::_snapshot_description() const {
+    if (!_opened_dataset_key.has_value()) {
+        return "Lance dataset";
+    }
+    // Version 0 asks for the latest version; name the one that was opened. No lance-c call here:
+    // callers build this message before lance_error() reads the thread's last error, which a
+    // successful lance-c call clears.
+    const auto version = _opened_version > 0 ? _opened_version : _opened_dataset_key->version;
+    return fmt::format("Lance dataset version {} at {}", version,
+                       display_uri(_opened_dataset_key->uri));
+}
+
 Status LanceTableReader::_prepare_fts_query_context() {
     DORIS_CHECK(_dataset != nullptr);
     DORIS_CHECK(_fts_query_context == nullptr);
@@ -632,7 +720,7 @@ Status LanceTableReader::_prepare_fts_query_context() {
                 coverage_mode);
     }
     if (_fts_query_context == nullptr) {
-        return lance_error("prepare Lance FTS query context");
+        return lance_error("prepare Lance FTS query context at " + _snapshot_description());
     }
     return Status::OK();
 }
@@ -923,6 +1011,7 @@ Status LanceTableReader::_configure_normal_scan(LanceScanner* scanner,
     DORIS_CHECK(scanner != nullptr);
     std::vector<uint64_t> fragment_ids;
     RETURN_IF_ERROR(parse_fragment_ids(lance_params, &fragment_ids));
+    RETURN_IF_ERROR(_check_fragment_ids(fragment_ids));
     if (!fragment_ids.empty() &&
         lance_scanner_set_fragment_ids(scanner, fragment_ids.data(), fragment_ids.size()) != 0) {
         return lance_error("set Lance scanner fragment ids");
@@ -963,8 +1052,12 @@ Status LanceTableReader::_configure_vector_search(LanceScanner* scanner,
     DORIS_CHECK(scanner != nullptr);
     DORIS_CHECK(_scan_params != nullptr);
     DORIS_CHECK(_scan_params->__isset.lance_scan_params);
+    const auto& lance_scan_params = _scan_params->lance_scan_params;
+    DORIS_CHECK(lance_scan_params.__isset.external_search_request);
+    const auto& request = lance_scan_params.external_search_request;
     std::vector<uint64_t> fragment_ids;
     RETURN_IF_ERROR(parse_fragment_ids(lance_params, &fragment_ids));
+    RETURN_IF_ERROR(_check_fragment_ids(fragment_ids));
     if (!fragment_ids.empty() &&
         lance_scanner_set_fragment_ids(scanner, fragment_ids.data(), fragment_ids.size()) != 0) {
         return lance_error("set Lance vector scanner fragment ids");
@@ -972,6 +1065,15 @@ Status LanceTableReader::_configure_vector_search(LanceScanner* scanner,
     std::vector<uint8_t> segment_uuids;
     size_t segment_count = 0;
     RETURN_IF_ERROR(parse_index_segment_uuids(lance_params, &segment_uuids, &segment_count));
+    // FE plans index segments only when use_index allows them. A split carrying both contradicts
+    // itself, and the BE would have to override either FE's plan or the request.
+    if (segment_count > 0 && request.__isset.vector_search_options &&
+        request.vector_search_options.__isset.use_index &&
+        !request.vector_search_options.use_index) {
+        return Status::InvalidArgument(
+                "Lance vector search split carries {} index segments although use_index is false",
+                segment_count);
+    }
     if (segment_count > 0 &&
         lance_scanner_set_index_segments(scanner, segment_uuids.data(), segment_count) != 0) {
         return lance_error("set Lance vector scanner index segments");
@@ -981,9 +1083,6 @@ Status LanceTableReader::_configure_vector_search(LanceScanner* scanner,
     if (lance_scanner_set_prefilter(scanner, true) != 0) {
         return lance_error("enable Lance vector prefilter");
     }
-    const auto& lance_scan_params = _scan_params->lance_scan_params;
-    DORIS_CHECK(lance_scan_params.__isset.external_search_request);
-    const auto& request = lance_scan_params.external_search_request;
     const auto& vector = request.search_query.vector_search;
     const auto& query = vector.query_vector;
     const auto dimension = static_cast<size_t>(query.dimension);
@@ -1102,10 +1201,13 @@ Status LanceTableReader::_configure_vector_search(LanceScanner* scanner,
             lance_scanner_set_ef(scanner, static_cast<uint32_t>(options.ef)) != 0) {
             return lance_error("set Lance vector ef");
         }
-        if (options.__isset.use_index &&
-            lance_scanner_set_use_index(scanner, options.use_index) != 0) {
-            return lance_error("set Lance vector use_index");
-        }
+    }
+    // FE plans a split without index segments as a flat search, and EXPLAIN and the profile count
+    // it as one. Lance would otherwise search it with the first index on the column in manifest
+    // order, which need not be the index FE selected. A split with segments searches exactly
+    // those; one that also carries use_index=false was rejected above.
+    if (lance_scanner_set_use_index(scanner, segment_count > 0) != 0) {
+        return lance_error("set Lance vector use_index");
     }
     if (lance_scanner_set_offset(scanner, vector.offset) != 0) {
         return lance_error("set Lance vector offset");
@@ -1133,6 +1235,7 @@ Status LanceTableReader::_configure_full_text_search(LanceScanner* scanner,
     // prepared FTS context; the segment UUID is the execution boundary.
     std::vector<uint64_t> fragment_ids;
     RETURN_IF_ERROR(parse_fragment_ids(lance_params, &fragment_ids));
+    RETURN_IF_ERROR(_check_fragment_ids(fragment_ids));
     std::vector<uint8_t> segment_uuids;
     size_t segment_count = 0;
     RETURN_IF_ERROR(parse_index_segment_uuids(lance_params, &segment_uuids, &segment_count));
@@ -1251,6 +1354,8 @@ void LanceTableReader::_close_dataset() {
         _dataset = nullptr;
     }
     _dataset_schema.reset();
+    _dataset_fragment_ids.reset();
+    _opened_version = 0;
     _record_batch_converter.reset_schema();
 }
 
diff --git a/be/src/format_v2/table/lance_reader.h b/be/src/format_v2/table/lance_reader.h
index 88deea610b3..6fe11480bc6 100644
--- a/be/src/format_v2/table/lance_reader.h
+++ b/be/src/format_v2/table/lance_reader.h
@@ -78,6 +78,10 @@ private:
     Status _validate_external_search_request() const;
     Status _ensure_dataset_open(const TFileRangeDesc& range, bool prepare_fts_context = true);
     Status _open_dataset(const DatasetKey& key);
+    // Rejects FE fragment ids the opened snapshot lacks; lance-c would silently skip them.
+    Status _check_fragment_ids(const std::vector<uint64_t>& fragment_ids) const;
+    // Names the opened snapshot in execution errors, since several share one URI or version.
+    std::string _snapshot_description() const;
     Status _prepare_fts_query_context();
     Status _open_scanner(const TFileRangeDesc& range);
     void _init_scanner_profile();
@@ -103,6 +107,10 @@ private:
     LanceScanner* _scanner = nullptr;
     ShardedKVCache* _runtime_filter_cache = nullptr;
     std::optional<DatasetKey> _opened_dataset_key;
+    // Sorted fragment ids of the opened snapshot, listed on the first split that names any.
+    mutable std::optional<std::vector<uint64_t>> _dataset_fragment_ids;
+    // The version the open dataset resolved to, which differs from the key's for version 0.
+    int64_t _opened_version = 0;
     LanceRecordBatchConverter _record_batch_converter;
     size_t _scanner_batch_size = 0;
     RuntimeProfile::Counter* _planned_index_segment_count = nullptr;
diff --git a/be/test/format_v2/table/lance_reader_test.cpp b/be/test/format_v2/table/lance_reader_test.cpp
index e952d8da483..d13665f2998 100644
--- a/be/test/format_v2/table/lance_reader_test.cpp
+++ b/be/test/format_v2/table/lance_reader_test.cpp
@@ -448,6 +448,18 @@ Status get_index_segment_uuids(const std::filesystem::path& dataset_uri, const c
     return Status::OK();
 }
 
+// A split over `fragment_ids` searching the segments of `index_name`, as FE plans an indexed split;
+// BE searches a vector index only through the segments FE names.
+TFileRangeDesc make_indexed_lance_range(const std::filesystem::path& dataset_uri,
+                                        const LanceFixtureInfo& fixture,
+                                        std::vector<int64_t> fragment_ids, const char* index_name) {
+    auto range = make_lance_range(dataset_uri, fixture.version, std::move(fragment_ids));
+    std::vector<std::string> segment_uuids;
+    EXPECT_TRUE(get_index_segment_uuids(dataset_uri, index_name, &segment_uuids).ok());
+    range.table_format_params.lance_params.__set_index_segment_uuids(std::move(segment_uuids));
+    return range;
+}
+
 TFileRangeDesc make_full_text_search_range(const std::filesystem::path& dataset_uri,
                                            const LanceFixtureInfo& fixture,
                                            const char* index_name) {
@@ -880,7 +892,16 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorScoresFiltersOffsetsAndIndexed
                 }
                 LanceTableReader reader;
                 ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &params).ok());
-                ASSERT_TRUE(prepare_fixture(&reader, uri, fixture, fixture.fragment_ids).ok());
+                // BE searches an index only through the segments FE planned; the index covers
+                // fragment 0 and fragment 1 is searched flat in the same split.
+                auto range = make_lance_range(uri, fixture.version, fixture.fragment_ids);
+                if (indexed) {
+                    std::vector<std::string> segments;
+                    ASSERT_TRUE(get_index_segment_uuids(uri, (column + "_idx").c_str(), &segments)
+                                        .ok());
+                    range.table_format_params.lance_params.__set_index_segment_uuids(segments);
+                }
+                ASSERT_TRUE(prepare_range(&reader, range).ok());
                 Block block;
                 add_output_columns(&block, columns);
                 auto rows = read_vector_search_rows(&reader, &block);
@@ -1058,6 +1079,328 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorSegmentTopKMatchesIndependentG
     }
 }
 
+TEST(LanceTableReaderVectorSearchTest, SplitWithoutIndexSegmentsSearchesFlat) {
+    // FE plans a split without index segments as a flat search. Lance must not search it with
+    // an index of its own choosing, even one covering the split and with use_index=true.
+    const std::filesystem::path uri =
+            "./be/test/format_v2/table/lance/data/multivector_ivf_flat.lance";
+    LanceFixtureInfo fixture;
+    ASSERT_TRUE(get_fixture_info(uri, &fixture).ok());
+    ASSERT_EQ(3, fixture.fragment_ids.size());
+    std::vector<std::string> segments;
+    ASSERT_TRUE(get_index_segment_uuids(uri, "vectors_idx", &segments).ok());
+    ASSERT_EQ(2, segments.size());
+    const auto query = representative_multi_vector(7, 0);
+    const Columns columns {projected_column("row_id", TYPE_BIGINT, false),
+                           projected_column("_distance", TYPE_FLOAT, true)};
+    TQueryGlobals globals;
+    RuntimeState state(globals);
+    std::map<std::string, std::vector<std::pair<int64_t, float>>> results;
+    for (const auto* mode : {"segment", "no_segment_default", "no_segment_use_index"}) {
+        SCOPED_TRACE(mode);
+        RuntimeProfile profile("lance_segmentless_split");
+        auto params = make_float32_vector_search_params({0, 0, 0}, 5, 0);
+        auto& request = params.lance_scan_params.external_search_request;
+        request.vector_search_options.__isset.use_index = false;
+        if (std::string(mode) == "no_segment_use_index") {
+            request.vector_search_options.__set_use_index(true);
+        }
+        request.vector_search_options.__set_nprobes(64);
+        auto& search = request.search_query.vector_search;
+        search.__set_column("vectors");
+        search.__set_metric(TVectorMetric::COSINE);
+        search.query_vector.__set_dimension(128);
+        search.query_vector.__set_num_vectors(1);
+        std::string bytes(query.size() * sizeof(float), '\0');
+        for (size_t j = 0; j < query.size(); ++j) {
+            LittleEndian::Store32(bytes.data() + j * sizeof(float),
+                                  std::bit_cast<uint32_t>(query[j]));
+        }
+        search.query_vector.__set_values(bytes);
+        auto range = make_lance_range(uri, fixture.version, {fixture.fragment_ids[0]});
+        if (std::string(mode) == "segment") {
+            range.table_format_params.lance_params.__set_index_segment_uuids({segments[0]});
+        }
+        LanceTableReader reader;
+        ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &params).ok());
+        ASSERT_TRUE(prepare_range(&reader, range).ok());
+        Block block;
+        add_output_columns(&block, columns);
+        results[mode] = read_vector_search_rows(&reader, &block);
+        ASSERT_EQ(5, results[mode].size());
+        EXPECT_TRUE(reader.close().ok());
+        auto* partitions = profile.get_counter("LanceIVFPartitionsSearched");
+        ASSERT_NE(nullptr, partitions);
+        auto* flat = profile.get_counter("LancePlannedFlatSearchFragmentCount");
+        ASSERT_NE(nullptr, flat);
+        if (std::string(mode) == "segment") {
+            EXPECT_GT(partitions->value(), 0);
+            EXPECT_EQ(0, flat->value());
+        } else {
+            EXPECT_EQ(0, partitions->value());
+            EXPECT_EQ(1, flat->value());
+        }
+    }
+    EXPECT_EQ(results["no_segment_default"], results["no_segment_use_index"]);
+}
+
+TEST(LanceTableReaderVectorSearchTest, RejectsIndexSegmentsWhenUseIndexIsFalse) {
+    // FE plans index segments only when use_index allows them. A split carrying segments under
+    // use_index=false is rejected instead of being searched with or without the index.
+    const std::filesystem::path uri =
+            "./be/test/format_v2/table/lance/data/multivector_ivf_flat.lance";
+    LanceFixtureInfo fixture;
+    ASSERT_TRUE(get_fixture_info(uri, &fixture).ok());
+    std::vector<std::string> segments;
+    ASSERT_TRUE(get_index_segment_uuids(uri, "vectors_idx", &segments).ok());
+    ASSERT_FALSE(segments.empty());
+    const auto query = representative_multi_vector(7, 0);
+    const Columns columns {projected_column("row_id", TYPE_BIGINT, false),
+                           projected_column("_distance", TYPE_FLOAT, true)};
+    TQueryGlobals globals;
+    RuntimeState state(globals);
+    for (const bool with_segment : {true, false}) {
+        SCOPED_TRACE(with_segment ? "with segment" : "without segment");
+        RuntimeProfile profile("lance_segment_with_use_index_false");
+        auto params = make_float32_vector_search_params({0, 0, 0}, 5, 0);
+        auto& request = params.lance_scan_params.external_search_request;
+        ASSERT_TRUE(request.vector_search_options.__isset.use_index);
+        ASSERT_FALSE(request.vector_search_options.use_index);
+        auto& search = request.search_query.vector_search;
+        search.__set_column("vectors");
+        search.__set_metric(TVectorMetric::COSINE);
+        search.query_vector.__set_dimension(128);
+        search.query_vector.__set_num_vectors(1);
+        std::string bytes(query.size() * sizeof(float), '\0');
+        for (size_t j = 0; j < query.size(); ++j) {
+            LittleEndian::Store32(bytes.data() + j * sizeof(float),
+                                  std::bit_cast<uint32_t>(query[j]));
+        }
+        search.query_vector.__set_values(bytes);
+        auto range = make_lance_range(uri, fixture.version, {fixture.fragment_ids[0]});
+        if (with_segment) {
+            range.table_format_params.lance_params.__set_index_segment_uuids({segments[0]});
+        }
+        LanceTableReader reader;
+        ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &params).ok());
+        const auto status = prepare_range(&reader, range);
+        if (with_segment) {
+            EXPECT_FALSE(status.ok());
+            EXPECT_NE(
+                    status.to_string().find("carries 1 index segments although use_index is false"),
+                    std::string::npos)
+                    << status.to_string();
+        } else {
+            ASSERT_TRUE(status.ok()) << status.to_string();
+            Block block;
+            add_output_columns(&block, columns);
+            EXPECT_EQ(5, read_vector_search_rows(&reader, &block).size());
+            auto* flat = profile.get_counter("LancePlannedFlatSearchFragmentCount");
+            ASSERT_NE(nullptr, flat);
+            EXPECT_EQ(1, flat->value());
+        }
+        EXPECT_TRUE(reader.close().ok());
+    }
+}
+
+TEST(LanceTableReaderSnapshotTest, RejectsFragmentIdsMissingFromTheSnapshot) {
+    // lance-c silently skips a fragment id its snapshot lacks, which would drop rows.
+    const std::filesystem::path dataset_uri =
+            "./be/test/format_v2/table/lance/data/all_types.lance";
+    LanceFixtureInfo fixture;
+    ASSERT_TRUE(get_fixture_info(dataset_uri, &fixture).ok());
+    TQueryGlobals query_globals;
+    RuntimeState state(query_globals);
+    const Columns search_columns {projected_column("row_id", TYPE_BIGINT, false),
+                                  projected_column("_distance", TYPE_FLOAT, true)};
+    const Columns scan_columns {projected_column("row_id", TYPE_BIGINT, false)};
+    for (const bool search : {true, false}) {
+        SCOPED_TRACE(search ? "vector search" : "normal scan");
+        RuntimeProfile profile("lance_missing_fragment");
+        auto scan_params = search ? make_float32_vector_search_params({0.0F, 0.0F, 0.0F}, 2, 0)
+                                  : TFileScanRangeParams {};
+        LanceTableReader reader;
+        ASSERT_TRUE(init_reader(&reader, search ? search_columns : scan_columns, &state, &profile,
+                                &scan_params)
+                            .ok());
+        const auto status =
+                prepare_fixture(&reader, dataset_uri, fixture, {fixture.fragment_ids[0], 999});
+        ASSERT_FALSE(status.ok());
+        EXPECT_NE(status.to_string().find(
+                          "references fragment ids [999] that Lance dataset version " +
+                          std::to_string(fixture.version) + " at " + dataset_uri.string() +
+                          " does not contain"),
+                  std::string::npos)
+                << status.to_string();
+        EXPECT_TRUE(reader.close().ok());
+    }
+
+    // Full-text search installs no fragment filter, but its fragment ids still describe the
+    // planned coverage of this snapshot.
+    const std::filesystem::path fts_uri = "./be/test/format_v2/table/lance/data/fts_indexed.lance";
+    LanceFixtureInfo fts_fixture;
+    ASSERT_TRUE(get_fixture_info(fts_uri, &fts_fixture).ok());
+    RuntimeProfile fts_profile("lance_missing_fragment_fts");
+    auto fts_params = make_full_text_search_params("lance", 2, 0);
+    const Columns fts_columns {projected_column("row_id", TYPE_BIGINT, false),
+                               projected_column("_score", TYPE_FLOAT, true)};
+    LanceTableReader fts_reader;
+    ASSERT_TRUE(init_reader(&fts_reader, fts_columns, &state, &fts_profile, &fts_params).ok());
+    auto fts_range = make_full_text_search_range(fts_uri, fts_fixture, "body_fts");
+    fts_range.table_format_params.lance_params.fragment_ids.push_back(999);
+    const auto fts_status = prepare_range(&fts_reader, fts_range);
+    ASSERT_FALSE(fts_status.ok());
+    EXPECT_NE(fts_status.to_string().find("references fragment ids [999]"), std::string::npos)
+            << fts_status.to_string();
+    EXPECT_TRUE(fts_reader.close().ok());
+}
+
+TEST(LanceTableReaderSnapshotTest, RejectsSearchSplitsAndRowIdFetchesWithoutFixedVersion) {
+    // Version 0 opens the latest version, which is not the snapshot FE planned.
+    const std::filesystem::path dataset_uri =
+            "./be/test/format_v2/table/lance/data/all_types.lance";
+    LanceFixtureInfo fixture;
+    ASSERT_TRUE(get_fixture_info(dataset_uri, &fixture).ok());
+    TQueryGlobals query_globals;
+    RuntimeState state(query_globals);
+    const Columns columns {projected_column("row_id", TYPE_BIGINT, false),
+                           projected_column("_distance", TYPE_FLOAT, true)};
+    for (const int64_t version : {int64_t {0}, int64_t {-1}, int64_t {-2}}) {
+        // -2 stands for a version FE never set.
+        const bool unset = version == -2;
+        RuntimeProfile profile("lance_unpinned_search");
+        auto scan_params = make_float32_vector_search_params({0.0F, 0.0F, 0.0F}, 2, 0);
+        LanceTableReader reader;
+        ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &scan_params).ok());
+        auto range = make_lance_range(dataset_uri, version, fixture.fragment_ids);
+        if (unset) {
+            range.table_format_params.lance_params.__isset.version = false;
+        }
+        const auto status = prepare_range(&reader, range);
+        ASSERT_FALSE(status.ok());
+        EXPECT_NE(status.to_string().find(std::string("Lance search split requires a fixed "
+                                                      "positive dataset version, but got ") +
+                                          (unset ? std::string("none") : std::to_string(version))),
+                  std::string::npos)
+                << status.to_string();
+        EXPECT_TRUE(reader.close().ok());
+    }
+
+    RuntimeProfile fetch_profile("lance_unpinned_fetch");
+    TFileScanRangeParams scan_params;
+    const Columns payload_columns {projected_column("row_id", TYPE_BIGINT, false)};
+    LanceTableReader reader;
+    ASSERT_TRUE(init_reader(&reader, payload_columns, &state, &fetch_profile, &scan_params).ok());
+    Block block;
+    add_output_columns(&block, payload_columns);
+    const auto status = reader.read_by_row_ids(
+            make_lance_range(dataset_uri, 0, fixture.fragment_ids), {0}, &block);
+    ASSERT_FALSE(status.ok());
+    EXPECT_NE(status.to_string().find(
+                      "Lance row-id fetch requires a fixed positive dataset version, but got 0"),
+              std::string::npos)
+            << status.to_string();
+    EXPECT_TRUE(reader.close().ok());
+}
+
+TEST(LanceTableReaderSnapshotTest, ProfileShowsTheSnapshotRead) {
+    const std::filesystem::path dataset_uri =
+            "./be/test/format_v2/table/lance/data/all_types.lance";
+    LanceFixtureInfo fixture;
+    ASSERT_TRUE(get_fixture_info(dataset_uri, &fixture).ok());
+    TQueryGlobals query_globals;
+    RuntimeState state(query_globals);
+    RuntimeProfile profile("lance_snapshot_profile");
+    auto scan_params = make_float32_vector_search_params({0.0F, 0.0F, 0.0F}, 2, 0);
+    const Columns columns {projected_column("row_id", TYPE_BIGINT, false),
+                           projected_column("_distance", TYPE_FLOAT, true)};
+    LanceTableReader reader;
+    ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &scan_params).ok());
+    // A query string may carry credentials, so the profile leaves it out.
+    auto range = make_lance_range(dataset_uri, fixture.version, fixture.fragment_ids);
+    ASSERT_TRUE(prepare_range(&reader, range).ok());
+    const auto* version = profile.get_info_string("LanceDatasetVersion");
+    ASSERT_NE(nullptr, version);
+    EXPECT_EQ(std::to_string(fixture.version), *version);
+    const auto* uri = profile.get_info_string("LanceDatasetUri");
+    ASSERT_NE(nullptr, uri);
+    EXPECT_EQ(dataset_uri.string(), *uri);
+    EXPECT_TRUE(reader.close().ok());
+
+    // A scan of version 0 opens the latest version, and the profile shows which one that was.
+    RuntimeProfile latest_profile("lance_snapshot_profile_latest");
+    TFileScanRangeParams normal_params;
+    const Columns normal_columns {projected_column("row_id", TYPE_BIGINT, false)};
+    LanceTableReader latest_reader;
+    ASSERT_TRUE(init_reader(&latest_reader, normal_columns, &state, &latest_profile, &normal_params)
+                        .ok());
+    ASSERT_TRUE(prepare_range(&latest_reader, make_latest_lance_range(dataset_uri)).ok());
+    const auto* latest_version = latest_profile.get_info_string("LanceDatasetVersion");
+    ASSERT_NE(nullptr, latest_version);
+    EXPECT_EQ(std::to_string(fixture.version), *latest_version);
+    EXPECT_TRUE(latest_reader.close().ok());
+}
+
+TEST(LanceTableReaderSnapshotTest, OpenErrorsNameTheVersionWithoutTheQueryString) {
+    const std::filesystem::path dataset_uri =
+            "./be/test/format_v2/table/lance/data/all_types.lance";
+    LanceFixtureInfo fixture;
+    ASSERT_TRUE(get_fixture_info(dataset_uri, &fixture).ok());
+    TQueryGlobals query_globals;
+    RuntimeState state(query_globals);
+    RuntimeProfile profile("lance_open_error");
+    auto scan_params = make_float32_vector_search_params({0.0F, 0.0F, 0.0F}, 2, 0);
+    const Columns columns {projected_column("row_id", TYPE_BIGINT, false),
+                           projected_column("_distance", TYPE_FLOAT, true)};
+    LanceTableReader reader;
+    ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &scan_params).ok());
+    // The query string stands for credentials a URI may carry; Doris's own prefix leaves it out.
+    // What lance-c reports after the prefix is its own message.
+    auto range = make_lance_range(dataset_uri, 999, fixture.fragment_ids);
+    range.table_format_params.lance_params.__set_dataset_uri(dataset_uri.string() +
+                                                             "?secret=hidden");
+    const auto status = prepare_range(&reader, range);
+    ASSERT_FALSE(status.ok());
+    EXPECT_NE(
+            status.to_string().find("Lance dataset version 999 at " + dataset_uri.string() + ": "),
+            std::string::npos)
+            << status.to_string();
+    EXPECT_TRUE(reader.close().ok());
+}
+
+TEST(LanceTableReaderSnapshotTest, OpenErrorsShowTheUriWithoutItsPassword) {
+    // A password in the user information may carry a credential and is removed; a user part
+    // without a password stays, since Azure URIs name the container there. Lance parses a
+    // memory:// URI as a URL and names only the object path in its own error text, so the whole
+    // error must be free of the password and the query string. (A file:// URI with user
+    // information is not a valid URL; Lance would open it as a relative local path and echo it.)
+    TQueryGlobals query_globals;
+    RuntimeState state(query_globals);
+    const Columns columns {projected_column("row_id", TYPE_BIGINT, false),
+                           projected_column("_distance", TYPE_FLOAT, true)};
+    for (const auto& [uri, shown] : std::vector<std::pair<std::string, std::string>> {
+                 {"memory://doris:secret@localhost/open_error.lance?token=hidden",
+                  "memory://localhost/open_error.lance"},
+                 {"memory://container@localhost/open_error.lance?token=hidden",
+                  "memory://container@localhost/open_error.lance"}}) {
+        SCOPED_TRACE(uri);
+        RuntimeProfile profile("lance_open_error_uri");
+        auto scan_params = make_float32_vector_search_params({0.0F, 0.0F, 0.0F}, 2, 0);
+        LanceTableReader reader;
+        ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &scan_params).ok());
+        auto range = make_lance_range("open_error.lance", 999, {0});
+        range.table_format_params.lance_params.__set_dataset_uri(uri);
+        const auto status = prepare_range(&reader, range);
+        ASSERT_FALSE(status.ok());
+        const std::string message = status.to_string();
+        EXPECT_NE(message.find("Lance dataset version 999 at " + shown + ": "), std::string::npos)
+                << message;
+        EXPECT_EQ(message.find("secret"), std::string::npos) << message;
+        EXPECT_EQ(message.find("hidden"), std::string::npos) << message;
+        EXPECT_TRUE(reader.close().ok());
+    }
+}
+
 TEST(LanceTableReaderVectorSearchTest, MultiVectorTopOnePreservesPrecisionAndBatchIndependence) {
     const std::filesystem::path uri = "./be/test/format_v2/table/lance/data/multivector.lance";
     LanceFixtureInfo fixture;
@@ -1093,7 +1436,12 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorTopOnePreservesPrecisionAndBat
             RuntimeProfile profile("multi_vector_top_one");
             LanceTableReader reader;
             ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &params).ok());
-            ASSERT_TRUE(prepare_fixture(&reader, uri, fixture, fixture.fragment_ids).ok());
+            ASSERT_TRUE(prepare_range(&reader, indexed ? make_indexed_lance_range(
+                                                                 uri, fixture, fixture.fragment_ids,
+                                                                 "batch_vectors_idx")
+                                                       : make_lance_range(uri, fixture.version,
+                                                                          fixture.fragment_ids))
+                                .ok());
             Block block;
             add_output_columns(&block, columns);
             auto rows = read_vector_search_rows(&reader, &block);
@@ -1102,6 +1450,7 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorTopOnePreservesPrecisionAndBat
             EXPECT_NEAR(indexed ? 2.0F - std::sqrt(2.0F) : 1e-8F, rows[0].second,
                         indexed ? 1e-6F : 1e-13F);
             EXPECT_TRUE(reader.close().ok());
+            EXPECT_EQ(indexed, profile.get_counter("LanceIVFPartitionsSearched")->value() > 0);
         }
     }
 }
@@ -1136,7 +1485,12 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorCosineMasksUndefinedRows) {
             RuntimeProfile profile("multi_vector_cosine_zero_norm");
             LanceTableReader reader;
             ASSERT_TRUE(init_reader(&reader, columns, &state, &profile, &params).ok());
-            ASSERT_TRUE(prepare_fixture(&reader, uri, fixture, fixture.fragment_ids).ok());
+            ASSERT_TRUE(prepare_range(&reader, indexed ? make_indexed_lance_range(
+                                                                 uri, fixture, fixture.fragment_ids,
+                                                                 "vectors_idx")
+                                                       : make_lance_range(uri, fixture.version,
+                                                                          fixture.fragment_ids))
+                                .ok());
             Block block;
             add_output_columns(&block, columns);
             auto rows = read_vector_search_rows(&reader, &block);
@@ -1147,10 +1501,14 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorCosineMasksUndefinedRows) {
                                : std::vector<std::pair<int64_t, float>> {{2, 1}, {3, 1}};
             EXPECT_EQ(expected, rows);
             EXPECT_TRUE(reader.close().ok());
+            EXPECT_EQ(indexed, profile.get_counter("LanceIVFPartitionsSearched")->value() > 0);
         }
     }
 }
 
+// FE plans an omitted metric as L2, and this column's only index is cosine, so FE plans every split
+// flat. BE must then search flat too, with the same L2 metric in every split, although the request
+// allows indexes.
 TEST(LanceTableReaderVectorSearchTest, MultiVectorDefaultMetricIsConsistentAcrossFragments) {
     const std::filesystem::path uri = "./be/test/format_v2/table/lance/data/multivector.lance";
     LanceFixtureInfo fixture;
@@ -1183,6 +1541,7 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorDefaultMetricIsConsistentAcros
         auto rows = read_vector_search_rows(&reader, &block);
         all_rows.insert(all_rows.end(), rows.begin(), rows.end());
         EXPECT_TRUE(reader.close().ok());
+        EXPECT_EQ(0, profile.get_counter("LanceIVFPartitionsSearched")->value());
     }
     std::sort(all_rows.begin(), all_rows.end());
     EXPECT_EQ((std::vector<std::pair<int64_t, float>> {{1, 0}, {2, 1}, {3, 4}, {6, 1}}), all_rows);
@@ -1220,7 +1579,8 @@ TEST(LanceTableReaderVectorSearchTest, MultiVectorRejectsActualNullAndNonFiniteE
             bool eos = false;
             auto status = reader.get_block(&block, &eos);
             EXPECT_FALSE(status.ok());
-            EXPECT_NE(status.to_string().find("finite, non-null elements"), std::string::npos);
+            EXPECT_NE(status.to_string().find("finite, non-null elements"), std::string::npos)
+                    << status.to_string();
             EXPECT_TRUE(reader.close().ok());
         }
     }
diff --git a/docker/thirdparties/docker-compose/iceberg/iceberg.yaml.tpl b/docker/thirdparties/docker-compose/iceberg/iceberg.yaml.tpl
index 0ea1088377e..f2dddc0a319 100644
--- a/docker/thirdparties/docker-compose/iceberg/iceberg.yaml.tpl
+++ b/docker/thirdparties/docker-compose/iceberg/iceberg.yaml.tpl
@@ -118,11 +118,11 @@ services:
       - ./scripts/lance_rest_server.py:/opt/lance-rest/server.py:ro
     environment:
       LANCE_REST_BEARER_TOKEN: doris-lance-rest-test-token
-      LANCE_REST_TABLES_JSON: '{"all_types":"s3://warehouse/lance/all_types.lance","all_types_unprefixed":"s3://warehouse/lance/all_types.lance","time_travel":"s3://warehouse/lance/time_travel.lance"}'
+      LANCE_REST_TABLES_JSON: '{"all_types":"s3://warehouse/lance/all_types.lance","all_types_unprefixed":"s3://warehouse/lance/all_types.lance","time_travel":"s3://warehouse/lance/time_travel.lance","search_snapshot":"s3://warehouse/lance/search_snapshot.lance","search_snapshot_pruned":"s3://warehouse/lance/search_snapshot_pruned.lance"}'
       # all_types_unprefixed serves the same dataset but vends its credentials under the
       # unprefixed object-store spelling, which is what real namespace servers emit.
       LANCE_REST_UNPREFIXED_TABLES_JSON: '["all_types_unprefixed","time_travel_managed_unprefixed"]'
-      # All managed tables are the same three-version dataset; they differ in what the namespace
+      # The time_travel_managed tables are the same three-version dataset; they differ in what the namespace
       # records. A reader that resolves versions through the namespace cannot see a version
       # missing there even though its manifest is still in storage, and its latest version is
       # the namespace's latest, not storage's:
@@ -138,10 +138,17 @@ services:
       #                                   although its canonical one exists
       #   time_travel_managed_misrecorded every version, version 3 recorded at a manifest Doris
       #                                   does not read
-      # Versions and commit times (epoch millis, UTC) match the committed time_travel.lance,
-      # see lance_build_time_travel.py. Doris resolves FOR TIME AS OF from the manifests' commit
+      # The search_snapshot_managed tables serve search_snapshot.lance (seven versions, see
+      # lance_build_search_snapshot.py) to the search TVFs:
+      #   search_snapshot_managed         every version, with commit times, and branch dev
+      #                                   (versions 4 to 6 under tree/dev/)
+      #   search_snapshot_managed_partial every version but 6
+      # unicode_branch_managed serves unicode_branch.lance, whose branch dev\u1c89 has a letter newer
+      # than the JDK's Unicode tables (see lance_build_unicode_branch.py).
+      # Versions and commit times (epoch millis, UTC) match the committed time_travel.lance and
+      # search_snapshot.lance, see lance_build_time_travel.py and lance_build_search_snapshot.py. Doris resolves FOR TIME AS OF from the manifests' commit
       # times, so the reported ones are not what the time-travel results depend on.
-      LANCE_REST_MANAGED_TABLES_JSON: '{"time_travel_managed":{"uri":"s3://warehouse/lance/time_travel.lance","versions":[{"version":1,"timestamp_millis":1789823167597},{"version":2,"timestamp_millis":1789823169113},{"version":3,"timestamp_millis":1789823170621}],"branches":{"dev":{"versions":[2,3]}}},"time_travel_managed_partial":{"uri":"s3://warehouse/lance/time_travel.lance","versions":[{"version":1,"timestamp_millis":1789823167597},{"version":3,"timestamp_millis":1789823170621}]},"ti [...]
+      LANCE_REST_MANAGED_TABLES_JSON: '{"time_travel_managed":{"uri":"s3://warehouse/lance/time_travel.lance","versions":[{"version":1,"timestamp_millis":1789823167597},{"version":2,"timestamp_millis":1789823169113},{"version":3,"timestamp_millis":1789823170621}],"branches":{"dev":{"versions":[2,3]}}},"time_travel_managed_partial":{"uri":"s3://warehouse/lance/time_travel.lance","versions":[{"version":1,"timestamp_millis":1789823167597},{"version":3,"timestamp_millis":1789823170621}]},"ti [...]
       LANCE_S3_ACCESS_KEY: admin
       LANCE_S3_SECRET_KEY: password
       LANCE_S3_REGION: us-east-1
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_legacy_vector_index.py b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_legacy_vector_index.py
new file mode 100644
index 00000000000..7a91b2336de
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_legacy_vector_index.py
@@ -0,0 +1,100 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Generate the Lance legacy vector index regression fixture.
+
+legacy_vector_index.lance is a root table of the preinstalled Directory catalog next to
+time_travel.lance. Its vector index was written by pylance 0.18.2, which predates index details
+in the manifest, so no segment of vec_idx carries details:
+
+    version 1  create        row_id 1..512   fragment 0
+    version 2  vector index  vec_idx (IVF_PQ, l2, 2 partitions, 2 sub-vectors) over fragment 0
+
+vec = [row_id, row_id + 1, row_id + 2, row_id + 3] as float32. Lance infers the missing details
+from the index files when it loads the index, so the FE plans vec_idx like any other index and
+the BE searches it through the planned segment instead of falling back to a flat search.
+
+Build it with pylance 0.18.2, not the writer pinned in lance_fixture_requirements.txt; the
+catalog build carries it over as-is. --check runs with any reader.
+
+Usage:
+  pip install pylance==0.18.2 && python3 lance_build_legacy_vector_index.py preinstalled_data/lance
+  python3 lance_build_legacy_vector_index.py --check preinstalled_data/lance
+"""
+import argparse
+import shutil
+from pathlib import Path
+
+import lance
+import pyarrow as pa
+
+LEGACY_DIR = "legacy_vector_index.lance"
+WRITER_VERSION = "0.18.2"
+ROWS = 512
+DIMENSION = 4
+
+
+def build(output: Path) -> None:
+    if lance.__version__ != WRITER_VERSION:
+        raise SystemExit(f"build {LEGACY_DIR} with pylance {WRITER_VERSION}, not {lance.__version__}")
+    if output.exists():
+        shutil.rmtree(output)
+    ids = list(range(1, ROWS + 1))
+    table = pa.table({
+        "row_id": pa.array(ids, pa.int32()),
+        "vec": pa.array([[float(i + j) for j in range(DIMENSION)] for i in ids],
+                        pa.list_(pa.float32(), DIMENSION)),
+    })
+    uri = str(output)
+    lance.write_dataset(table, uri, mode="create")
+    lance.dataset(uri).create_index("vec", "IVF_PQ", name="vec_idx", metric="l2", num_partitions=2,
+                                    num_sub_vectors=2, sample_rate=256)
+    assert lance.dataset(uri).version == 2, lance.dataset(uri).version
+
+
+def check(output: Path) -> None:
+    dataset = lance.dataset(str(output))
+    assert [v["version"] for v in dataset.versions()] == [1, 2], dataset.versions()
+    row_ids = sorted(dataset.to_table(columns=["row_id"])["row_id"].to_pylist())
+    assert row_ids == list(range(1, ROWS + 1)), "rows differ"
+    indexes = dataset.list_indices()
+    assert [index["name"] for index in indexes] == ["vec_idx"], indexes
+    assert sorted(indexes[0]["fragment_ids"]) == [0], indexes
+    manifests = sorted((output / "_versions").glob("*.manifest"))
+    assert manifests, f"no manifest under {output / '_versions'}"
+    for manifest in manifests:
+        content = manifest.read_bytes()
+        assert b"VectorIndexDetails" not in content, f"{manifest} carries index details"
+        assert WRITER_VERSION.encode() in content, f"{manifest} was not written by pylance {WRITER_VERSION}"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("root", type=Path, help="directory holding the fixture")
+    parser.add_argument("--check", action="store_true", help="verify the existing fixture")
+    args = parser.parse_args()
+    if args.check:
+        check(args.root / LEGACY_DIR)
+    else:
+        build(args.root / LEGACY_DIR)
+        check(args.root / LEGACY_DIR)
+    print(f"{LEGACY_DIR} {'checked' if args.check else 'written'}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_preinstalled_catalog.py b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_preinstalled_catalog.py
index 2645e8748d8..d8652bf9ef8 100644
--- a/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_preinstalled_catalog.py
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_preinstalled_catalog.py
@@ -32,6 +32,20 @@ The generated catalog contains:
   - time_travel.lance     Three uncompacted versions for FOR VERSION / TIME AS OF; carried
                           over as-is because the suites hard-code its commit times
                           (see lance_build_time_travel.py).
+  - search_snapshot.lance, search_snapshot_pruned.lance
+                          Index history, tags and a branch for the search TVFs' snapshot
+                          selectors; carried over as-is for the same reason
+                          (see lance_build_search_snapshot.py).
+  - search_snapshot_evolved.lance
+                          A column added and renamed after the vector index; rebuilt, since
+                          no suite depends on its commit times.
+  - legacy_vector_index.lance
+                          A vector index written by pylance 0.18.2, without index details;
+                          carried over as-is because this writer cannot rebuild it
+                          (see lance_build_legacy_vector_index.py).
+  - unicode_branch.lance
+                          A branch named with a letter newer than the JDK's Unicode, written by
+                          pylance 12.0.0; carried over as-is (see lance_build_unicode_branch.py).
   - The `doris` namespace with two full-text-search fixtures, one indexed vector table per cell of the
     algorithm x element type x metric matrix (hash-prefixed directories), listed in
     VECTOR_TABLES below; BREADTH_TABLE, one table carrying the remaining cells at plan
@@ -90,9 +104,20 @@ import lance_namespace
 import pyarrow as pa
 import pyarrow.ipc as ipc
 from lance_build_array_predicates import build as build_array_predicates, check as check_array_predicates
+from lance_build_legacy_vector_index import LEGACY_DIR as LEGACY_VECTOR_INDEX_DIR
+from lance_build_legacy_vector_index import check as check_legacy_vector_index
 from lance_build_multivector import build as build_multivector, check as check_multivector
 from lance_build_nested_null import build as build_nested_null, check as check_nested_null
+from lance_build_search_snapshot import (
+    EVOLVED_DIR as SEARCH_SNAPSHOT_EVOLVED_DIR,
+    MAIN_DIR as SEARCH_SNAPSHOT_DIR,
+    PRUNED_DIR as SEARCH_SNAPSHOT_PRUNED_DIR,
+    build_evolved as build_search_snapshot_evolved,
+    check as check_search_snapshot,
+)
 from lance_build_time_travel import check as check_time_travel
+from lance_build_unicode_branch import UNICODE_BRANCH_DIR
+from lance_build_unicode_branch import check as check_unicode_branch
 from lance_namespace_urllib3_client.models import (
     CreateNamespaceRequest,
     CreateTableRequest,
@@ -937,10 +962,13 @@ def build_multi_frag(root: Path) -> None:
     lance.dataset(location).delete(f"row_id in ({deleted})")
 
 
-def build(root: Path, all_types_source: Path, time_travel_source: Path) -> None:
+def build(root: Path, all_types_source: Path, time_travel_source: Path, carried_root: Path) -> None:
     shutil.copytree(all_types_source, root / ALL_TYPES_DIR)
-    # Not rebuilt: its commit times are hard-coded in the time-travel suites.
+    # Not rebuilt: their commit times are hard-coded in the time-travel and search-snapshot suites.
     shutil.copytree(time_travel_source, root / TIME_TRAVEL_DIR)
+    for name in (SEARCH_SNAPSHOT_DIR, SEARCH_SNAPSHOT_PRUNED_DIR, LEGACY_VECTOR_INDEX_DIR, UNICODE_BRANCH_DIR):
+        shutil.copytree(carried_root / name, root / name)
+    build_search_snapshot_evolved(root / SEARCH_SNAPSHOT_EVOLVED_DIR)
     build_multi_frag(root)
     # Recreate this fixture in staging because promotion replaces the entire catalog tree.
     build_nested_null(root / NESTED_NULL_DIR)
@@ -1737,6 +1765,9 @@ def check_catalog(root: Path) -> None:
     check_multi_frag(root)
     check_nested_null(root / NESTED_NULL_DIR)
     check_time_travel(root / TIME_TRAVEL_DIR)
+    check_search_snapshot(root)
+    check_legacy_vector_index(root / LEGACY_VECTOR_INDEX_DIR)
+    check_unicode_branch(root / UNICODE_BRANCH_DIR)
     check_multivector(root / "multivector.lance")
 
     full_fts = namespace.describe_table(DescribeTableRequest(id=[NAMESPACE, FTS_TABLE]))
@@ -1808,11 +1839,15 @@ def main() -> int:
     if not time_travel_source.is_dir():
         print(f"missing time_travel source: {time_travel_source}", file=sys.stderr)
         return 1
+    for name in (SEARCH_SNAPSHOT_DIR, SEARCH_SNAPSHOT_PRUNED_DIR, LEGACY_VECTOR_INDEX_DIR, UNICODE_BRANCH_DIR):
+        if not (output / name).is_dir():
+            print(f"missing carried-over source: {output / name}", file=sys.stderr)
+            return 1
 
     with tempfile.TemporaryDirectory(prefix="lance_fixture_") as staging_name:
         staging = Path(staging_name) / "lance"
         staging.mkdir()
-        build(staging, all_types_source, time_travel_source)
+        build(staging, all_types_source, time_travel_source, output)
         build_array_predicates(staging / "predicate_arrays")
         check_catalog(staging)
         backup = output.with_name(output.name + ".old")
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_search_snapshot.py b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_search_snapshot.py
new file mode 100644
index 00000000000..24d056ec995
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_search_snapshot.py
@@ -0,0 +1,329 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Generate the Lance search-snapshot regression fixtures.
+
+search_snapshot.lance, search_snapshot_pruned.lance and search_snapshot_evolved.lance are root
+tables of the preinstalled Directory catalog next to time_travel.lance. They exercise
+vector_search() and full_text_search() with the version, timestamp, tag and branch properties,
+so they keep an uncompacted history in which indexes appear, stop covering new data, are
+rebuilt, and outlive schema changes.
+
+search_snapshot.lance, main chain:
+
+    version 1  create        row_id 1..8    fragment 0
+    version 2  append        row_id 9..16   fragment 1
+    version 3  vector index  vec_idx (IVF_FLAT, l2) over fragments 0 and 1
+    version 4  FTS index     body_idx over fragments 0 and 1
+    version 5  append        row_id 17..24  fragment 2, covered by neither index
+    version 6  delete        row_id 3 and 11
+    version 7  vector index  vec_idx rebuilt over all fragments (a new index UUID)
+
+Tag "rel" points at main version 5. Branch "dev" forks from version 4:
+
+    dev version 5  append     row_id 101..108  fragment 2 (the same id as main's fragment 2)
+    dev version 6  FTS index  body_idx rebuilt over all fragments, stored under tree/dev/
+
+Tag "dev_rel" points at dev version 5, which is not the branch's latest version. So main and
+dev both have versions 5 and 6 and a fragment 2, with different rows and indexes.
+
+Every row has vec = [row_id, row_id + 1, row_id + 2, row_id + 3] as float32, so the exact
+squared L2 distance between rows r and n is 4 * (n - r)^2, and body = "doc <row_id> <word>"
+with <word> "lance" for even row_ids and "doris" for odd ones. The vector index has two IVF
+partitions; the suites search with nprobes=2, which makes IVF_FLAT exact, so indexed and flat
+searches return the same rows.
+
+search_snapshot_pruned.lance keeps what cleanup leaves behind:
+
+    version 1  create        row_id 1..8, removed by cleanup
+    version 2  vector index  vec_idx, pinned by tag "kept"; its index files are then deleted
+    version 3  vector index  vec_idx rebuilt
+
+so version 1 is missing, and version 2 opens but its index files are gone.
+
+search_snapshot_evolved.lance changes its schema after the vector index is built:
+
+    version 1  create        row_id 1..8    fragment 0
+    version 2  vector index  vec_idx over fragment 0
+    version 3  add column    note = "note <row_id>"
+    version 4  rename        vec -> embedding (same field id, so vec_idx still serves it)
+    version 5  append        row_id 9..16   fragment 1, not covered by vec_idx
+
+so a search must bind the column names, the index and the fragments of the version it reads.
+
+A Lance branch is a shallow clone that records its parent's absolute URI, so the branch was
+created against the fixture's final location s3://warehouse/lance/search_snapshot.lance (see
+lance_build_time_travel.py for the same procedure):
+
+  python3 lance_build_search_snapshot.py preinstalled_data/lance
+  # upload search_snapshot.lance to s3://warehouse/lance/search_snapshot.lance
+  python3 lance_build_search_snapshot.py --create-branch s3://warehouse/lance/search_snapshot.lance \
+      --storage-option endpoint=http://127.0.0.1:19000 --storage-option access_key_id=admin \
+      --storage-option secret_access_key=password --storage-option region=us-east-1 \
+      --storage-option allow_http=true
+  # then sync tree/, _refs/branches/ and _refs/tags/ from that location back
+
+The suites hard-code the commit times this script prints, as the time-travel suites do.
+Run it with the writer pinned in lance_fixture_requirements.txt.
+
+Usage:
+  python3 lance_build_search_snapshot.py preinstalled_data/lance
+  python3 lance_build_search_snapshot.py --fixture evolved preinstalled_data/lance
+  python3 lance_build_search_snapshot.py --check preinstalled_data/lance
+
+--fixture limits a build to some of the fixtures. Rebuilding search_snapshot.lance changes the
+commit times the suites hard-code and requires recreating its branch.
+"""
+import argparse
+import shutil
+import time
+from datetime import timedelta
+from pathlib import Path
+
+import lance
+import pyarrow as pa
+
+MAIN_DIR = "search_snapshot.lance"
+PRUNED_DIR = "search_snapshot_pruned.lance"
+EVOLVED_DIR = "search_snapshot_evolved.lance"
+BRANCH = "dev"
+BRANCH_PARENT_URI = "s3://warehouse/lance/search_snapshot.lance"
+DIMENSION = 4
+COMMIT_GAP_SECONDS = 1.5
+FTS_INDEX_PARAMS = {
+    "base_tokenizer": "simple",
+    "language": "English",
+    "max_token_length": 40,
+    "lower_case": True,
+    "stem": False,
+    "remove_stop_words": False,
+    "ascii_folding": False,
+    "with_position": True,
+}
+
+
+def rows_of(low: int, high: int) -> pa.Table:
+    ids = list(range(low, high + 1))
+    vectors = [[float(i + j) for j in range(DIMENSION)] for i in ids]
+    return pa.table({
+        "row_id": pa.array(ids, pa.int32()),
+        "vec": pa.array(vectors, pa.list_(pa.float32(), DIMENSION)),
+        "body": pa.array([f"doc {i} {'lance' if i % 2 == 0 else 'doris'}" for i in ids], pa.string()),
+    })
+
+
+def create_vector_index(dataset, replace: bool = False):
+    dataset.create_index("vec", "IVF_FLAT", name="vec_idx", metric="l2", num_partitions=2,
+                         sample_rate=256, replace=replace)
+
+
+def create_fts_index(dataset, replace: bool = False):
+    dataset.create_scalar_index("body", "INVERTED", name="body_idx", replace=replace, **FTS_INDEX_PARAMS)
+
+
+def pause() -> None:
+    time.sleep(COMMIT_GAP_SECONDS)
+
+
+def build_main(output: Path) -> None:
+    if output.exists():
+        shutil.rmtree(output)
+    uri = str(output)
+    lance.write_dataset(rows_of(1, 8), uri, mode="create", data_storage_version="2.2")
+    pause()
+    lance.write_dataset(rows_of(9, 16), uri, mode="append", data_storage_version="2.2")
+    pause()
+    create_vector_index(lance.dataset(uri))
+    pause()
+    create_fts_index(lance.dataset(uri))
+    pause()
+    lance.write_dataset(rows_of(17, 24), uri, mode="append", data_storage_version="2.2")
+    pause()
+    lance.dataset(uri).delete("row_id IN (3, 11)")
+    pause()
+    create_vector_index(lance.dataset(uri), replace=True)
+    dataset = lance.dataset(uri)
+    assert dataset.version == 7, dataset.version
+    dataset.tags.create("rel", 5)
+
+
+def build_pruned(output: Path) -> None:
+    if output.exists():
+        shutil.rmtree(output)
+    uri = str(output)
+    lance.write_dataset(rows_of(1, 8), uri, mode="create", data_storage_version="2.2")
+    create_vector_index(lance.dataset(uri))
+    kept = lance.dataset(uri)
+    kept_index = {index["name"]: index["uuid"] for index in kept.list_indices()}["vec_idx"]
+    kept.tags.create("kept", 2)
+    create_vector_index(lance.dataset(uri), replace=True)
+    dataset = lance.dataset(uri)
+    # The tag keeps version 2 through cleanup, as a tagged release would be kept.
+    dataset.cleanup_old_versions(older_than=timedelta(0), delete_unverified=True,
+                                 error_if_tagged_old_versions=False)
+    shutil.rmtree(output / "_indices" / kept_index)
+    assert [v["version"] for v in lance.dataset(uri).versions()] == [2, 3]
+
+
+def evolved_rows(low: int, high: int, schema: pa.Schema) -> pa.Table:
+    rows = rows_of(low, high).rename_columns(["row_id", "embedding", "body"])
+    notes = pa.array([f"note {i}" for i in range(low, high + 1)], pa.string())
+    return rows.append_column("note", notes).cast(schema)
+
+
+def build_evolved(output: Path) -> None:
+    if output.exists():
+        shutil.rmtree(output)
+    uri = str(output)
+    lance.write_dataset(rows_of(1, 8), uri, mode="create", data_storage_version="2.2")
+    create_vector_index(lance.dataset(uri))
+    lance.dataset(uri).add_columns({"note": "concat('note ', CAST(row_id AS STRING))"})
+    lance.dataset(uri).alter_columns({"path": "vec", "name": "embedding"})
+    renamed = lance.dataset(uri)
+    lance.write_dataset(evolved_rows(9, 16, renamed.schema), uri, mode="append", data_storage_version="2.2")
+    assert lance.dataset(uri).version == 5, lance.dataset(uri).version
+
+
+FIXTURES = {"main": (MAIN_DIR, build_main), "pruned": (PRUNED_DIR, build_pruned),
+            "evolved": (EVOLVED_DIR, build_evolved)}
+
+
+def build(root: Path, fixtures: list) -> None:
+    for name in fixtures:
+        directory, builder = FIXTURES[name]
+        builder(root / directory)
+        print(f"{directory} written")
+    if "main" in fixtures:
+        print(f"create the branch with --create-branch {BRANCH_PARENT_URI}")
+
+
+def create_branch(uri: str, storage_options: dict) -> None:
+    """Forks dev at the dataset's final location, appends to it and rebuilds its FTS index there."""
+    dataset = lance.dataset(uri, storage_options=storage_options)
+    assert dataset.version == 7, "upload the main chain first"
+    dataset.create_branch(BRANCH, 4)
+    branch_uri = f"{uri}/tree/{BRANCH}"
+    pause()
+    lance.write_dataset(rows_of(101, 108), branch_uri, mode="append", data_storage_version="2.2",
+                        storage_options=storage_options)
+    pause()
+    create_fts_index(lance.dataset(branch_uri, storage_options=storage_options), replace=True)
+    branch = lance.dataset(branch_uri, storage_options=storage_options)
+    assert branch.version == 6, branch.version
+    dataset.tags.create("dev_rel", (BRANCH, 5))
+    print(f"branch {BRANCH} and tag dev_rel created at {uri}; sync tree/, _refs/branches/ and _refs/tags/ back")
+
+
+def row_ids(dataset) -> list:
+    return sorted(dataset.to_table(columns=["row_id"])["row_id"].to_pylist())
+
+
+def check(root: Path) -> None:
+    output = root / MAIN_DIR
+    dataset = lance.dataset(str(output))
+    versions = dataset.versions()
+    assert [v["version"] for v in versions] == list(range(1, 8)), versions
+    timestamps = [v["timestamp"] for v in versions]
+    assert all((b - a).total_seconds() >= 1 for a, b in zip(timestamps, timestamps[1:])), timestamps
+    expected_rows = {
+        1: list(range(1, 9)), 2: list(range(1, 17)), 3: list(range(1, 17)), 4: list(range(1, 17)),
+        5: list(range(1, 25)), 6: [i for i in range(1, 25) if i not in (3, 11)],
+        7: [i for i in range(1, 25) if i not in (3, 11)],
+    }
+    indexes = {}
+    for version, rows in expected_rows.items():
+        snapshot = dataset.checkout_version(version)
+        assert row_ids(snapshot) == rows, f"version {version} rows differ"
+        indexes[version] = {index["name"]: (index["uuid"], sorted(index["fragment_ids"]))
+                             for index in snapshot.list_indices()}
+    assert indexes[2] == {}
+    assert set(indexes[3]) == {"vec_idx"} and indexes[3]["vec_idx"][1] == [0, 1]
+    assert set(indexes[4]) == {"vec_idx", "body_idx"} and indexes[4]["body_idx"][1] == [0, 1]
+    assert indexes[5] == indexes[4] and indexes[6]["vec_idx"] == indexes[4]["vec_idx"]
+    assert indexes[7]["vec_idx"][0] != indexes[6]["vec_idx"][0], "version 7 must rebuild vec_idx"
+    assert indexes[7]["vec_idx"][1] == [0, 1, 2]
+    tags = {name: (ref["branch"], ref["version"]) for name, ref in dataset.tags.list().items()}
+    assert tags == {"rel": (None, 5), "dev_rel": (BRANCH, 5)}, tags
+    assert list(dataset.branches.list()) == [BRANCH], dataset.branches.list()
+    branch_manifests = sorted((output / "tree" / BRANCH / "_versions").glob("*.manifest"))
+    assert len(branch_manifests) == 3, f"branch {BRANCH} must carry versions 4 to 6: {branch_manifests}"
+    for manifest in branch_manifests:
+        assert BRANCH_PARENT_URI.encode() in manifest.read_bytes(), (
+            f"{manifest} must reference the parent at {BRANCH_PARENT_URI}")
+    assert (output / "tree" / BRANCH / "_indices").is_dir(), "dev must hold its rebuilt FTS index"
+
+    pruned = lance.dataset(str(root / PRUNED_DIR))
+    assert [v["version"] for v in pruned.versions()] == [2, 3], pruned.versions()
+    kept = pruned.checkout_version(2)
+    kept_index = kept.list_indices()[0]["uuid"]
+    assert not (root / PRUNED_DIR / "_indices" / kept_index).exists(), "version 2 index files must be gone"
+    assert (root / PRUNED_DIR / "_indices" / pruned.list_indices()[0]["uuid"]).is_dir()
+    check_evolved(root / EVOLVED_DIR)
+    for version in versions:
+        print(f"{MAIN_DIR} version {version['version']} committed at {version['timestamp'].isoformat()}")
+
+
+def check_evolved(output: Path) -> None:
+    dataset = lance.dataset(str(output))
+    assert [v["version"] for v in dataset.versions()] == list(range(1, 6)), dataset.versions()
+    expected_columns = {
+        1: ["row_id", "vec", "body"], 2: ["row_id", "vec", "body"], 3: ["row_id", "vec", "body", "note"],
+        4: ["row_id", "embedding", "body", "note"], 5: ["row_id", "embedding", "body", "note"],
+    }
+    index_uuids = set()
+    for version, columns in expected_columns.items():
+        snapshot = dataset.checkout_version(version)
+        assert snapshot.schema.names == columns, f"version {version} columns {snapshot.schema.names}"
+        rows = list(range(1, 17)) if version == 5 else list(range(1, 9))
+        assert row_ids(snapshot) == rows, f"version {version} rows differ"
+        indexes = snapshot.list_indices()
+        if version == 1:
+            assert indexes == [], indexes
+            continue
+        assert [index["name"] for index in indexes] == ["vec_idx"], indexes
+        assert sorted(indexes[0]["fragment_ids"]) == [0], indexes
+        index_uuids.add(indexes[0]["uuid"])
+    assert len(index_uuids) == 1, f"the rename must keep vec_idx: {index_uuids}"
+    notes = dataset.checkout_version(3).to_table(columns=["row_id", "note"]).to_pylist()
+    assert all(row["note"] == f"note {row['row_id']}" for row in notes), notes
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("root", type=Path, nargs="?",
+                        help="directory holding the fixtures (not used with --create-branch)")
+    parser.add_argument("--check", action="store_true", help="verify the existing fixtures")
+    parser.add_argument("--fixture", action="append", choices=sorted(FIXTURES), metavar="NAME",
+                        help="build only this fixture (repeatable): " + ", ".join(sorted(FIXTURES)))
+    parser.add_argument("--create-branch", metavar="URI",
+                        help="create the dev branch at the uploaded dataset URI instead of building")
+    parser.add_argument("--storage-option", action="append", default=[], metavar="KEY=VALUE",
+                        help="Lance storage option for --create-branch (repeatable)")
+    args = parser.parse_args()
+    if not args.create_branch and args.root is None:
+        parser.error("the fixture directory is required unless --create-branch is given")
+    if args.create_branch:
+        create_branch(args.create_branch, dict(item.split("=", 1) for item in args.storage_option))
+    elif args.check:
+        check(args.root)
+    else:
+        build(args.root, args.fixture or list(FIXTURES))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_unicode_branch.py b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_unicode_branch.py
new file mode 100644
index 00000000000..1179ddbe6a9
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/lance_build_unicode_branch.py
@@ -0,0 +1,135 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Generate the Lance regression fixture whose branch name is newer than the JDK's Unicode.
+
+unicode_branch.lance is a root table of the preinstalled Directory catalog next to
+time_travel.lance. Its branch is named "dev\\u1c89": U+1C89 was added in Unicode 16, so Lance's
+Rust validation accepts it while JDK 17, on Unicode 13, leaves it unassigned. The REST server
+serves the table as unicode_branch_managed, so Doris opens the branch by the URI it joins.
+
+    version 1          create  row_id 1..8      fragment 0
+    dev\\u1c89 version 2  append  row_id 201..204  on the branch only
+
+vec = [row_id, row_id + 1, row_id + 2, row_id + 3] as float32, body = "doc <row_id>".
+
+A Lance branch is a shallow clone that records its parent's absolute URI, so the branch is
+created against the fixture's final location (see lance_build_search_snapshot.py):
+
+  python3 lance_build_unicode_branch.py preinstalled_data/lance
+  # upload unicode_branch.lance to s3://warehouse/lance/unicode_branch.lance
+  python3 lance_build_unicode_branch.py --create-branch s3://warehouse/lance/unicode_branch.lance \\
+      --storage-option endpoint=http://127.0.0.1:19000 --storage-option access_key_id=admin \\
+      --storage-option secret_access_key=password --storage-option region=us-east-1 \\
+      --storage-option allow_http=true
+  # then sync tree/ and _refs/branches/ from that location back
+  python3 lance_build_unicode_branch.py --check preinstalled_data/lance
+
+Build it with pylance 12.0.0, the Lance the FE uses, not the writer pinned in
+lance_fixture_requirements.txt: Lance 7 stores a non-ASCII branch directory percent-encoded
+(tree/dev%E1%B2%89/), which Lance 12 does not find, while Lance 12 stores it as tree/dev\u1c89/.
+The catalog build carries the fixture over as-is. --check runs with any reader.
+"""
+import argparse
+import shutil
+from pathlib import Path
+
+import lance
+import pyarrow as pa
+
+UNICODE_BRANCH_DIR = "unicode_branch.lance"
+BRANCH = "devᲉ"
+PARENT_URI = "s3://warehouse/lance/unicode_branch.lance"
+WRITER_VERSION = "12.0.0"
+DIMENSION = 4
+
+
+def rows_of(low: int, high: int) -> pa.Table:
+    ids = list(range(low, high + 1))
+    return pa.table({
+        "row_id": pa.array(ids, pa.int32()),
+        "vec": pa.array([[float(i + j) for j in range(DIMENSION)] for i in ids],
+                        pa.list_(pa.float32(), DIMENSION)),
+        "body": pa.array([f"doc {i}" for i in ids], pa.string()),
+    })
+
+
+def require_writer() -> None:
+    if lance.__version__ != WRITER_VERSION:
+        raise SystemExit(f"build {UNICODE_BRANCH_DIR} with pylance {WRITER_VERSION}, not {lance.__version__}")
+
+
+def build(output: Path) -> None:
+    require_writer()
+    if output.exists():
+        shutil.rmtree(output)
+    lance.write_dataset(rows_of(1, 8), str(output), mode="create", data_storage_version="2.2")
+    print(f"{UNICODE_BRANCH_DIR} written; create the branch with --create-branch {PARENT_URI}")
+
+
+def create_branch(uri: str, storage_options: dict) -> None:
+    require_writer()
+    dataset = lance.dataset(uri, storage_options=storage_options)
+    assert dataset.version == 1, "upload the main chain first"
+    dataset.create_branch(BRANCH, 1)
+    lance.write_dataset(rows_of(201, 204), f"{uri}/tree/{BRANCH}", mode="append",
+                        data_storage_version="2.2", storage_options=storage_options)
+    branch = lance.dataset(f"{uri}/tree/{BRANCH}", storage_options=storage_options)
+    assert branch.version == 2, branch.version
+    print(f"branch {BRANCH!r} created at {uri}; sync tree/ and _refs/branches/ back")
+
+
+def row_ids(dataset) -> list:
+    return sorted(dataset.to_table(columns=["row_id"])["row_id"].to_pylist())
+
+
+def check(output: Path) -> None:
+    dataset = lance.dataset(str(output))
+    assert [v["version"] for v in dataset.versions()] == [1], dataset.versions()
+    assert row_ids(dataset) == list(range(1, 9)), "main rows differ"
+    assert list(dataset.branches.list()) == [BRANCH], dataset.branches.list()
+    # The branch directory keeps the name as is; Lance 12 does not find a percent-encoded one.
+    manifests = sorted((output / "tree" / BRANCH / "_versions").glob("*.manifest"))
+    assert len(manifests) == 2, f"branch {BRANCH!r} must carry versions 1 and 2: {manifests}"
+    for manifest in manifests:
+        assert PARENT_URI.encode() in manifest.read_bytes(), f"{manifest} must reference {PARENT_URI}"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("root", type=Path, nargs="?",
+                        help="directory holding the fixture (not used with --create-branch)")
+    parser.add_argument("--check", action="store_true", help="verify the existing fixture")
+    parser.add_argument("--create-branch", metavar="URI",
+                        help="create the branch at the uploaded dataset URI instead of building")
+    parser.add_argument("--storage-option", action="append", default=[], metavar="KEY=VALUE",
+                        help="Lance storage option for --create-branch (repeatable)")
+    args = parser.parse_args()
+    if not args.create_branch and args.root is None:
+        parser.error("the fixture directory is required unless --create-branch is given")
+    if args.create_branch:
+        create_branch(args.create_branch, dict(item.split("=", 1) for item in args.storage_option))
+    elif args.check:
+        check(args.root / UNICODE_BRANCH_DIR)
+        print(f"{UNICODE_BRANCH_DIR} checked")
+    else:
+        build(args.root / UNICODE_BRANCH_DIR)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/lance_fixture_requirements.txt b/docker/thirdparties/docker-compose/iceberg/scripts/lance_fixture_requirements.txt
index 1af5d1305b2..c34326bdc43 100644
--- a/docker/thirdparties/docker-compose/iceberg/scripts/lance_fixture_requirements.txt
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/lance_fixture_requirements.txt
@@ -38,6 +38,12 @@
 # it: the Spark and REST catalog suites read and register into the same __manifest this
 # writer produces, and they must pass for a fixture rebuild to be acceptable.
 #
+# One fixture is the exception: legacy_vector_index.lance must carry a vector index without
+# index details, which only writers before 0.20 produce, so lance_build_legacy_vector_index.py
+# builds it with pylance 0.18.2 and the catalog build carries it over as-is. Likewise
+# unicode_branch.lance is built by pylance 12.0.0, because Lance 7 stores a non-ASCII branch
+# directory percent-encoded, which Lance 12 does not find (see lance_build_unicode_branch.py).
+#
 # The pylance and lance-namespace pins are enforced rather than advisory:
 # check_pinned_writer() refuses to build or verify the fixture unless the installed versions
 # match them exactly. That check has to exist because the generator's own self-check cannot
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_indices/bc324f21-a15a-45bf-8d9e-09538f895f55/index.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_indices/bc324f21-a15a-45bf-8d9e-09538f895f55/index.idx
new file mode 100644
index 00000000000..ea4702c7d12
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_indices/bc324f21-a15a-45bf-8d9e-09538f895f55/index.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_transactions/0-c5e3be90-3de0-44fb-95b1-bd46928ae0f2.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_transactions/0-c5e3be90-3de0-44fb-95b1-bd46928ae0f2.txn
new file mode 100644
index 00000000000..c0c2ee59368
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_transactions/0-c5e3be90-3de0-44fb-95b1-bd46928ae0f2.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_transactions/1-9c8d1a85-5125-46ad-aeb8-8370bba30617.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_transactions/1-9c8d1a85-5125-46ad-aeb8-8370bba30617.txn
new file mode 100644
index 00000000000..ef6ab8a790c
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_transactions/1-9c8d1a85-5125-46ad-aeb8-8370bba30617.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_versions/1.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_versions/1.manifest
new file mode 100644
index 00000000000..3944e308416
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_versions/1.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_versions/2.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_versions/2.manifest
new file mode 100644
index 00000000000..097654588b9
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/_versions/2.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/data/02cdc0ff-ceee-44ef-bccd-6cb6f4b50779.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/data/02cdc0ff-ceee-44ef-bccd-6cb6f4b50779.lance
new file mode 100644
index 00000000000..045bba3e716
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/legacy_vector_index.lance/data/02cdc0ff-ceee-44ef-bccd-6cb6f4b50779.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_deletions/0-5-1267712482458982649.arrow b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_deletions/0-5-1267712482458982649.arrow
new file mode 100644
index 00000000000..6ea56a96b0a
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_deletions/0-5-1267712482458982649.arrow differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_deletions/1-5-6394601565774866848.arrow b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_deletions/1-5-6394601565774866848.arrow
new file mode 100644
index 00000000000..6ea56a96b0a
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_deletions/1-5-6394601565774866848.arrow differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/85880db4-716d-49b3-8eb2-fdadcc900e25/auxiliary.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/85880db4-716d-49b3-8eb2-fdadcc900e25/auxiliary.idx
new file mode 100644
index 00000000000..4b1580b5878
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/85880db4-716d-49b3-8eb2-fdadcc900e25/auxiliary.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/85880db4-716d-49b3-8eb2-fdadcc900e25/index.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/85880db4-716d-49b3-8eb2-fdadcc900e25/index.idx
new file mode 100644
index 00000000000..36be1299145
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/85880db4-716d-49b3-8eb2-fdadcc900e25/index.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/984593f1-89f1-4849-83f9-d3e45462c244/auxiliary.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/984593f1-89f1-4849-83f9-d3e45462c244/auxiliary.idx
new file mode 100644
index 00000000000..10b801b0027
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/984593f1-89f1-4849-83f9-d3e45462c244/auxiliary.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/984593f1-89f1-4849-83f9-d3e45462c244/index.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/984593f1-89f1-4849-83f9-d3e45462c244/index.idx
new file mode 100644
index 00000000000..8c40d51cd61
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/984593f1-89f1-4849-83f9-d3e45462c244/index.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/metadata.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/metadata.lance
new file mode 100644
index 00000000000..e0a664930f8
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/metadata.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_docs.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_docs.lance
new file mode 100644
index 00000000000..48baff15562
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_docs.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_invert.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_invert.lance
new file mode 100644
index 00000000000..b237ff0ec65
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_invert.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_tokens.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_tokens.lance
new file mode 100644
index 00000000000..9c5d074382f
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_indices/b1fd3eca-c523-401e-88cd-d4afa9b66ecf/part_0_tokens.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/branches/dev.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/branches/dev.json
new file mode 100644
index 00000000000..f816ab17d80
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/branches/dev.json
@@ -0,0 +1,15 @@
+{
+  "parentBranch": null,
+  "identifier": {
+    "version_mapping": [
+      [
+        4,
+        "db8ce527ff5c415b9a220a4a54108997"
+      ]
+    ]
+  },
+  "parentVersion": 4,
+  "createAt": 1790693536,
+  "manifestSize": 1244,
+  "metadata": {}
+}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/tags/dev_rel.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/tags/dev_rel.json
new file mode 100644
index 00000000000..c43136173a5
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/tags/dev_rel.json
@@ -0,0 +1,8 @@
+{
+  "branch": "dev",
+  "version": 5,
+  "createdAt": "2026-09-29T14:52:19.682676Z",
+  "updatedAt": "2026-09-29T14:52:19.682676Z",
+  "manifestSize": 1240,
+  "metadata": {}
+}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/tags/rel.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/tags/rel.json
new file mode 100644
index 00000000000..cbb50015fba
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_refs/tags/rel.json
@@ -0,0 +1,8 @@
+{
+  "branch": null,
+  "version": 5,
+  "createdAt": "2026-09-29T14:52:00.568051Z",
+  "updatedAt": "2026-09-29T14:52:00.568051Z",
+  "manifestSize": 1173,
+  "metadata": {}
+}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/0-154ed129-09cd-48de-89ac-618fc1060501.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/0-154ed129-09cd-48de-89ac-618fc1060501.txn
new file mode 100644
index 00000000000..9c20aecce08
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/0-154ed129-09cd-48de-89ac-618fc1060501.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/1-d6645060-096c-4335-8bd9-c595a08fdd34.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/1-d6645060-096c-4335-8bd9-c595a08fdd34.txn
new file mode 100644
index 00000000000..a2b7fb63746
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/1-d6645060-096c-4335-8bd9-c595a08fdd34.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/2-1518405c-5551-4e8f-b615-a0ca0d754255.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/2-1518405c-5551-4e8f-b615-a0ca0d754255.txn
new file mode 100644
index 00000000000..94c30ead7c7
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/2-1518405c-5551-4e8f-b615-a0ca0d754255.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/3-c7c138f8-03a8-4564-9fc5-d59c25c2223c.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/3-c7c138f8-03a8-4564-9fc5-d59c25c2223c.txn
new file mode 100644
index 00000000000..875089678d8
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/3-c7c138f8-03a8-4564-9fc5-d59c25c2223c.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/4-1cbab51a-2c2d-41c4-8025-30daa3cc11a4.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/4-1cbab51a-2c2d-41c4-8025-30daa3cc11a4.txn
new file mode 100644
index 00000000000..4b36ae8725a
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/4-1cbab51a-2c2d-41c4-8025-30daa3cc11a4.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/5-630bd020-d3af-4be8-b5e8-33388c068adc.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/5-630bd020-d3af-4be8-b5e8-33388c068adc.txn
new file mode 100644
index 00000000000..0f22d17e335
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/5-630bd020-d3af-4be8-b5e8-33388c068adc.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/6-9a8f0e65-3b5d-49ac-b232-5990ddd60891.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/6-9a8f0e65-3b5d-49ac-b232-5990ddd60891.txn
new file mode 100644
index 00000000000..c9b01bd551f
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_transactions/6-9a8f0e65-3b5d-49ac-b232-5990ddd60891.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551608.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551608.manifest
new file mode 100644
index 00000000000..299a56d1934
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551608.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551609.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551609.manifest
new file mode 100644
index 00000000000..b39807e70dc
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551609.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551610.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551610.manifest
new file mode 100644
index 00000000000..8d1014ec813
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551610.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551611.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551611.manifest
new file mode 100644
index 00000000000..f7c56dcfe47
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551611.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551612.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551612.manifest
new file mode 100644
index 00000000000..69ae8b9f38b
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551612.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551613.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551613.manifest
new file mode 100644
index 00000000000..755c4a235a4
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551613.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551614.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551614.manifest
new file mode 100644
index 00000000000..895267a7b12
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/18446744073709551614.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/latest_version_hint.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/latest_version_hint.json
new file mode 100644
index 00000000000..30a68a6c522
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/_versions/latest_version_hint.json
@@ -0,0 +1 @@
+{"version":7}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/01110111111110000001111167198a47f9880a55a8085ebb87.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/01110111111110000001111167198a47f9880a55a8085ebb87.lance
new file mode 100644
index 00000000000..a529fba94ea
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/01110111111110000001111167198a47f9880a55a8085ebb87.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/110001100010111000101110284ca44e90bfc0c56be666a32f.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/110001100010111000101110284ca44e90bfc0c56be666a32f.lance
new file mode 100644
index 00000000000..a6688314a69
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/110001100010111000101110284ca44e90bfc0c56be666a32f.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/110100000111011110010100fc3e5d485e9c40f5a217eaa59e.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/110100000111011110010100fc3e5d485e9c40f5a217eaa59e.lance
new file mode 100644
index 00000000000..4f18f971545
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/data/110100000111011110010100fc3e5d485e9c40f5a217eaa59e.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/metadata.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/metadata.lance
new file mode 100644
index 00000000000..c2703a12343
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/metadata.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_docs.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_docs.lance
new file mode 100644
index 00000000000..8199b4ab560
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_docs.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_invert.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_invert.lance
new file mode 100644
index 00000000000..eda931361ee
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_invert.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_tokens.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_tokens.lance
new file mode 100644
index 00000000000..3ae795448b3
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_indices/9821abbf-c51c-4c59-a184-756342a17365/part_0_tokens.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/4-a99a47e7-aae1-46cf-87f7-4cc649db3aa1.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/4-a99a47e7-aae1-46cf-87f7-4cc649db3aa1.txn
new file mode 100644
index 00000000000..0a82e1c17e9
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/4-a99a47e7-aae1-46cf-87f7-4cc649db3aa1.txn
@@ -0,0 +1 @@
+$a99a47e7-aae1-46cf-87f7-4cc649db3aa1�5"*s3://warehouse/lance/search_snapshot.lance*dev
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/4-d995fee3-982e-4e43-8e30-94537a9b0de2.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/4-d995fee3-982e-4e43-8e30-94537a9b0de2.txn
new file mode 100644
index 00000000000..24e59116138
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/4-d995fee3-982e-4e43-8e30-94537a9b0de2.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/5-6028c4ff-0a8e-4938-9d58-8a13524f6812.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/5-6028c4ff-0a8e-4938-9d58-8a13524f6812.txn
new file mode 100644
index 00000000000..bbc6a0a6fa7
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_transactions/5-6028c4ff-0a8e-4938-9d58-8a13524f6812.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551609.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551609.manifest
new file mode 100644
index 00000000000..3ffa94a28c8
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551609.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551610.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551610.manifest
new file mode 100644
index 00000000000..66430e475d2
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551610.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551611.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551611.manifest
new file mode 100644
index 00000000000..31a78e836d9
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/_versions/18446744073709551611.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/data/10010100101010111100101014250f4aa0a70d3d926f124125.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/data/10010100101010111100101014250f4aa0a70d3d926f124125.lance
new file mode 100644
index 00000000000..966c2a46db1
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot.lance/tree/dev/data/10010100101010111100101014250f4aa0a70d3d926f124125.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_indices/72e585d1-b843-4463-aba0-ffabc76017c1/auxiliary.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_indices/72e585d1-b843-4463-aba0-ffabc76017c1/auxiliary.idx
new file mode 100644
index 00000000000..80f7aa133f6
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_indices/72e585d1-b843-4463-aba0-ffabc76017c1/auxiliary.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_indices/72e585d1-b843-4463-aba0-ffabc76017c1/index.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_indices/72e585d1-b843-4463-aba0-ffabc76017c1/index.idx
new file mode 100644
index 00000000000..d544eb75b56
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_indices/72e585d1-b843-4463-aba0-ffabc76017c1/index.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/0-fecb1851-f6b0-496c-bfb8-f4dbe7f649f1.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/0-fecb1851-f6b0-496c-bfb8-f4dbe7f649f1.txn
new file mode 100644
index 00000000000..b954b2e1a06
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/0-fecb1851-f6b0-496c-bfb8-f4dbe7f649f1.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/1-5a98fef6-06a5-457c-b1b1-a9c830eafd2b.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/1-5a98fef6-06a5-457c-b1b1-a9c830eafd2b.txn
new file mode 100644
index 00000000000..e08d3999e36
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/1-5a98fef6-06a5-457c-b1b1-a9c830eafd2b.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/2-9bdddb95-2dc3-4e77-95b9-f67ed6e6387e.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/2-9bdddb95-2dc3-4e77-95b9-f67ed6e6387e.txn
new file mode 100644
index 00000000000..4292a1a52fc
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/2-9bdddb95-2dc3-4e77-95b9-f67ed6e6387e.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/3-954a5d41-5fc9-4e39-96d9-864e1ac233bc.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/3-954a5d41-5fc9-4e39-96d9-864e1ac233bc.txn
new file mode 100644
index 00000000000..1ba22c72ee6
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/3-954a5d41-5fc9-4e39-96d9-864e1ac233bc.txn
@@ -0,0 +1,5 @@
+$954a5d41-5fc9-4e39-96d9-864e1ac233bc��
+row_id ���������*int3208
+5	embedding ���������*fixed_size_list:float:408
+body ���������*string08
+note ���������*string08
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/4-a41517b8-29a3-410f-b3ae-768c33b38cf5.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/4-a41517b8-29a3-410f-b3ae-768c33b38cf5.txn
new file mode 100644
index 00000000000..d8b69c8d8d5
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_transactions/4-a41517b8-29a3-410f-b3ae-768c33b38cf5.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551610.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551610.manifest
new file mode 100644
index 00000000000..1be033e54a6
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551610.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551611.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551611.manifest
new file mode 100644
index 00000000000..5210652bb11
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551611.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551612.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551612.manifest
new file mode 100644
index 00000000000..f8f942177e8
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551612.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551613.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551613.manifest
new file mode 100644
index 00000000000..72583dc5c45
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551613.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551614.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551614.manifest
new file mode 100644
index 00000000000..7058db9b2bb
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/18446744073709551614.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/latest_version_hint.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/latest_version_hint.json
new file mode 100644
index 00000000000..978d5262ed3
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/_versions/latest_version_hint.json
@@ -0,0 +1 @@
+{"version":5}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/011110000001001000111000634254483b82696db0b43cee8b.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/011110000001001000111000634254483b82696db0b43cee8b.lance
new file mode 100644
index 00000000000..c306d906f99
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/011110000001001000111000634254483b82696db0b43cee8b.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/1011111000111000011010107529f744f0b515d3cc0aaf4111.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/1011111000111000011010107529f744f0b515d3cc0aaf4111.lance
new file mode 100644
index 00000000000..bdcee25cf40
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/1011111000111000011010107529f744f0b515d3cc0aaf4111.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/1101110010000010110100009494424b38a01956f50baa341d.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/1101110010000010110100009494424b38a01956f50baa341d.lance
new file mode 100644
index 00000000000..a6688314a69
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_evolved.lance/data/1101110010000010110100009494424b38a01956f50baa341d.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_indices/961caf93-b3e9-45b9-b1a7-8944a37213ea/auxiliary.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_indices/961caf93-b3e9-45b9-b1a7-8944a37213ea/auxiliary.idx
new file mode 100644
index 00000000000..14f77983cb9
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_indices/961caf93-b3e9-45b9-b1a7-8944a37213ea/auxiliary.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_indices/961caf93-b3e9-45b9-b1a7-8944a37213ea/index.idx b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_indices/961caf93-b3e9-45b9-b1a7-8944a37213ea/index.idx
new file mode 100644
index 00000000000..0ad4ce6fc08
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_indices/961caf93-b3e9-45b9-b1a7-8944a37213ea/index.idx differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_refs/tags/kept.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_refs/tags/kept.json
new file mode 100644
index 00000000000..9a0a0880568
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_refs/tags/kept.json
@@ -0,0 +1,8 @@
+{
+  "branch": null,
+  "version": 2,
+  "createdAt": "2026-09-29T14:52:00.582902Z",
+  "updatedAt": "2026-09-29T14:52:00.582902Z",
+  "manifestSize": 1017,
+  "metadata": {}
+}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_transactions/1-5c4816b8-2e0a-46bb-aa6c-0879630399b4.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_transactions/1-5c4816b8-2e0a-46bb-aa6c-0879630399b4.txn
new file mode 100644
index 00000000000..c8a8678b7b7
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_transactions/1-5c4816b8-2e0a-46bb-aa6c-0879630399b4.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_transactions/2-b57c17ad-85a6-415b-a250-4b2efe8d3f8c.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_transactions/2-b57c17ad-85a6-415b-a250-4b2efe8d3f8c.txn
new file mode 100644
index 00000000000..e5a32a72835
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_transactions/2-b57c17ad-85a6-415b-a250-4b2efe8d3f8c.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/18446744073709551612.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/18446744073709551612.manifest
new file mode 100644
index 00000000000..dd9ff6f73e9
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/18446744073709551612.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/18446744073709551613.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/18446744073709551613.manifest
new file mode 100644
index 00000000000..efcf2d7d8ee
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/18446744073709551613.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/latest_version_hint.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/latest_version_hint.json
new file mode 100644
index 00000000000..f93d3984472
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/_versions/latest_version_hint.json
@@ -0,0 +1 @@
+{"version":3}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/data/101101000110111001110011284b0f491a947f1b18c7abddff.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/data/101101000110111001110011284b0f491a947f1b18c7abddff.lance
new file mode 100644
index 00000000000..a6688314a69
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/search_snapshot_pruned.lance/data/101101000110111001110011284b0f491a947f1b18c7abddff.lance differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_refs/branches/dev%E1%B2%89.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_refs/branches/dev%E1%B2%89.json
new file mode 100644
index 00000000000..f60670a9280
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_refs/branches/dev%E1%B2%89.json
@@ -0,0 +1,15 @@
+{
+  "parentBranch": null,
+  "identifier": {
+    "version_mapping": [
+      [
+        1,
+        "baa77a56726b479eacff307d13509c71"
+      ]
+    ]
+  },
+  "parentVersion": 1,
+  "createAt": 1791178981,
+  "manifestSize": 552,
+  "metadata": {}
+}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_transactions/0-420a1091-b61a-4cfb-8006-0b8f1e322ef8.txn b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_transactions/0-420a1091-b61a-4cfb-8006-0b8f1e322ef8.txn
new file mode 100644
index 00000000000..60e03205e9d
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_transactions/0-420a1091-b61a-4cfb-8006-0b8f1e322ef8.txn differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_versions/18446744073709551614.manifest b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_versions/18446744073709551614.manifest
new file mode 100644
index 00000000000..83622779333
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_versions/18446744073709551614.manifest differ
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_versions/latest_version_hint.json b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_versions/latest_version_hint.json
new file mode 100644
index 00000000000..491d734467a
--- /dev/null
+++ b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/_versions/latest_version_hint.json
@@ -0,0 +1 @@
+{"version":1}
\ No newline at end of file
diff --git a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/data/001101010101111000101000a13eb949eca41d69d17f9ea5a6.lance b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/data/001101010101111000101000a13eb949eca41d69d17f9ea5a6.lance
new file mode 100644
index 00000000000..d1446b437c5
Binary files /dev/null and b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/data/001101010101111000101000a13eb949eca41d69d17f9ea5a6.lance differ
diff --git "a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_transactions/1-1be00bd2-8443-4851-9ab8-4bdcee3ffa5e.txn" "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_transactions/1-1be00bd2-8443-4851-9ab8-4bdcee3ffa5e.txn"
new file mode 100644
index 00000000000..3548df51401
Binary files /dev/null and "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_transactions/1-1be00bd2-8443-4851-9ab8-4bdcee3ffa5e.txn" differ
diff --git "a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_transactions/1-c1998c6f-6213-4b7e-ae7c-cc00cde3b7de.txn" "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_transactions/1-c1998c6f-6213-4b7e-ae7c-cc00cde3b7de.txn"
new file mode 100644
index 00000000000..fb3b7a57266
--- /dev/null
+++ "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_transactions/1-c1998c6f-6213-4b7e-ae7c-cc00cde3b7de.txn"
@@ -0,0 +1 @@
+$c1998c6f-6213-4b7e-ae7c-cc00cde3b7de�7")s3://warehouse/lance/unicode_branch.lance*devᲉ
\ No newline at end of file
diff --git "a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_versions/18446744073709551613.manifest" "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_versions/18446744073709551613.manifest"
new file mode 100644
index 00000000000..19fd4f62f3f
Binary files /dev/null and "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_versions/18446744073709551613.manifest" differ
diff --git "a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_versions/18446744073709551614.manifest" "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_versions/18446744073709551614.manifest"
new file mode 100644
index 00000000000..42918df699b
Binary files /dev/null and "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/_versions/18446744073709551614.manifest" differ
diff --git "a/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/data/01110100011000100001111040aa57401ab473a6a921298540.lance" "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/data/01110100011000100001111040aa57401ab473a6a921298540.lance"
new file mode 100644
index 00000000000..266136cc003
Binary files /dev/null and "b/docker/thirdparties/docker-compose/iceberg/scripts/preinstalled_data/lance/unicode_branch.lance/tree/dev\341\262\211/data/01110100011000100001111040aa57401ab473a6a921298540.lance" differ
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceCatalogClient.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceCatalogClient.java
index 8b745a868a9..4cd3ed64329 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceCatalogClient.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceCatalogClient.java
@@ -20,7 +20,6 @@ package org.apache.doris.datasource.lance;
 import org.apache.doris.analysis.TableSnapshot;
 import org.apache.doris.common.Config;
 import org.apache.doris.common.DdlException;
-import org.apache.doris.common.util.TimeUtils;
 import org.apache.doris.datasource.lance.index.LanceIndexInspection;
 import org.apache.doris.datasource.lance.index.LanceIndexInspectionExecutor;
 import org.apache.doris.datasource.lance.index.LancePhysicalIndexEntry;
@@ -73,8 +72,6 @@ import java.util.function.BiFunction;
 final class LanceCatalogClient implements AutoCloseable {
 
     private static final Logger LOG = LogManager.getLogger(LanceCatalogClient.class);
-    /** Lance's name for the main chain; {@code @branch(main)} and tags on it mean the main chain. */
-    static final String MAIN_BRANCH = "main";
     private static final long METADATA_CACHE_SIZE_BYTES = 64L * 1024 * 1024;
     private static final long INDEX_CACHE_SIZE_BYTES = 128L * 1024 * 1024;
 
@@ -235,7 +232,11 @@ final class LanceCatalogClient implements AutoCloseable {
     }
 
     public LanceTableMetadata loadTableMetadataForSearch(String dbName, String tableName) {
-        LanceTableMetadata metadata = loadQueryMetadata(dbName, tableName, Optional.empty(),
+        return loadTableMetadataForSearch(dbName, tableName, LanceRefSelector.latest());
+    }
+
+    public LanceTableMetadata loadTableMetadataForSearch(String dbName, String tableName, LanceRefSelector selector) {
+        LanceTableMetadata metadata = loadQueryMetadata(dbName, tableName, selector,
                 LanceMetadataLoader.MetadataScope.WITH_INDEXES);
         if (!metadata.getIndexMetadataState().canPlanIndexSegments()) {
             throw new IllegalArgumentException("Lance SDK cannot provide field IDs required for search planning");
@@ -244,7 +245,11 @@ final class LanceCatalogClient implements AutoCloseable {
     }
 
     public LanceTableMetadata loadBasicTableMetadata(String dbName, String tableName) {
-        return loadQueryMetadata(dbName, tableName, Optional.empty(), LanceMetadataLoader.MetadataScope.BASIC);
+        return loadBasicTableMetadata(dbName, tableName, LanceRefSelector.latest());
+    }
+
+    public LanceTableMetadata loadBasicTableMetadata(String dbName, String tableName, LanceRefSelector selector) {
+        return loadQueryMetadata(dbName, tableName, selector, LanceMetadataLoader.MetadataScope.BASIC);
     }
 
     public Schema loadTableSchema(String dbName, String tableName) {
@@ -261,11 +266,6 @@ final class LanceCatalogClient implements AutoCloseable {
         return loadQueryMetadata(dbName, tableName, selector, LanceMetadataLoader.MetadataScope.WITH_INDEXES);
     }
 
-    private LanceTableMetadata loadQueryMetadata(String dbName, String tableName,
-            Optional<TableSnapshot> tableSnapshot, LanceMetadataLoader.MetadataScope mode) {
-        return loadQueryMetadata(dbName, tableName, LanceRefSelector.snapshot(tableSnapshot), mode);
-    }
-
     private LanceTableMetadata loadQueryMetadata(String dbName, String tableName,
             LanceRefSelector selector, LanceMetadataLoader.MetadataScope mode) {
         return readTableSnapshot(dbName, tableName, selector,
@@ -473,6 +473,7 @@ final class LanceCatalogClient implements AutoCloseable {
     private <T> T readManagedBranch(BufferAllocator allocator, ReadState state, SnapshotReader<T> reader,
             LanceMetadataMetrics metrics) throws Exception {
         String branch = state.branch.get();
+        checkBranchName(branch);
         LanceTableAccess branchAccess = state.access.onBranch(branch,
                 branchUri(state.access.getDatasetUri(), branch));
         Optional<TableSnapshot> snapshot = state.selector.getSnapshot();
@@ -494,6 +495,44 @@ final class LanceCatalogClient implements AutoCloseable {
         }
     }
 
+    /**
+     * Rejects a branch name that could leave the table's {@code tree/} directory or change the URI
+     * {@link #branchUri} joins for a managed table, which Lance does not validate on that path;
+     * the object store resolves dot segments, including percent-encoded ones. Other tables check a
+     * branch out through Lance, which validates the name itself.
+     *
+     * <p>This never rejects a name Lance's {@code check_valid_branch} accepts, whichever Unicode
+     * version either side uses: ASCII allows exactly Lance's letters, digits, '.', '-', '_' and
+     * '/', and outside ASCII only whitespace and control characters, which are never
+     * alphanumeric, are rejected. Lance cannot create a branch with a name it would reject, and the
+     * namespace decides whether such a branch exists.
+     */
+    static void checkBranchName(String branch) {
+        String reason = null;
+        if (branch.isEmpty()) {
+            reason = "it is empty";
+        } else if (branch.startsWith("/") || branch.endsWith("/") || branch.contains("//")) {
+            reason = "it starts or ends with '/' or contains an empty segment";
+        } else if (branch.contains("..") || branch.endsWith(".lock")) {
+            reason = "it contains '..' or ends with '.lock'";
+        } else if (!branch.codePoints().allMatch(LanceCatalogClient::isBranchNameCharacter)) {
+            reason = "only letters, digits, '.', '-', '_' and '/' between segments are allowed";
+        }
+        if (reason != null) {
+            throw new LanceUserFacingException("Invalid Lance branch name '" + branch + "': " + reason);
+        }
+    }
+
+    private static boolean isBranchNameCharacter(int codePoint) {
+        if (codePoint < 0x80) {
+            return (codePoint >= 'a' && codePoint <= 'z') || (codePoint >= 'A' && codePoint <= 'Z')
+                    || (codePoint >= '0' && codePoint <= '9') || codePoint == '.' || codePoint == '-'
+                    || codePoint == '_' || codePoint == '/';
+        }
+        return !Character.isWhitespace(codePoint) && !Character.isSpaceChar(codePoint)
+                && !Character.isISOControl(codePoint);
+    }
+
     /**
      * The URI of a branch's directory, joined as Lance's {@code BranchLocation} joins it:
      * {@code tree/<branch>} under the table root, before the URI's query string.
@@ -746,26 +785,19 @@ final class LanceCatalogClient implements AutoCloseable {
 
     private static LanceUserFacingException historyRemoved(long version, boolean staged, String requestedText,
             ReadState state) {
-        return new LanceUserFacingException("Lance cannot resolve FOR TIME AS OF '" + requestedText + "' on "
+        // Worded for FOR TIME AS OF and the search functions' timestamp alike.
+        return new LanceUserFacingException("Lance cannot select the version at or before '" + requestedText + "' on "
                 + state.displayName() + ": version " + version + ", which may hold the state at that time, "
                 + (staged ? "cannot be read: " + stagedOnly() : "no longer exists"));
     }
 
-    /**
-     * Parses a {@code FOR TIME AS OF} value in the session time zone. Second and millisecond
-     * precision are accepted. Commit times are compared in full, so a commit later within the
-     * requested millisecond is not selected.
-     */
     private static long parseTimeTravelTimestamp(String value) {
-        long timestamp = TimeUtils.timeStringToLong(value, TimeUtils.getTimeZone());
-        if (timestamp < 0) {
-            timestamp = TimeUtils.msTimeStringToLong(value, TimeUtils.getTimeZone());
-        }
-        if (timestamp < 0) {
+        OptionalLong timestamp = LanceSnapshotResolver.parseTimestamp(value);
+        if (!timestamp.isPresent()) {
             throw new IllegalArgumentException("Cannot parse Lance FOR TIME AS OF value '" + value
-                    + "', expected 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd HH:mm:ss.SSS'");
+                    + "', expected " + LanceSnapshotResolver.TIMESTAMP_FORMATS);
         }
-        return timestamp;
+        return timestamp.getAsLong();
     }
 
     /**
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalCatalog.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalCatalog.java
index 187d2b19121..dc62cb7ff63 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalCatalog.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalCatalog.java
@@ -224,11 +224,19 @@ public class LanceExternalCatalog extends ExternalCatalog {
     }
 
     public LanceTableMetadata loadTableMetadataForSearch(String dbName, String tableName) {
-        return withClient(current -> current.loadTableMetadataForSearch(dbName, tableName));
+        return loadTableMetadataForSearch(dbName, tableName, LanceRefSelector.latest());
+    }
+
+    public LanceTableMetadata loadTableMetadataForSearch(String dbName, String tableName, LanceRefSelector selector) {
+        return withClient(current -> current.loadTableMetadataForSearch(dbName, tableName, selector));
     }
 
     public LanceTableMetadata loadBasicTableMetadata(String dbName, String tableName) {
-        return withClient(current -> current.loadBasicTableMetadata(dbName, tableName));
+        return loadBasicTableMetadata(dbName, tableName, LanceRefSelector.latest());
+    }
+
+    public LanceTableMetadata loadBasicTableMetadata(String dbName, String tableName, LanceRefSelector selector) {
+        return withClient(current -> current.loadBasicTableMetadata(dbName, tableName, selector));
     }
 
     public Schema loadTableSchema(String dbName, String tableName) {
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalTable.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalTable.java
index 916976cdfaf..9069a353942 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalTable.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/LanceExternalTable.java
@@ -64,13 +64,15 @@ public class LanceExternalTable extends ExternalTable implements MvccTable {
         return ((LanceExternalCatalog) catalog).loadTableMetadata(db.getRemoteName(), remoteName);
     }
 
-    public LanceTableMetadata loadMetadataForSearch() {
+    /** Search metadata, index details included, of the snapshot {@code selector} selects. */
+    public LanceTableMetadata loadMetadataForSearch(LanceRefSelector selector) {
         return ((LanceExternalCatalog) catalog).loadTableMetadataForSearch(
-                db.getRemoteName(), remoteName);
+                db.getRemoteName(), remoteName, selector);
     }
 
-    public LanceTableMetadata loadBasicMetadata() {
-        return ((LanceExternalCatalog) catalog).loadBasicTableMetadata(db.getRemoteName(), remoteName);
+    /** Search metadata without index details, of the snapshot {@code selector} selects. */
+    public LanceTableMetadata loadBasicMetadata(LanceRefSelector selector) {
+        return ((LanceExternalCatalog) catalog).loadBasicTableMetadata(db.getRemoteName(), remoteName, selector);
     }
 
     public List<LanceShowIndexInfo> loadIndexesForShow() throws AnalysisException {
@@ -112,10 +114,7 @@ public class LanceExternalTable extends ExternalTable implements MvccTable {
                             + tableSnapshot.get().getValue() + "' names a tag, which cannot be combined with @branch;"
                             + " use @tag(...) or a numeric version");
                 }
-                // Lance calls the main chain "main"; it lives at the table root, not under tree/.
-                if (!LanceCatalogClient.MAIN_BRANCH.equals(branch)) {
-                    selector = LanceRefSelector.branch(branch, tableSnapshot);
-                }
+                selector = LanceRefSelector.branch(branch, tableSnapshot);
             } else if (params.isTag()) {
                 if (tableSnapshot.isPresent()) {
                     throw new IllegalArgumentException("Lance table " + getName()
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/index/LanceDatasetIndexDiscovery.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/index/LanceDatasetIndexDiscovery.java
index 21819caa90e..8747aa18ef1 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/index/LanceDatasetIndexDiscovery.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/index/LanceDatasetIndexDiscovery.java
@@ -47,7 +47,9 @@ public final class LanceDatasetIndexDiscovery {
      * Describes only user-created indexes. The Lance JNI bulk describe path also tries to
      * materialize details for internal indexes, whose details are not supported by the SDK.
      * Legacy indexes that cannot be described because all their segments lack details are
-     * omitted. This disables their FE segment planning, not the scanner's automatic index use.
+     * omitted, so the FE plans no segments for them. Vector and full-text searches use only the
+     * segments the FE plans and therefore never use such an index; an ordinary scan may still use
+     * a legacy scalar index through Lance's own index selection.
      */
     public static List<IndexDescription> describeUserIndexes(Dataset dataset) {
         List<String> listedNames = dataset.listIndexes();
@@ -98,7 +100,7 @@ public final class LanceDatasetIndexDiscovery {
                 if (indexesWithoutDetails.contains(name)) {
                     LOG.warn("Skipping FE metadata and segment planning for legacy Lance index '{}' "
                             + "at dataset version {}: all physical segments lack index details; "
-                            + "scanner index selection remains unchanged", name, dataset.version());
+                            + "vector and full-text searches will not use it", name, dataset.version());
                     continue;
                 }
             }
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceRefSelector.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceRefSelector.java
index 2ef80565be7..86a72e81b5c 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceRefSelector.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceRefSelector.java
@@ -28,6 +28,9 @@ import java.util.Optional;
  * with a snapshot inside that branch). A tag and a snapshot exclude each other.
  */
 public final class LanceRefSelector {
+    /** Lance's name for the main chain. Lance rejects it as a branch name, so it never names a real branch. */
+    public static final String MAIN_BRANCH = "main";
+
     private static final LanceRefSelector LATEST = new LanceRefSelector(Optional.empty(), Optional.empty(),
             Optional.empty());
 
@@ -56,8 +59,14 @@ public final class LanceRefSelector {
         return new LanceRefSelector(Optional.empty(), Optional.of(tag), Optional.empty());
     }
 
-    /** A branch, at its latest version or at the snapshot selected inside it. */
+    /**
+     * A branch, at its latest version or at the snapshot selected inside it. {@value #MAIN_BRANCH}
+     * is the main chain, which lives at the table root rather than under {@code tree/}.
+     */
     public static LanceRefSelector branch(String branch, Optional<TableSnapshot> snapshot) {
+        if (MAIN_BRANCH.equals(branch)) {
+            return snapshot(snapshot);
+        }
         return new LanceRefSelector(snapshot, Optional.empty(), Optional.of(branch));
     }
 
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceSnapshotResolver.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceSnapshotResolver.java
index 7483e4892ad..b90b98ee4cd 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceSnapshotResolver.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/metadata/LanceSnapshotResolver.java
@@ -17,6 +17,8 @@
 
 package org.apache.doris.datasource.lance.metadata;
 
+import org.apache.doris.common.util.TimeUtils;
+
 import org.lance.Version;
 
 import java.time.Instant;
@@ -26,6 +28,7 @@ import java.util.Comparator;
 import java.util.List;
 import java.util.NavigableMap;
 import java.util.NavigableSet;
+import java.util.OptionalLong;
 import java.util.TreeMap;
 import java.util.regex.Pattern;
 
@@ -54,6 +57,28 @@ public final class LanceSnapshotResolver {
 
     private static final Pattern VERSION_NUMBER = Pattern.compile("[+-]?[0-9]+");
 
+    /** The time formats {@link #parseTimestamp} accepts, for error messages. */
+    public static final String TIMESTAMP_FORMATS = "'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd HH:mm:ss.SSS'";
+
+    /**
+     * Parses a time-travel timestamp in the session time zone, with second or millisecond
+     * precision, into epoch milliseconds; empty if the value is in neither format. Commit times
+     * are compared in full, so a commit later within the requested millisecond is not selected.
+     */
+    public static OptionalLong parseTimestamp(String value) {
+        long timestamp;
+        try {
+            timestamp = TimeUtils.timeStringToLong(value, TimeUtils.getTimeZone());
+            if (timestamp < 0) {
+                timestamp = TimeUtils.msTimeStringToLong(value, TimeUtils.getTimeZone());
+            }
+        } catch (ArithmeticException e) {
+            // A year too large for epoch milliseconds.
+            return OptionalLong.empty();
+        }
+        return timestamp < 0 ? OptionalLong.empty() : OptionalLong.of(timestamp);
+    }
+
     /**
      * Whether a {@code FOR VERSION AS OF} value is a version number rather than a tag name. A
      * signed number counts as one, so that {@code '-1'} is reported as an invalid version.
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanNode.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanNode.java
index 3f9505b87b9..c572234f027 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanNode.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanNode.java
@@ -386,8 +386,7 @@ public class LanceScanNode extends FileQueryScanNode {
                             .append(fullText.getPhraseSlop()).append("\n");
                 }
             }
-            result.append(prefix).append("lanceVersion=")
-                    .append(plannedMetadata.getVersion()).append("\n");
+            appendSnapshotExplain(result, prefix);
             result.append(prefix).append("lanceSearchFragments=")
                     .append(scanPlan.fragmentCount).append("\n");
             result.append(prefix).append("lanceSearchUnindexedFragments=")
@@ -397,13 +396,7 @@ public class LanceScanNode extends FileQueryScanNode {
             result.append(prefix).append("lanceSearchIndexFragments=")
                     .append(scanPlan.indexedFragmentCount).append("\n");
         } else {
-            result.append(prefix).append("lanceCatalogType=")
-                    .append(((LanceExternalCatalog) lanceTable.getCatalog()).getLanceCatalogType()).append("\n");
-            result.append(prefix).append("lanceVersion=").append(scanPlan.version).append("\n");
-            result.append(prefix).append("lanceManagedVersioning=")
-                    .append(plannedMetadata.isManagedVersioning()).append("\n");
-            plannedMetadata.getBranch().ifPresent(branch ->
-                    result.append(prefix).append("lanceBranch=").append(branch).append("\n"));
+            appendSnapshotExplain(result, prefix);
             result.append(prefix).append("lanceFragments=").append(scanPlan.fragmentCount).append("\n");
             if (scanPlan.fragmentsPerSplit > 0) {
                 result.append(prefix).append("lanceFragmentGrouping=DEBUG\n");
@@ -433,6 +426,17 @@ public class LanceScanNode extends FileQueryScanNode {
         return result.toString();
     }
 
+    /** The snapshot this node plans from; table scans and searches show it the same way. */
+    private void appendSnapshotExplain(StringBuilder result, String prefix) {
+        result.append(prefix).append("lanceCatalogType=")
+                .append(((LanceExternalCatalog) lanceTable.getCatalog()).getLanceCatalogType()).append("\n");
+        result.append(prefix).append("lanceVersion=").append(plannedMetadata.getVersion()).append("\n");
+        result.append(prefix).append("lanceManagedVersioning=")
+                .append(plannedMetadata.isManagedVersioning()).append("\n");
+        plannedMetadata.getBranch().ifPresent(branch ->
+                result.append(prefix).append("lanceBranch=").append(branch).append("\n"));
+    }
+
     TExternalSearchRequest createSplitSearchRequest() {
         TExternalSearchRequest splitRequest = externalSearchRequest.deepCopy();
         // Every split must retain enough rows for the later global OFFSET/LIMIT. Applying the
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlan.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlan.java
index 94e604a6f16..d2259c697ed 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlan.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlan.java
@@ -52,7 +52,10 @@ final class LanceScanPlan {
         }
     }
 
-    /** Explains FE segment selection, not whether the BE may automatically use a Lance index. */
+    /**
+     * Explains FE segment selection. The BE searches an index only through the segments the FE
+     * plans, so a vector search under any status other than USED is a flat search.
+     */
     enum VectorIndexStatus {
         /** No vector planning result exists yet (also used by ordinary and FTS scans). */
         NOT_PLANNED,
@@ -72,7 +75,6 @@ final class LanceScanPlan {
 
     final VectorIndexStatus vectorIndexStatus;
     private final List<Split> splits;
-    final long version;
     final int fragmentCount;
     final int fragmentsPerSplit;
     final int indexSegmentCount;
@@ -80,12 +82,11 @@ final class LanceScanPlan {
     final int unindexedFragmentCount;
     final String scalarIndexName;
 
-    LanceScanPlan(List<Split> splits, long version, int fragments, int fragmentsPerSplit,
+    LanceScanPlan(List<Split> splits, int fragments, int fragmentsPerSplit,
             int indexSegments, int indexFragments, int unindexedFragments, String scalarIndexName,
             VectorIndexStatus vectorIndexStatus) {
         this.vectorIndexStatus = vectorIndexStatus;
         this.splits = Collections.unmodifiableList(new ArrayList<>(splits));
-        this.version = version;
         this.fragmentCount = fragments;
         this.fragmentsPerSplit = fragmentsPerSplit;
         this.indexSegmentCount = indexSegments;
@@ -95,7 +96,7 @@ final class LanceScanPlan {
     }
 
     static LanceScanPlan empty() {
-        return new LanceScanPlan(Collections.emptyList(), -1, 0, 0, 0, 0, 0, null, VectorIndexStatus.NOT_PLANNED);
+        return new LanceScanPlan(Collections.emptyList(), 0, 0, 0, 0, 0, null, VectorIndexStatus.NOT_PLANNED);
     }
 
     /** Backend assignment shuffles its input list; keep that mutation outside the stored plan. */
diff --git a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlanner.java b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlanner.java
index 23fc3eeb5dd..2d97bc802bf 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlanner.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/datasource/lance/source/LanceScanPlanner.java
@@ -79,7 +79,7 @@ final class LanceScanPlanner {
             LanceScanPlanner planner = new LanceScanPlanner(metadata, kind, request,
                     fieldId, pushedConjuncts, fragmentsPerSplit, countParallelism);
             List<Split> splits = planner.buildSplits();
-            LanceScanPlan plan = new LanceScanPlan(splits, metadata.getVersion(), planner.plannedFragments,
+            LanceScanPlan plan = new LanceScanPlan(splits, planner.plannedFragments,
                     planner.plannedFragmentsPerSplit, planner.plannedIndexSegments, planner.plannedIndexFragments,
                     planner.plannedUnindexedFragments,
                     planner.scalarIndexPlan == null ? null : planner.scalarIndexPlan.indexName,
@@ -166,13 +166,19 @@ final class LanceScanPlanner {
         return splits;
     }
 
+    /** "dataset version N", naming the branch too, since branches number versions like main. */
+    private static String datasetVersion(LanceTableMetadata metadata) {
+        return "dataset version " + metadata.getVersion()
+                + metadata.getBranch().map(branch -> " of branch '" + branch + "'").orElse("");
+    }
+
     private Map<Long, LanceFragmentInfo> getVisibleFragments(LanceTableMetadata metadata)
             throws UserException {
         Map<Long, LanceFragmentInfo> visible = new LinkedHashMap<>();
         for (LanceFragmentInfo fragment : metadata.getFragments()) {
             if (visible.put(fragment.getId(), fragment) != null) {
                 throw new UserException("Duplicate Lance fragment id " + fragment.getId()
-                        + " at dataset version " + metadata.getVersion());
+                        + " at " + datasetVersion(metadata));
             }
         }
         return visible;
@@ -251,7 +257,7 @@ final class LanceScanPlanner {
                 metadata.getIndexes(), searchFieldId, fullText.getColumn());
         if (matchingSegments.isEmpty()) {
             throw new UserException("No committed Lance FTS index exists for column '"
-                    + fullText.getColumn() + "' at dataset version " + metadata.getVersion());
+                    + fullText.getColumn() + "' at " + datasetVersion(metadata));
         }
         // A matching index with no visible coverage is a valid empty INDEX_ONLY result.
         // Unknown coverage still throws in planIndexSegments; STRICT checks uncovered fragments below.
@@ -265,7 +271,7 @@ final class LanceScanPlanner {
         if (fullText.getCoverageMode() == TFtsCoverageMode.STRICT
                 && plannedUnindexedFragments != 0) {
             throw new UserException("Lance FTS coverage_mode=STRICT requires every fragment at "
-                    + "dataset version " + metadata.getVersion() + " to be indexed; column '"
+                    + datasetVersion(metadata) + " to be indexed; column '"
                     + fullText.getColumn() + "' has " + plannedUnindexedFragments
                     + " unindexed fragments. Rebuild the index or use coverage_mode=index_only");
         }
diff --git a/fe/fe-core/src/main/java/org/apache/doris/nereids/parser/LogicalPlanBuilder.java b/fe/fe-core/src/main/java/org/apache/doris/nereids/parser/LogicalPlanBuilder.java
index 492b299c7dc..7a83e22961d 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/nereids/parser/LogicalPlanBuilder.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/nereids/parser/LogicalPlanBuilder.java
@@ -2899,6 +2899,16 @@ public class LogicalPlanBuilder extends DorisParserBaseVisitor<Object> {
                     }
                 }
             } else {
+                if ("full_text_search".equalsIgnoreCase(functionName) && ctx.properties != null) {
+                    // A placeholder would otherwise reach the function as the literal text "?".
+                    for (PropertyItemContext argument : ctx.properties.properties) {
+                        if (argument.key.constant() instanceof DorisParser.PlaceholderContext
+                                || argument.value.constant() instanceof DorisParser.PlaceholderContext) {
+                            throw new AnalysisException("full_text_search properties must be constant"
+                                    + " in a prepared statement");
+                        }
+                    }
+                }
                 map = visitPropertyItemList(ctx.properties);
             }
             LogicalPlan relation = new UnboundTVFRelation(StatementScopeIdGenerator.newRelationId(),
diff --git a/fe/fe-core/src/main/java/org/apache/doris/tablefunction/FullTextSearchTableValuedFunction.java b/fe/fe-core/src/main/java/org/apache/doris/tablefunction/FullTextSearchTableValuedFunction.java
index 8c7789e4535..24d27cd06e2 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/tablefunction/FullTextSearchTableValuedFunction.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/tablefunction/FullTextSearchTableValuedFunction.java
@@ -48,7 +48,7 @@ public class FullTextSearchTableValuedFunction extends LanceExternalSearchTableV
     private static final String SLOP = "slop";
     private static final Set<String> PROPERTIES = ImmutableSet.of(
             TABLE, COLUMN, QUERY, TOP_K, OFFSET, FILTER, COVERAGE_MODE,
-            QUERY_TYPE, OPERATOR, MAX_FUZZY_DISTANCE, SLOP);
+            QUERY_TYPE, OPERATOR, MAX_FUZZY_DISTANCE, SLOP, VERSION, TIMESTAMP, TAG, BRANCH);
 
     public FullTextSearchTableValuedFunction(Map<String, String> properties)
             throws AnalysisException {
diff --git a/fe/fe-core/src/main/java/org/apache/doris/tablefunction/LanceExternalSearchTableValuedFunction.java b/fe/fe-core/src/main/java/org/apache/doris/tablefunction/LanceExternalSearchTableValuedFunction.java
index 12d078e1c9a..6b1e910def7 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/tablefunction/LanceExternalSearchTableValuedFunction.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/tablefunction/LanceExternalSearchTableValuedFunction.java
@@ -18,6 +18,7 @@
 package org.apache.doris.tablefunction;
 
 import org.apache.doris.analysis.TableName;
+import org.apache.doris.analysis.TableSnapshot;
 import org.apache.doris.analysis.TupleDescriptor;
 import org.apache.doris.catalog.Column;
 import org.apache.doris.catalog.Env;
@@ -29,7 +30,9 @@ import org.apache.doris.common.ErrorReport;
 import org.apache.doris.datasource.CatalogIf;
 import org.apache.doris.datasource.lance.LanceExternalCatalog;
 import org.apache.doris.datasource.lance.LanceExternalTable;
+import org.apache.doris.datasource.lance.metadata.LanceRefSelector;
 import org.apache.doris.datasource.lance.metadata.LanceSchemaHelper;
+import org.apache.doris.datasource.lance.metadata.LanceSnapshotResolver;
 import org.apache.doris.datasource.lance.metadata.LanceTableMetadata;
 import org.apache.doris.datasource.lance.source.LanceScanNode;
 import org.apache.doris.mysql.privilege.PrivPredicate;
@@ -54,6 +57,7 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Optional;
 import java.util.OptionalInt;
 import java.util.Set;
 import java.util.TreeMap;
@@ -67,6 +71,10 @@ abstract class LanceExternalSearchTableValuedFunction extends TableValuedFunctio
     protected static final String TOP_K = "top_k";
     protected static final String OFFSET = "offset";
     protected static final String FILTER = "filter";
+    protected static final String VERSION = "version";
+    protected static final String TIMESTAMP = "timestamp";
+    protected static final String TAG = "tag";
+    protected static final String BRANCH = "branch";
 
     private static final String FULLY_QUALIFIED_TABLE_NAME_ERROR =
             "'table' must be a fully qualified catalog.database.table name";
@@ -74,6 +82,7 @@ abstract class LanceExternalSearchTableValuedFunction extends TableValuedFunctio
     /** A trailing @tag/@branch/... or FOR VERSION/TIME AS OF on the 'table' argument. */
     private static final Pattern SELECTOR_SUFFIX = Pattern.compile(
             "(?i)(@\\s*(tag|branch|incr|options)\\b|\\sfor\\s+(version|time)\\b)");
+    private static final Pattern POSITIVE_INTEGER = Pattern.compile("[0-9]+");
 
     private final String displayName;
     private final TableName sourceTableName;
@@ -165,11 +174,12 @@ abstract class LanceExternalSearchTableValuedFunction extends TableValuedFunctio
             String displayName, String searchDescription, boolean loadIndexMetadata)
             throws AnalysisException {
         TableName sourceTableName = parseTableName(required(params, TABLE, functionName));
+        LanceRefSelector selector = parseSelector(params);
         LanceExternalTable sourceTable = findLanceExternalTable(sourceTableName);
         LanceTableMetadata metadata;
         try {
             metadata = loadIndexMetadata
-                    ? sourceTable.loadMetadataForSearch() : sourceTable.loadBasicMetadata();
+                    ? sourceTable.loadMetadataForSearch(selector) : sourceTable.loadBasicMetadata(selector);
         } catch (RuntimeException e) {
             throw new AnalysisException("Failed to load Lance metadata for " + searchDescription
                     + " on " + sourceTableName + ": " + e.getMessage(), e);
@@ -262,14 +272,83 @@ abstract class LanceExternalSearchTableValuedFunction extends TableValuedFunctio
     }
 
     /**
-     * The search TVFs always read the latest version of the main chain. A name that only fails to
-     * parse because it carries a selector gets a message saying so; a backquoted name containing
-     * '@' or ' for ' parses and is never affected.
+     * The snapshot the 'version', 'timestamp', 'tag' and 'branch' properties select, under the
+     * rules of FOR VERSION AS OF, FOR TIME AS OF, @tag and @branch on a Lance table: a tag
+     * determines both its branch and its version, so it stands alone, and a version or a time
+     * selects within a branch, the main chain by default. Unlike FOR VERSION AS OF, 'version' does
+     * not take a tag name, which 'tag' names without ambiguity. No selector property selects the
+     * latest version of the main chain. Errors name the properties, and a selector the catalog
+     * cannot resolve later fails rather than falling back to the latest version.
+     */
+    static LanceRefSelector parseSelector(Map<String, String> params) throws AnalysisException {
+        Optional<String> version = selectorProperty(params, VERSION);
+        Optional<String> timestamp = selectorProperty(params, TIMESTAMP);
+        Optional<String> tag = selectorProperty(params, TAG);
+        Optional<String> branch = selectorProperty(params, BRANCH);
+        if (version.isPresent() && timestamp.isPresent()) {
+            throw new AnalysisException("'" + VERSION + "' and '" + TIMESTAMP + "' are mutually exclusive");
+        }
+        if (tag.isPresent()) {
+            for (String other : new String[] {VERSION, TIMESTAMP, BRANCH}) {
+                if (params.containsKey(other)) {
+                    throw new AnalysisException("'" + TAG + "' and '" + other + "' are mutually exclusive;"
+                            + " a tag already determines its branch and version");
+                }
+            }
+            return LanceRefSelector.tag(tag.get());
+        }
+        Optional<TableSnapshot> snapshot = Optional.empty();
+        if (version.isPresent()) {
+            snapshot = Optional.of(TableSnapshot.versionOf(String.valueOf(parseVersion(version.get()))));
+        } else if (timestamp.isPresent()) {
+            if (!LanceSnapshotResolver.parseTimestamp(timestamp.get()).isPresent()) {
+                throw new AnalysisException("'" + TIMESTAMP + "' must be " + LanceSnapshotResolver.TIMESTAMP_FORMATS
+                        + " in the session time zone, but was '" + timestamp.get() + "'");
+            }
+            snapshot = Optional.of(TableSnapshot.timeOf(timestamp.get()));
+        }
+        return branch.isPresent()
+                ? LanceRefSelector.branch(branch.get(), snapshot) : LanceRefSelector.snapshot(snapshot);
+    }
+
+    /** A selector property's trimmed value. An empty one is an error, not an absent selector. */
+    private static Optional<String> selectorProperty(Map<String, String> params, String key)
+            throws AnalysisException {
+        String value = params.get(key);
+        if (value == null) {
+            return Optional.empty();
+        }
+        if (value.trim().isEmpty()) {
+            throw new AnalysisException("'" + key + "' must not be empty");
+        }
+        return Optional.of(value.trim());
+    }
+
+    private static long parseVersion(String value) throws AnalysisException {
+        String error = "'" + VERSION + "' must be a positive integer, but was '" + value + "'";
+        if (!POSITIVE_INTEGER.matcher(value).matches()) {
+            throw new AnalysisException(error);
+        }
+        long version;
+        try {
+            version = Long.parseLong(value);
+        } catch (NumberFormatException e) {
+            throw new AnalysisException("'" + VERSION + "' " + value + " is out of range");
+        }
+        if (version <= 0) {
+            throw new AnalysisException(error);
+        }
+        return version;
+    }
+
+    /**
+     * A name that only fails to parse because it carries a selector gets a message pointing to the
+     * selector properties; a backquoted name containing '@' or ' for ' parses and is never affected.
      */
     private static String tableNameError(String value) {
         return SELECTOR_SUFFIX.matcher(value).find()
                 ? "'table' of a Lance search function cannot select a version, tag or branch;"
-                        + " it always searches the latest version"
+                        + " use the 'version', 'timestamp', 'tag' or 'branch' property"
                 : FULLY_QUALIFIED_TABLE_NAME_ERROR;
     }
 
diff --git a/fe/fe-core/src/main/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunction.java b/fe/fe-core/src/main/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunction.java
index 93f7b2f4d56..2e9e2374b7f 100644
--- a/fe/fe-core/src/main/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunction.java
+++ b/fe/fe-core/src/main/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunction.java
@@ -67,7 +67,7 @@ public class VectorSearchTableValuedFunction extends LanceExternalSearchTableVal
     private static final String USE_INDEX = "use_index";
     private static final Set<String> PROPERTIES = ImmutableSet.of(
             TABLE, COLUMN, QUERY_VECTOR, TOP_K, OFFSET, METRIC, FILTER,
-            NPROBES, REFINE_FACTOR, EF, USE_INDEX, QUERY_PARALLELISM);
+            NPROBES, REFINE_FACTOR, EF, USE_INDEX, QUERY_PARALLELISM, VERSION, TIMESTAMP, TAG, BRANCH);
 
     public VectorSearchTableValuedFunction(Map<String, String> properties)
             throws AnalysisException {
diff --git a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceCatalogClientTest.java b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceCatalogClientTest.java
index 73f31711abd..3b260a86ed4 100644
--- a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceCatalogClientTest.java
+++ b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceCatalogClientTest.java
@@ -194,6 +194,32 @@ public class LanceCatalogClientTest {
         }
     }
 
+    /**
+     * A managed table's branch is opened by a URI Doris joins, so Doris rejects names that could
+     * leave the table's tree/ directory, since the object store would resolve dot segments, even
+     * percent-encoded ones, but never a name Lance accepts.
+     */
+    @Test
+    public void testManagedBranchNamesFollowLanceRules() {
+        // Every name Lance accepts passes, including letters newer than the JDK's Unicode tables:
+        // "devᲉ" ends with U+1C89, added in Unicode 16, which Rust's char::is_alphanumeric
+        // accepts and JDK 17 leaves unassigned. "शाखा" has a combining vowel sign, then a
+        // superscript digit and a Roman numeral.
+        for (String valid : new String[] {"dev", "team/dev", "v1.0", "a_b-c", "123", "dev2026", "分支",
+                "devᲉ", "शाखा", "v²", "Ⅻ"}) {
+            LanceCatalogClient.checkBranchName(valid);
+        }
+        // URI and path syntax is rejected, as is whitespace, including an ideographic space.
+        for (String invalid : new String[] {"", "../other.lance", "a/../../b", "/dev", "dev/", "a//b",
+                "x.lock", "%2e%2e/x", "dev?x=1", "dev#x", "a b", "a\\b", "s3://bucket/t", "a+b", "a\tb",
+                "a b"}) {
+            RuntimeException exception = Assertions.assertThrows(RuntimeException.class,
+                    () -> LanceCatalogClient.checkBranchName(invalid), invalid);
+            Assertions.assertTrue(exception.getMessage().startsWith("Invalid Lance branch name '" + invalid + "'"),
+                    exception.getMessage());
+        }
+    }
+
     private static LanceCatalogClient client(LanceNamespace namespace, BufferAllocator allocator, Session session) {
         return new LanceCatalogClient(namespace, allocator, session, "filesystem", "default",
                 Collections.emptyList(), Collections.emptyList(), Collections.emptyMap(), Collections.emptyList());
diff --git a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceManagedVersioningTest.java b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceManagedVersioningTest.java
index 6d5da9f669c..d1ec70c0643 100644
--- a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceManagedVersioningTest.java
+++ b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceManagedVersioningTest.java
@@ -391,6 +391,75 @@ public class LanceManagedVersioningTest {
         }
     }
 
+    /** The search entry points take the same selectors, under the same namespace rules. */
+    @Test
+    public void testSearchMetadataOfManagedTableFollowsTheSelector() throws Exception {
+        LanceExternalCatalog catalog = newCatalog(329, "lance_managed_search");
+        try {
+            for (boolean withIndexes : new boolean[] {true, false}) {
+                java.util.function.Function<LanceRefSelector, LanceTableMetadata> load = selector -> withIndexes
+                        ? catalog.loadTableMetadataForSearch("default", FULL_TABLE, selector)
+                        : catalog.loadBasicTableMetadata("default", FULL_TABLE, selector);
+                LanceTableMetadata latest = load.apply(LanceRefSelector.latest());
+                Assertions.assertTrue(latest.isManagedVersioning());
+                Assertions.assertEquals(3, latest.getVersion());
+                Assertions.assertEquals(2, load.apply(LanceRefSelector.snapshot(
+                        Optional.of(TableSnapshot.versionOf("2")))).getVersion());
+                Assertions.assertEquals(2, load.apply(LanceRefSelector.tag("v2")).getVersion());
+                String betweenSecondAndThird = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS")
+                        .withZone(TimeUtils.getTimeZone().toZoneId())
+                        .format(datasetVersions.get(1).getDataTime().toInstant().plusMillis(1));
+                Assertions.assertEquals(2, load.apply(LanceRefSelector.snapshot(
+                        Optional.of(TableSnapshot.timeOf(betweenSecondAndThird)))).getVersion());
+
+                LanceTableMetadata branch = load.apply(LanceRefSelector.branch(BRANCH, Optional.empty()));
+                Assertions.assertEquals(Optional.of(BRANCH), branch.getBranch());
+                Assertions.assertEquals(branchVersions, branch.getVersion());
+                Assertions.assertTrue(branch.isManagedVersioning());
+                LanceTableMetadata branchTag = load.apply(LanceRefSelector.tag(BRANCH_TAG));
+                Assertions.assertEquals(Optional.of(BRANCH), branchTag.getBranch());
+                Assertions.assertEquals(3, branchTag.getVersion());
+                // main is the table root, not a branch named main.
+                LanceTableMetadata main = load.apply(LanceRefSelector.branch(LanceRefSelector.MAIN_BRANCH,
+                        Optional.of(TableSnapshot.versionOf("2"))));
+                Assertions.assertFalse(main.getBranch().isPresent());
+                Assertions.assertEquals(2, main.getVersion());
+            }
+            // A version the namespace does not record fails; it never falls back to the latest one.
+            RuntimeException unrecorded = Assertions.assertThrows(RuntimeException.class,
+                    () -> catalog.loadTableMetadataForSearch("default", PARTIAL_TABLE,
+                            LanceRefSelector.snapshot(Optional.of(TableSnapshot.versionOf("2")))));
+            Assertions.assertEquals(
+                    "Lance version 2 of default." + PARTIAL_TABLE + " was not found in the namespace",
+                    unrecorded.getMessage());
+            // A head whose commit was never finalized cannot be searched, on main or on a branch,
+            // and nothing falls back to an older version.
+            RuntimeException pending = Assertions.assertThrows(RuntimeException.class,
+                    () -> catalog.loadTableMetadataForSearch("default", PENDING_HEAD_TABLE, LanceRefSelector.latest()));
+            Assertions.assertEquals("Lance version 4 of default." + PENDING_HEAD_TABLE + STAGED_ONLY,
+                    pending.getMessage());
+            RuntimeException pendingBranch = Assertions.assertThrows(RuntimeException.class,
+                    () -> catalog.loadBasicTableMetadata("default", PENDING_HEAD_TABLE,
+                            LanceRefSelector.branch(BRANCH, Optional.empty())));
+            Assertions.assertEquals("Lance version 4 of default." + PENDING_HEAD_TABLE + "@" + BRANCH + STAGED_ONLY,
+                    pendingBranch.getMessage());
+            Assertions.assertEquals(3, catalog.loadTableMetadataForSearch("default", PENDING_HEAD_TABLE,
+                    LanceRefSelector.snapshot(Optional.of(TableSnapshot.versionOf("3")))).getVersion());
+            // A managed branch is opened by a URI Doris joins, so a name that would climb out of the
+            // table's tree/ directory is rejected before the branch's versions are requested.
+            requestPaths.clear();
+            RuntimeException climbing = Assertions.assertThrows(RuntimeException.class,
+                    () -> catalog.loadTableMetadataForSearch("default", FULL_TABLE,
+                            LanceRefSelector.branch("../../" + PLAIN_TABLE, Optional.empty())));
+            Assertions.assertTrue(climbing.getMessage().startsWith("Invalid Lance branch name '../../"),
+                    climbing.getMessage());
+            Assertions.assertTrue(requestPaths.stream().noneMatch(path -> path.contains("/version/")),
+                    requestPaths.toString());
+        } finally {
+            catalog.onClose();
+        }
+    }
+
     @Test
     public void testVersionMissingFromNamespaceIsReported() {
         LanceExternalCatalog catalog = newCatalog(301, "lance_managed_partial");
@@ -421,7 +490,8 @@ public class LanceManagedVersioningTest {
             RuntimeException dropped = Assertions.assertThrows(RuntimeException.class,
                     () -> catalog.loadTableMetadata("default", PARTIAL_TABLE,
                             Optional.of(new TableSnapshot(betweenSecondAndThird, TableSnapshot.VersionType.TIME))));
-            Assertions.assertEquals("Lance cannot resolve FOR TIME AS OF '" + betweenSecondAndThird + "' on default."
+            Assertions.assertEquals("Lance cannot select the version at or before '"
+                    + betweenSecondAndThird + "' on default."
                     + PARTIAL_TABLE + ": version 2, which may hold the state at that time, no longer exists",
                     dropped.getMessage());
             Assertions.assertTrue(requestPaths.stream().anyMatch(
@@ -537,7 +607,7 @@ public class LanceManagedVersioningTest {
             RuntimeException byTime = Assertions.assertThrows(RuntimeException.class,
                     () -> catalog.loadTableMetadata("default", PENDING_HEAD_TABLE,
                             Optional.of(new TableSnapshot("2100-01-01 00:00:00", TableSnapshot.VersionType.TIME))));
-            Assertions.assertEquals("Lance cannot resolve FOR TIME AS OF '2100-01-01 00:00:00' on default."
+            Assertions.assertEquals("Lance cannot select the version at or before '2100-01-01 00:00:00' on default."
                     + PENDING_HEAD_TABLE + ": version 4, which may hold the state at that time," + STAGED_ONLY,
                     byTime.getMessage());
             Assertions.assertEquals(3, catalog.loadTableMetadata("default", PENDING_HEAD_TABLE,
@@ -564,7 +634,7 @@ public class LanceManagedVersioningTest {
                     () -> catalog.loadTableMetadata("default", PENDING_HEAD_TABLE,
                             LanceRefSelector.branch(BRANCH, Optional.of(new TableSnapshot("2100-01-01 00:00:00",
                                     TableSnapshot.VersionType.TIME)))));
-            Assertions.assertEquals("Lance cannot resolve FOR TIME AS OF '2100-01-01 00:00:00' on default."
+            Assertions.assertEquals("Lance cannot select the version at or before '2100-01-01 00:00:00' on default."
                     + PENDING_HEAD_TABLE + "@" + BRANCH + ": version 4, which may hold the state at that time,"
                     + STAGED_ONLY, devByTime.getMessage());
         } finally {
@@ -952,7 +1022,8 @@ public class LanceManagedVersioningTest {
             RuntimeException removed = Assertions.assertThrows(RuntimeException.class,
                     () -> catalog.loadTableMetadata("default", STAGED_UNTIMED_TABLE,
                             Optional.of(new TableSnapshot(betweenFirstAndSecond, TableSnapshot.VersionType.TIME))));
-            Assertions.assertEquals("Lance cannot resolve FOR TIME AS OF '" + betweenFirstAndSecond + "' on default."
+            Assertions.assertEquals("Lance cannot select the version at or before '"
+                    + betweenFirstAndSecond + "' on default."
                     + STAGED_UNTIMED_TABLE + ": version 1, which may hold the state at that time," + STAGED_ONLY,
                     removed.getMessage());
             RuntimeException byVersion = Assertions.assertThrows(RuntimeException.class,
@@ -995,7 +1066,8 @@ public class LanceManagedVersioningTest {
                 RuntimeException gap = Assertions.assertThrows(RuntimeException.class,
                         () -> catalog.loadTableMetadata("default", table,
                                 Optional.of(new TableSnapshot(betweenFirstAndThird, TableSnapshot.VersionType.TIME))));
-                Assertions.assertEquals("Lance cannot resolve FOR TIME AS OF '" + betweenFirstAndThird + "' on default."
+                Assertions.assertEquals("Lance cannot select the version at or before '"
+                        + betweenFirstAndThird + "' on default."
                         + table + ": version 2, which may hold the state at that time, no longer exists",
                         gap.getMessage());
                 Assertions.assertEquals(3, catalog.loadTableMetadata("default", table,
diff --git a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceSearchSnapshotTest.java b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceSearchSnapshotTest.java
new file mode 100644
index 00000000000..1b043db7383
--- /dev/null
+++ b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/LanceSearchSnapshotTest.java
@@ -0,0 +1,506 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.apache.doris.datasource.lance;
+
+import org.apache.doris.analysis.TableSnapshot;
+import org.apache.doris.analysis.TupleDescriptor;
+import org.apache.doris.analysis.TupleId;
+import org.apache.doris.catalog.TableIf;
+import org.apache.doris.common.UserException;
+import org.apache.doris.datasource.lance.metadata.LanceFragmentInfo;
+import org.apache.doris.datasource.lance.metadata.LanceRefSelector;
+import org.apache.doris.datasource.lance.metadata.LanceTableMetadata;
+import org.apache.doris.datasource.lance.source.LanceScanNode;
+import org.apache.doris.datasource.lance.source.LanceSplit;
+import org.apache.doris.planner.PlanNodeId;
+import org.apache.doris.qe.SessionVariable;
+import org.apache.doris.spi.Split;
+import org.apache.doris.thrift.TExplainLevel;
+import org.apache.doris.thrift.TExternalSearchQuery;
+import org.apache.doris.thrift.TExternalSearchRequest;
+import org.apache.doris.thrift.TFtsCoverageMode;
+import org.apache.doris.thrift.TFtsMatchOperator;
+import org.apache.doris.thrift.TFtsQueryType;
+import org.apache.doris.thrift.TFullTextSearchParams;
+import org.apache.doris.thrift.TVectorSearchParams;
+
+import org.apache.arrow.memory.BufferAllocator;
+import org.apache.arrow.memory.RootAllocator;
+import org.apache.arrow.vector.BigIntVector;
+import org.apache.arrow.vector.Float4Vector;
+import org.apache.arrow.vector.VarCharVector;
+import org.apache.arrow.vector.VectorSchemaRoot;
+import org.apache.arrow.vector.complex.FixedSizeListVector;
+import org.apache.arrow.vector.types.FloatingPointPrecision;
+import org.apache.arrow.vector.types.pojo.ArrowType;
+import org.apache.arrow.vector.types.pojo.Field;
+import org.apache.arrow.vector.types.pojo.FieldType;
+import org.apache.arrow.vector.types.pojo.Schema;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestInstance;
+import org.lance.Dataset;
+import org.lance.Fragment;
+import org.lance.FragmentMetadata;
+import org.lance.FragmentOperation;
+import org.lance.ReadOptions;
+import org.lance.Ref;
+import org.lance.WriteParams;
+import org.lance.cleanup.CleanupPolicy;
+import org.lance.index.DistanceType;
+import org.lance.index.IndexParams;
+import org.lance.index.IndexType;
+import org.lance.index.scalar.ScalarIndexParams;
+import org.lance.index.vector.VectorIndexParams;
+import org.lance.schema.ColumnAlteration;
+import org.mockito.Mockito;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.TreeSet;
+import java.util.stream.Collectors;
+
+/**
+ * Search metadata and planning on historical versions, tags and branches of a real dataset.
+ *
+ * <p>Main: v1 is empty; v2 adds fragment 0 (ids 0..9); v3 fragment 1 (ids 10..19); v4 a vector
+ * index over both; v5 an FTS index over both; v6 fragment 2 (ids 20..29), which neither index
+ * covers. Tag {@code rel} points at main v6. Branch {@code dev} forks from v5 and appends ids
+ * 100..109 as its own v6. A branch continues its parent's fragment numbering, so dev v6 and main
+ * v6 both hold fragments 0, 1 and 2, with a different fragment 2. Tag {@code dev_rel} points at
+ * dev v5, the fork point, which is not the branch's latest version.
+ */
+@Disabled("Re-enable after fixing Arrow C Data JNI compatibility: CI libstdc++ lacks CXXABI_1.3.9")
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+public class LanceSearchSnapshotTest {
+    private static final String BRANCH = "dev";
+    private static final Schema SCHEMA = new Schema(Arrays.asList(
+            Field.nullable("id", new ArrowType.Int(64, true)),
+            new Field("vec", FieldType.nullable(new ArrowType.FixedSizeList(2)), Collections.singletonList(
+                    Field.nullable("item", new ArrowType.FloatingPoint(FloatingPointPrecision.SINGLE)))),
+            Field.nullable("body", ArrowType.Utf8.INSTANCE)));
+
+    private Path warehouse;
+    private String uri;
+    private LanceExternalCatalog catalog;
+
+    @BeforeAll
+    public void setUp() throws Exception {
+        LanceJniTestSupport.assumeJniBindingsLoadable();
+        warehouse = Files.createTempDirectory("lance_search_snapshot");
+        uri = warehouse.resolve("docs.lance").toString();
+        try (BufferAllocator allocator = new RootAllocator()) {
+            WriteParams params = new WriteParams.Builder().withDataStorageVersion("2.0").build();
+            try (Dataset created = Dataset.create(allocator, uri, SCHEMA, params)) {
+                Assertions.assertEquals(1, created.version());
+            }
+            Assertions.assertEquals(2, append(uri, allocator, 1, 0, 10));
+            Assertions.assertEquals(3, append(uri, allocator, 2, 10, 10));
+            try (Dataset dataset = Dataset.open(uri, allocator)) {
+                dataset.createIndex(Collections.singletonList("vec"), IndexType.IVF_FLAT, Optional.of("vec_idx"),
+                        IndexParams.builder().setVectorIndexParams(VectorIndexParams.ivfFlat(2, DistanceType.L2))
+                                .build(), false);
+                Assertions.assertEquals(4, dataset.version());
+                dataset.createIndex(Collections.singletonList("body"), IndexType.INVERTED, Optional.of("body_idx"),
+                        IndexParams.builder().setScalarIndexParams(ScalarIndexParams.create("inverted",
+                                "{\"base_tokenizer\":\"simple\",\"language\":\"English\",\"lower_case\":true,"
+                                        + "\"stem\":false,\"remove_stop_words\":false}")).build(), false);
+                Assertions.assertEquals(5, dataset.version());
+            }
+            Assertions.assertEquals(6, append(uri, allocator, 5, 20, 10));
+            try (Dataset dataset = Dataset.open(uri, allocator)) {
+                dataset.tags().create("rel", 6);
+                try (Dataset branch = dataset.createBranch(BRANCH, Ref.ofMain(5))) {
+                    Assertions.assertEquals(5, branch.version());
+                }
+                Assertions.assertEquals(6, append(uri + "/tree/" + BRANCH, allocator, 5, 100, 10));
+                dataset.tags().create("dev_rel", 5, BRANCH);
+            }
+        }
+        Map<String, String> properties = new HashMap<>();
+        properties.put("type", "lance");
+        properties.put(LanceExternalCatalog.WAREHOUSE, warehouse.toString());
+        catalog = new LanceExternalCatalog(910, "lance_search_snapshot", null, properties, "");
+    }
+
+    @AfterAll
+    public void tearDown() throws Exception {
+        if (catalog != null) {
+            catalog.onClose();
+        }
+        if (warehouse != null) {
+            try (java.util.stream.Stream<Path> paths = Files.walk(warehouse)) {
+                paths.sorted(java.util.Comparator.reverseOrder()).forEach(path -> path.toFile().delete());
+            }
+        }
+    }
+
+    /** Appends one fragment with ids {@code first..first+count-1} and returns the committed version. */
+    private static long append(String datasetUri, BufferAllocator allocator, long readVersion, long first, int count)
+            throws Exception {
+        WriteParams params = new WriteParams.Builder().withDataStorageVersion("2.0").build();
+        try (VectorSchemaRoot root = VectorSchemaRoot.create(SCHEMA, allocator)) {
+            BigIntVector id = (BigIntVector) root.getVector("id");
+            FixedSizeListVector vec = (FixedSizeListVector) root.getVector("vec");
+            VarCharVector body = (VarCharVector) root.getVector("body");
+            id.allocateNew(count);
+            vec.allocateNew();
+            Float4Vector items = (Float4Vector) vec.getDataVector();
+            items.allocateNew(count * 2);
+            body.allocateNew(count);
+            for (int i = 0; i < count; i++) {
+                long value = first + i;
+                id.set(i, value);
+                vec.setNotNull(i);
+                items.set(i * 2, value);
+                items.set(i * 2 + 1, -value);
+                body.setSafe(i, ("doc " + value + (value % 2 == 0 ? " lance" : " doris"))
+                        .getBytes(StandardCharsets.UTF_8));
+            }
+            id.setValueCount(count);
+            items.setValueCount(count * 2);
+            vec.setValueCount(count);
+            body.setValueCount(count);
+            root.setRowCount(count);
+            List<FragmentMetadata> fragments = Fragment.create(datasetUri, allocator, root, params);
+            try (Dataset committed = new FragmentOperation.Append(fragments)
+                    .commit(allocator, datasetUri, Optional.of(readVersion), Collections.emptyMap())) {
+                return committed.version();
+            }
+        }
+    }
+
+    private LanceTableMetadata search(LanceRefSelector selector) {
+        return catalog.loadTableMetadataForSearch("default", "docs", selector);
+    }
+
+    private static LanceRefSelector version(long version) {
+        return LanceRefSelector.snapshot(Optional.of(TableSnapshot.versionOf(String.valueOf(version))));
+    }
+
+    private static Set<Long> fragments(LanceTableMetadata metadata) {
+        return metadata.getFragments().stream().map(LanceFragmentInfo::getId)
+                .collect(Collectors.toCollection(TreeSet::new));
+    }
+
+    private static LanceScanNode node(LanceTableMetadata metadata, TExternalSearchRequest request, int fieldId) {
+        TupleDescriptor desc = new TupleDescriptor(new TupleId(0));
+        desc.setTable(Mockito.mock(TableIf.class));
+        LanceExternalCatalog lanceCatalog = Mockito.mock(LanceExternalCatalog.class);
+        Mockito.when(lanceCatalog.getLanceCatalogType()).thenReturn("filesystem");
+        LanceExternalTable table = Mockito.mock(LanceExternalTable.class);
+        Mockito.when(table.getCatalog()).thenReturn(lanceCatalog);
+        return LanceScanNode.forExternalSearch(new PlanNodeId(0), desc, table, metadata, fieldId, request,
+                new SessionVariable());
+    }
+
+    private static List<LanceSplit> vectorSplits(LanceTableMetadata metadata) throws UserException {
+        return vectorSplits(metadata, "vec");
+    }
+
+    private static List<LanceSplit> vectorSplits(LanceTableMetadata metadata, String column) throws UserException {
+        TVectorSearchParams vector = new TVectorSearchParams().setColumn(column).setTopK(5).setOffset(0);
+        LanceScanNode node = node(metadata, new TExternalSearchRequest()
+                .setSearchQuery(TExternalSearchQuery.vector_search(vector)),
+                metadata.getLanceFieldId(column).getAsInt());
+        List<LanceSplit> splits = new ArrayList<>();
+        for (Split split : node.getSplits(1)) {
+            splits.add((LanceSplit) split);
+        }
+        return splits;
+    }
+
+    private static List<LanceSplit> fullTextSplits(LanceTableMetadata metadata, TFtsCoverageMode mode)
+            throws UserException {
+        TFullTextSearchParams fullText = new TFullTextSearchParams().setColumn("body").setQuery("lance")
+                .setTopK(5).setOffset(0).setCoverageMode(mode).setQueryType(TFtsQueryType.MATCH)
+                .setMatchOperator(TFtsMatchOperator.OR).setMaxFuzzyDistance(0);
+        LanceScanNode node = node(metadata, new TExternalSearchRequest()
+                .setSearchQuery(TExternalSearchQuery.full_text_search(fullText)),
+                metadata.getLanceFieldId("body").getAsInt());
+        List<LanceSplit> splits = new ArrayList<>();
+        for (Split split : node.getSplits(1)) {
+            splits.add((LanceSplit) split);
+        }
+        return splits;
+    }
+
+    private static long indexedFragments(List<LanceSplit> splits) {
+        return splits.stream().filter(split -> split.getIndexSegmentUuid().isPresent())
+                .mapToLong(split -> split.getFragmentIds().size()).sum();
+    }
+
+    private static long flatFragments(List<LanceSplit> splits) {
+        return splits.stream().filter(split -> !split.getIndexSegmentUuid().isPresent())
+                .mapToLong(split -> split.getFragmentIds().size()).sum();
+    }
+
+    @Test
+    public void testNoSelectorSearchesLatestMain() throws Exception {
+        LanceTableMetadata latest = search(LanceRefSelector.latest());
+        Assertions.assertEquals(6, latest.getVersion());
+        Assertions.assertFalse(latest.getBranch().isPresent());
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList(0L, 1L, 2L)), fragments(latest));
+    }
+
+    @Test
+    public void testVersionBeforeAnyIndexFallsBackToFlatVectorSearchAndRejectsFullText() throws Exception {
+        LanceTableMetadata v3 = search(version(3));
+        Assertions.assertEquals(3, v3.getVersion());
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList(0L, 1L)), fragments(v3));
+        List<LanceSplit> splits = vectorSplits(v3);
+        Assertions.assertEquals(0, indexedFragments(splits));
+        Assertions.assertEquals(2, flatFragments(splits));
+        splits.forEach(split -> Assertions.assertEquals(3, split.getVersion()));
+        UserException exception = Assertions.assertThrows(UserException.class,
+                () -> fullTextSplits(v3, TFtsCoverageMode.INDEX_ONLY));
+        Assertions.assertTrue(exception.getMessage().contains(
+                "No committed Lance FTS index exists for column 'body' at dataset version 3"),
+                exception.getMessage());
+    }
+
+    @Test
+    public void testVersionWithVectorIndexButNoFullTextIndex() throws Exception {
+        LanceTableMetadata v4 = search(version(4));
+        List<LanceSplit> splits = vectorSplits(v4);
+        Assertions.assertEquals(2, indexedFragments(splits));
+        Assertions.assertEquals(0, flatFragments(splits));
+        Assertions.assertThrows(UserException.class, () -> fullTextSplits(v4, TFtsCoverageMode.INDEX_ONLY));
+        Assertions.assertEquals(2, indexedFragments(fullTextSplits(search(version(5)), TFtsCoverageMode.STRICT)));
+    }
+
+    @Test
+    public void testAppendAfterIndexingCoversPartially() throws Exception {
+        LanceTableMetadata v6 = search(version(6));
+        List<LanceSplit> vector = vectorSplits(v6);
+        Assertions.assertEquals(2, indexedFragments(vector));
+        Assertions.assertEquals(1, flatFragments(vector));
+        UserException strict = Assertions.assertThrows(UserException.class,
+                () -> fullTextSplits(v6, TFtsCoverageMode.STRICT));
+        Assertions.assertTrue(strict.getMessage().contains("every fragment at dataset version 6 to be indexed"),
+                strict.getMessage());
+        List<LanceSplit> indexOnly = fullTextSplits(v6, TFtsCoverageMode.INDEX_ONLY);
+        Assertions.assertEquals(2, indexedFragments(indexOnly));
+        Assertions.assertEquals(0, flatFragments(indexOnly));
+    }
+
+    @Test
+    public void testTagSelectsItsVersion() throws Exception {
+        LanceTableMetadata tagged = search(LanceRefSelector.tag("rel"));
+        Assertions.assertEquals(6, tagged.getVersion());
+        Assertions.assertFalse(tagged.getBranch().isPresent());
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList(0L, 1L, 2L)), fragments(tagged));
+    }
+
+    @Test
+    public void testBranchVersionsOverlapMainWithDifferentData() throws Exception {
+        LanceTableMetadata dev = search(LanceRefSelector.branch(BRANCH, Optional.empty()));
+        Assertions.assertEquals(6, dev.getVersion());
+        Assertions.assertEquals(Optional.of(BRANCH), dev.getBranch());
+        Assertions.assertTrue(dev.getDatasetUri().endsWith("/tree/" + BRANCH), dev.getDatasetUri());
+        // Same version number and fragment ids as main v6, different rows.
+        Assertions.assertEquals(fragments(search(version(6))), fragments(dev));
+        Assertions.assertEquals(10, count(dev.getDatasetUri(), 6, "id >= 100"));
+        Assertions.assertEquals(0, count(uri, 6, "id >= 100"));
+        // Inherited indexes cover the fork point's fragments; the branch's own append is flat.
+        List<LanceSplit> vector = vectorSplits(dev);
+        Assertions.assertEquals(2, indexedFragments(vector));
+        Assertions.assertEquals(1, flatFragments(vector));
+        vector.forEach(split -> {
+            Assertions.assertEquals(6, split.getVersion());
+            Assertions.assertEquals(dev.getDatasetUri(), split.getDatasetUri());
+        });
+        UserException strict = Assertions.assertThrows(UserException.class,
+                () -> fullTextSplits(dev, TFtsCoverageMode.STRICT));
+        Assertions.assertTrue(strict.getMessage().contains("dataset version 6 of branch 'dev'"), strict.getMessage());
+
+        LanceTableMetadata fork = search(LanceRefSelector.branch(BRANCH, Optional.of(TableSnapshot.versionOf("5"))));
+        Assertions.assertEquals(5, fork.getVersion());
+        Assertions.assertEquals(Optional.of(BRANCH), fork.getBranch());
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList(0L, 1L)), fragments(fork));
+        Assertions.assertEquals(2, indexedFragments(fullTextSplits(fork, TFtsCoverageMode.STRICT)));
+    }
+
+    @Test
+    public void testTagOnBranchSelectsTheBranch() throws Exception {
+        // A tag at a version of the branch other than its latest: Lance's with_tag on the branch
+        // URI fails for this (lance#9227), and Doris resolves it through the table root instead.
+        LanceTableMetadata tagged = search(LanceRefSelector.tag("dev_rel"));
+        Assertions.assertEquals(5, tagged.getVersion());
+        Assertions.assertEquals(Optional.of(BRANCH), tagged.getBranch());
+        Assertions.assertTrue(tagged.getDatasetUri().endsWith("/tree/" + BRANCH), tagged.getDatasetUri());
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList(0L, 1L)), fragments(tagged));
+    }
+
+    @Test
+    public void testMainBranchIsTheTableRoot() throws Exception {
+        LanceTableMetadata main = search(LanceRefSelector.branch(LanceRefSelector.MAIN_BRANCH,
+                Optional.of(TableSnapshot.versionOf("4"))));
+        Assertions.assertEquals(4, main.getVersion());
+        Assertions.assertFalse(main.getBranch().isPresent());
+        Assertions.assertFalse(main.getDatasetUri().contains("/tree/"), main.getDatasetUri());
+    }
+
+    @Test
+    public void testTimestamps() throws Exception {
+        Assertions.assertEquals(6, search(LanceRefSelector.snapshot(
+                Optional.of(TableSnapshot.timeOf("2999-01-01 00:00:00")))).getVersion());
+        Assertions.assertEquals(6, search(LanceRefSelector.branch(BRANCH,
+                Optional.of(TableSnapshot.timeOf("2999-01-01 00:00:00")))).getVersion());
+        RuntimeException early = Assertions.assertThrows(RuntimeException.class, () -> search(
+                LanceRefSelector.snapshot(Optional.of(TableSnapshot.timeOf("2000-01-01 00:00:00")))));
+        Assertions.assertTrue(early.getMessage().contains("has no version at or before '2000-01-01 00:00:00'"),
+                early.getMessage());
+    }
+
+    @Test
+    public void testMissingSnapshotsFailWithoutFallingBackToLatest() {
+        RuntimeException version = Assertions.assertThrows(RuntimeException.class, () -> search(version(99)));
+        Assertions.assertTrue(version.getMessage().contains("Lance version 99 of default.docs was not found"),
+                version.getMessage());
+        RuntimeException tag = Assertions.assertThrows(RuntimeException.class,
+                () -> search(LanceRefSelector.tag("nope")));
+        Assertions.assertTrue(tag.getMessage().contains("Lance tag 'nope'"), tag.getMessage());
+        RuntimeException branch = Assertions.assertThrows(RuntimeException.class,
+                () -> search(LanceRefSelector.branch("nope", Optional.empty())));
+        Assertions.assertTrue(branch.getMessage().contains("Lance branch 'nope'"), branch.getMessage());
+        RuntimeException branchVersion = Assertions.assertThrows(RuntimeException.class,
+                () -> search(LanceRefSelector.branch(BRANCH, Optional.of(TableSnapshot.versionOf("99")))));
+        Assertions.assertTrue(branchVersion.getMessage().contains("Lance version 99"), branchVersion.getMessage());
+    }
+
+    @Test
+    public void testPlannedSnapshotSurvivesLaterCommits() throws Exception {
+        String pinnedUri = warehouse.resolve("pinned.lance").toString();
+        try (BufferAllocator allocator = new RootAllocator()) {
+            try (Dataset created = Dataset.create(allocator, pinnedUri, SCHEMA,
+                    new WriteParams.Builder().withDataStorageVersion("2.0").build())) {
+                Assertions.assertEquals(1, created.version());
+            }
+            append(pinnedUri, allocator, 1, 0, 10);
+            try (Dataset dataset = Dataset.open(pinnedUri, allocator)) {
+                dataset.tags().create("moving", 2);
+            }
+            LanceTableMetadata planned = catalog.loadTableMetadataForSearch("default", "pinned",
+                    LanceRefSelector.tag("moving"));
+            Assertions.assertEquals(2, planned.getVersion());
+            // A commit and a tag move after planning do not reach the planned splits.
+            append(pinnedUri, allocator, 2, 10, 10);
+            try (Dataset dataset = Dataset.open(pinnedUri, allocator)) {
+                dataset.tags().update("moving", 3);
+            }
+            List<LanceSplit> splits = vectorSplits(planned);
+            splits.forEach(split -> Assertions.assertEquals(2, split.getVersion()));
+            Assertions.assertEquals(1, flatFragments(splits));
+            // The next resolution sees the moved tag.
+            Assertions.assertEquals(3, catalog.loadTableMetadataForSearch("default", "pinned",
+                    LanceRefSelector.tag("moving")).getVersion());
+        }
+    }
+
+    /**
+     * Each version keeps its own schema: a column added later is absent from older versions, and
+     * a renamed column keeps its field id, so the index built before the rename still serves it.
+     */
+    @Test
+    public void testSchemaFollowsTheSelectedVersion() throws Exception {
+        String schemaUri = warehouse.resolve("evolving.lance").toString();
+        try (BufferAllocator allocator = new RootAllocator()) {
+            try (Dataset created = Dataset.create(allocator, schemaUri, SCHEMA,
+                    new WriteParams.Builder().withDataStorageVersion("2.0").build())) {
+                Assertions.assertEquals(1, created.version());
+            }
+            Assertions.assertEquals(2, append(schemaUri, allocator, 1, 0, 10));
+            try (Dataset dataset = Dataset.open(schemaUri, allocator)) {
+                dataset.createIndex(Collections.singletonList("vec"), IndexType.IVF_FLAT, Optional.of("vec_idx"),
+                        IndexParams.builder().setVectorIndexParams(VectorIndexParams.ivfFlat(2, DistanceType.L2))
+                                .build(), false);
+                dataset.addColumns(Collections.singletonList(Field.nullable("note", ArrowType.Utf8.INSTANCE)));
+                dataset.alterColumns(Collections.singletonList(
+                        new ColumnAlteration.Builder("vec").rename("embedding").build()));
+                Assertions.assertEquals(5, dataset.version());
+            }
+        }
+        LanceTableMetadata v3 = catalog.loadTableMetadataForSearch("default", "evolving", version(3));
+        LanceTableMetadata v5 = catalog.loadTableMetadataForSearch("default", "evolving", version(5));
+        Set<String> v3Columns = v3.getSchema().getFields().stream().map(Field::getName).collect(Collectors.toSet());
+        Set<String> v5Columns = v5.getSchema().getFields().stream().map(Field::getName).collect(Collectors.toSet());
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList("id", "vec", "body")), new TreeSet<>(v3Columns));
+        Assertions.assertEquals(new TreeSet<>(Arrays.asList("id", "embedding", "body", "note")),
+                new TreeSet<>(v5Columns));
+        Assertions.assertFalse(v3.getLanceFieldId("note").isPresent());
+        Assertions.assertEquals(v3.getLanceFieldId("vec").getAsInt(), v5.getLanceFieldId("embedding").getAsInt());
+        Assertions.assertEquals(1, indexedFragments(vectorSplits(v3, "vec")));
+        Assertions.assertEquals(1, indexedFragments(vectorSplits(v5, "embedding")));
+    }
+
+    @Test
+    public void testVersionRemovedByCleanupIsNotFound() throws Exception {
+        String cleanedUri = warehouse.resolve("cleaned.lance").toString();
+        try (BufferAllocator allocator = new RootAllocator()) {
+            try (Dataset created = Dataset.create(allocator, cleanedUri, SCHEMA,
+                    new WriteParams.Builder().withDataStorageVersion("2.0").build())) {
+                Assertions.assertEquals(1, created.version());
+            }
+            append(cleanedUri, allocator, 1, 0, 10);
+            append(cleanedUri, allocator, 2, 10, 10);
+            try (Dataset dataset = Dataset.open(cleanedUri, allocator)) {
+                dataset.cleanupWithPolicy(CleanupPolicy.builder().withBeforeVersion(3)
+                        .withDeleteUnverified(true).build());
+            }
+        }
+        RuntimeException removed = Assertions.assertThrows(RuntimeException.class,
+                () -> catalog.loadTableMetadataForSearch("default", "cleaned", version(2)));
+        Assertions.assertTrue(removed.getMessage().contains("Lance version 2 of default.cleaned was not found"),
+                removed.getMessage());
+        Assertions.assertEquals(3, catalog.loadTableMetadataForSearch("default", "cleaned", version(3)).getVersion());
+    }
+
+    @Test
+    public void testSearchExplainNamesBranch() throws Exception {
+        LanceTableMetadata dev = search(LanceRefSelector.branch(BRANCH, Optional.empty()));
+        TVectorSearchParams vector = new TVectorSearchParams().setColumn("vec").setTopK(5).setOffset(0);
+        LanceScanNode node = node(dev, new TExternalSearchRequest()
+                .setSearchQuery(TExternalSearchQuery.vector_search(vector)), dev.getLanceFieldId("vec").getAsInt());
+        node.getSplits(1);
+        String explain = node.getNodeExplainString("", TExplainLevel.NORMAL);
+        Assertions.assertTrue(explain.contains("lanceVersion=6\n"), explain);
+        Assertions.assertTrue(explain.contains("lanceBranch=dev\n"), explain);
+        Assertions.assertTrue(explain.contains("lanceManagedVersioning=false\n"), explain);
+    }
+
+    private static long count(String datasetUri, long version, String filter) throws Exception {
+        try (BufferAllocator allocator = new RootAllocator();
+                Dataset dataset = Dataset.open(allocator, datasetUri,
+                        new ReadOptions.Builder().setVersion(version).build())) {
+            return dataset.countRows(filter);
+        }
+    }
+}
diff --git a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/source/LanceScanNodeTest.java b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/source/LanceScanNodeTest.java
index ac1f0f7218f..bd555d1dab3 100644
--- a/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/source/LanceScanNodeTest.java
+++ b/fe/fe-core/src/test/java/org/apache/doris/datasource/lance/source/LanceScanNodeTest.java
@@ -30,6 +30,8 @@ import org.apache.doris.common.UserException;
 import org.apache.doris.common.profile.RuntimeProfile;
 import org.apache.doris.common.profile.SummaryProfile;
 import org.apache.doris.datasource.FederationBackendPolicy;
+import org.apache.doris.datasource.lance.LanceExternalCatalog;
+import org.apache.doris.datasource.lance.LanceExternalTable;
 import org.apache.doris.datasource.lance.index.LanceIndexSegmentInfo;
 import org.apache.doris.datasource.lance.metadata.LanceFragmentInfo;
 import org.apache.doris.datasource.lance.metadata.LanceTableAccess;
@@ -1011,6 +1013,59 @@ public class LanceScanNodeTest {
                 "Lance fragment id must be non-negative");
     }
 
+    @Test
+    public void testExternalSearchExplainShowsSelectedSnapshot() throws Exception {
+        LanceTableAccess main = LanceTableAccess.managedByNamespace("s3://bucket/table.lance",
+                Collections.emptyMap(), Arrays.asList("db", "table"));
+        LanceTableAccess branch = main.onBranch("dev", "s3://bucket/table.lance/tree/dev");
+        for (LanceTableAccess access : Arrays.asList(main, branch)) {
+            LanceTableMetadata metadata = LanceTableMetadata.createSnapshotWithIndexes(
+                    access, 7, vectorSchema(), Collections.singletonList(new LanceFragmentInfo(1, 8, 8)),
+                    Collections.singletonMap("vector", 9), Collections.emptyList());
+            LanceScanNode node = newSearchNode(metadata, vectorSearchRequest(5, 0));
+            node.getSplits(1);
+            String explain = node.getNodeExplainString("", TExplainLevel.NORMAL);
+            Assert.assertTrue(explain, explain.contains("lanceCatalogType=rest\n"));
+            Assert.assertTrue(explain, explain.contains("lanceVersion=7\n"));
+            Assert.assertTrue(explain, explain.contains("lanceManagedVersioning=true\n"));
+            Assert.assertEquals(explain, access == branch, explain.contains("lanceBranch=dev\n"));
+        }
+    }
+
+    @Test
+    public void testExternalSearchErrorsNameTheBranch() {
+        LanceTableAccess branch = new LanceTableAccess("s3://bucket/table.lance", Collections.emptyMap())
+                .onBranch("dev", "s3://bucket/table.lance/tree/dev");
+        LanceTableMetadata metadata = LanceTableMetadata.createSnapshotWithIndexes(
+                branch, 7, fullTextSchema(), Collections.singletonList(new LanceFragmentInfo(1, 8, 8)),
+                Collections.singletonMap("body", 9), Collections.emptyList());
+        // Without an FTS index, and with duplicate fragment ids, the errors name the branch too.
+        for (TFtsCoverageMode mode : TFtsCoverageMode.values()) {
+            LanceScanNode node = newSearchNode(metadata, fullTextSearchRequest(5, 0, mode));
+            UserException exception = Assert.assertThrows(UserException.class, () -> node.getSplits(1));
+            Assert.assertTrue(exception.getMessage(), exception.getMessage().contains(
+                    "No committed Lance FTS index exists for column 'body' at dataset version 7 of branch 'dev'"));
+        }
+        LanceTableMetadata partial = LanceTableMetadata.createSnapshotWithIndexes(
+                branch, 7, fullTextSchema(),
+                Arrays.asList(new LanceFragmentInfo(1, 8, 8), new LanceFragmentInfo(2, 8, 8)),
+                Collections.singletonMap("body", 9),
+                Collections.singletonList(new LanceIndexSegmentInfo(UUID.randomUUID(), "body_fts",
+                        Collections.singletonList(9), Collections.singletonList(1L), IndexType.INVERTED, null)));
+        LanceScanNode strictNode = newSearchNode(partial, fullTextSearchRequest(5, 0, TFtsCoverageMode.STRICT));
+        UserException strict = Assert.assertThrows(UserException.class, () -> strictNode.getSplits(1));
+        Assert.assertTrue(strict.getMessage(), strict.getMessage().contains(
+                "requires every fragment at dataset version 7 of branch 'dev' to be indexed"));
+        LanceTableMetadata duplicate = LanceTableMetadata.createSnapshotWithIndexes(
+                branch, 7, vectorSchema(),
+                Arrays.asList(new LanceFragmentInfo(1, 8, 8), new LanceFragmentInfo(1, 8, 8)),
+                Collections.singletonMap("vector", 9), Collections.emptyList());
+        LanceScanNode node = newSearchNode(duplicate, vectorSearchRequest(5, 0));
+        UserException exception = Assert.assertThrows(UserException.class, () -> node.getSplits(1));
+        Assert.assertTrue(exception.getMessage(),
+                exception.getMessage().contains("Duplicate Lance fragment id 1 at dataset version 7 of branch 'dev'"));
+    }
+
     private static LanceScanNode newNode() {
         return newNode(new SessionVariable());
     }
@@ -1035,8 +1090,12 @@ public class LanceScanNodeTest {
         sessionVariable.lanceFragmentsPerSplit = 8;
         TupleDescriptor desc = new TupleDescriptor(new TupleId(0));
         desc.setTable(Mockito.mock(TableIf.class));
+        LanceExternalCatalog catalog = Mockito.mock(LanceExternalCatalog.class);
+        Mockito.when(catalog.getLanceCatalogType()).thenReturn("rest");
+        LanceExternalTable table = Mockito.mock(LanceExternalTable.class);
+        Mockito.when(table.getCatalog()).thenReturn(catalog);
         return LanceScanNode.forExternalSearch(
-                new PlanNodeId(0), desc, null,
+                new PlanNodeId(0), desc, table,
                 metadata, searchFieldId, request, sessionVariable);
     }
 
diff --git a/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LancePreparedSearchTest.java b/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LancePreparedSearchTest.java
index 20e72540a7f..074de75998f 100644
--- a/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LancePreparedSearchTest.java
+++ b/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LancePreparedSearchTest.java
@@ -23,10 +23,12 @@ import org.apache.doris.catalog.Env;
 import org.apache.doris.common.Pair;
 import org.apache.doris.common.jmockit.Deencapsulation;
 import org.apache.doris.datasource.lance.LanceExternalTable;
+import org.apache.doris.datasource.lance.metadata.LanceRefSelector;
 import org.apache.doris.datasource.lance.metadata.LanceTableAccess;
 import org.apache.doris.datasource.lance.metadata.LanceTableMetadata;
 import org.apache.doris.mysql.MysqlCommand;
 import org.apache.doris.nereids.CascadesContext;
+import org.apache.doris.nereids.SqlCacheContext;
 import org.apache.doris.nereids.StatementContext;
 import org.apache.doris.nereids.glue.LogicalPlanAdapter;
 import org.apache.doris.nereids.parser.NereidsParser;
@@ -224,6 +226,88 @@ public class LancePreparedSearchTest {
         }
     }
 
+    /**
+     * A constant selector is re-resolved by every EXECUTE: a tag moved between two executions
+     * selects its new version, and the selector itself is the same each time.
+     */
+    @ParameterizedTest
+    @ValueSource(booleans = {true, false})
+    public void testExecuteResolvesConstantSelectorAgain(boolean useIndex) {
+        ConnectContext previous = ConnectContext.get();
+        ConnectContext context = MemoTestUtils.createConnectContext();
+        AtomicLong version = new AtomicLong(42);
+        LanceExternalTable table = mockTable(version);
+        try (MockedStatic<LanceExternalSearchTableValuedFunction> lookup = Mockito.mockStatic(
+                LanceExternalSearchTableValuedFunction.class, Mockito.CALLS_REAL_METHODS)) {
+            lookup.when(() -> LanceExternalSearchTableValuedFunction.findLanceExternalTable(
+                    Mockito.any(TableName.class))).thenReturn(table);
+            Pair<LogicalPlan, StatementContext> parsed = new NereidsParser().parseMultiple(
+                    "select id, _distance from vector_search('table'='catalog.db.items', "
+                            + "'column'='embedding', 'use_index'='" + useIndex + "', 'tag'='release', "
+                            + "'query_vector'=?)").get(0);
+            StatementContext prepare = MemoTestUtils.createStatementContext(context, "");
+            prepare.setPrepareStage(true);
+            analyze(parsed.first, prepare);
+            // Each analysis resolves the selector exactly once; a second resolution within one
+            // execution could select a different version.
+            verifyResolvedOnceWithTag(table, "release");
+            Placeholder vector = parsed.second.getPlaceholders().get(0);
+            for (int i = 0; i < 2; i++) {
+                version.set(42 + i);
+                StatementContext execute = MemoTestUtils.createStatementContext(context, "");
+                execute.getIdToPlaceholderRealExpr().put(vector.getPlaceholderId(), new StringLiteral("[1,2]"));
+                Assertions.assertEquals(42 + i, analyze(parsed.first, execute).getMetadata().getVersion());
+                verifyResolvedOnceWithTag(table, "release");
+            }
+        } finally {
+            ConnectContext.remove();
+            if (previous != null) {
+                previous.setThreadLocalInfo();
+            }
+        }
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {"version", "timestamp", "tag", "branch"})
+    public void testSelectorMustBeConstantInPreparedStatement(String selector) {
+        ConnectContext previous = ConnectContext.get();
+        ConnectContext context = MemoTestUtils.createConnectContext();
+        context.setStatementContext(MemoTestUtils.createStatementContext(context, ""));
+        try {
+            Exception exception = Assertions.assertThrows(Exception.class,
+                    () -> new NereidsParser().parseMultiple(
+                            "select * from vector_search('table'='catalog.db.items', 'column'='embedding', "
+                                    + "'query_vector'='[1,2]', '" + selector + "'=?)"));
+            Assertions.assertTrue(exception.getMessage().contains(
+                    "vector_search property '" + selector + "' must be constant in a prepared statement"),
+                    exception.getMessage());
+            // Before this was rejected, full_text_search received the placeholder as the text "?".
+            for (String property : new String[] {"'" + selector + "'=?", "'top_k'=?", "?='x'"}) {
+                exception = Assertions.assertThrows(Exception.class,
+                        () -> new NereidsParser().parseMultiple(
+                                "select * from full_text_search('table'='catalog.db.items', 'column'='body', "
+                                        + "'query'='lance', " + property + ")"));
+                Assertions.assertTrue(exception.getMessage().contains(
+                        "full_text_search properties must be constant in a prepared statement"),
+                        exception.getMessage());
+            }
+        } finally {
+            ConnectContext.remove();
+            if (previous != null) {
+                previous.setThreadLocalInfo();
+            }
+        }
+    }
+
+    private static void verifyResolvedOnceWithTag(LanceExternalTable table, String tag) {
+        org.mockito.ArgumentCaptor<LanceRefSelector> selector =
+                org.mockito.ArgumentCaptor.forClass(LanceRefSelector.class);
+        // loadBasicMetadata delegates to loadMetadataForSearch in mockTable, so both modes count here.
+        Mockito.verify(table, Mockito.times(1)).loadMetadataForSearch(selector.capture());
+        Assertions.assertEquals(tag, selector.getValue().getTag().orElse(null));
+        Mockito.clearInvocations(table);
+    }
+
     private LanceExternalTable mockTable(AtomicLong version) {
         return mockTable(version, false);
     }
@@ -240,14 +324,122 @@ public class LancePreparedSearchTest {
                             vector.getChildren())));
         }
         Schema schema = new Schema(Arrays.asList(Field.nullable("id", new ArrowType.Int(64, true)), vector));
-        Mockito.when(table.loadMetadataForSearch()).thenAnswer(invocation -> LanceTableMetadata.createSnapshotWithIndexes(
-                new LanceTableAccess("s3://bucket/items.lance", Collections.emptyMap()),
-                version.get(), schema, Collections.emptyList(),
-                ImmutableMap.of("id", 0, "embedding", 1), Collections.emptyList()));
-        Mockito.when(table.loadBasicMetadata()).thenAnswer(invocation -> table.loadMetadataForSearch());
+        Mockito.when(table.loadMetadataForSearch(Mockito.any(LanceRefSelector.class))).thenAnswer(
+                invocation -> LanceTableMetadata.createSnapshotWithIndexes(
+                        new LanceTableAccess("s3://bucket/items.lance", Collections.emptyMap()),
+                        version.get(), schema, Collections.emptyList(),
+                        ImmutableMap.of("id", 0, "embedding", 1), Collections.emptyList()));
+        Mockito.when(table.loadBasicMetadata(Mockito.any(LanceRefSelector.class))).thenAnswer(
+                invocation -> table.loadMetadataForSearch(invocation.getArgument(0)));
+        return table;
+    }
+
+    /** Both search functions accept the selector properties and hand the table what they select. */
+    @org.junit.jupiter.api.Test
+    public void testBothSearchFunctionsPassTheirSelectorToTheTable() {
+        ConnectContext previous = ConnectContext.get();
+        ConnectContext context = MemoTestUtils.createConnectContext();
+        LanceExternalTable table = mockSearchTable();
+        String vector = "vector_search('table'='catalog.db.items', 'column'='embedding', 'query_vector'='[1,2]', ";
+        String text = "full_text_search('table'='catalog.db.items', 'column'='body', 'query'='lance', ";
+        try (MockedStatic<LanceExternalSearchTableValuedFunction> lookup = Mockito.mockStatic(
+                LanceExternalSearchTableValuedFunction.class, Mockito.CALLS_REAL_METHODS)) {
+            lookup.when(() -> LanceExternalSearchTableValuedFunction.findLanceExternalTable(
+                    Mockito.any(TableName.class))).thenReturn(table);
+            for (String useIndex : new String[] {"true", "false"}) {
+                String prefix = vector + "'use_index'='" + useIndex + "', ";
+                LanceRefSelector selector = selectorOf(table, prefix + "'VERSION'='3', 'Branch'='dev')", context);
+                Assertions.assertEquals("dev", selector.getBranch().orElse(null));
+                Assertions.assertEquals("3", selector.getSnapshot().get().getValue());
+                selector = selectorOf(table, prefix + "'tag'='rel')", context);
+                Assertions.assertEquals("rel", selector.getTag().orElse(null));
+            }
+            LanceRefSelector selector = selectorOf(table,
+                    text + "'timestamp'='2026-09-20 12:00:00', 'branch'='main')", context);
+            Assertions.assertFalse(selector.getBranch().isPresent());
+            Assertions.assertEquals(org.apache.doris.analysis.TableSnapshot.VersionType.TIME,
+                    selector.getSnapshot().get().getType());
+            selector = selectorOf(table, text + "'version'='2', 'branch'='dev')", context);
+            Assertions.assertEquals("dev", selector.getBranch().orElse(null));
+            Assertions.assertEquals("2", selector.getSnapshot().get().getValue());
+            Assertions.assertEquals("rel", selectorOf(table, text + "'tag'='rel')", context).getTag().orElse(null));
+            Assertions.assertSame(LanceRefSelector.latest(), selectorOf(table, text + "'top_k'='3')", context));
+        } finally {
+            ConnectContext.remove();
+            if (previous != null) {
+                previous.setThreadLocalInfo();
+            }
+        }
+    }
+
+    /**
+     * A search resolves its snapshot when it is bound, so a statement containing one must never be
+     * answered from the SQL cache: a cached result would skip resolving a moving selector again.
+     */
+    @org.junit.jupiter.api.Test
+    public void testSearchStatementsBypassSqlCache() {
+        ConnectContext previous = ConnectContext.get();
+        ConnectContext context = MemoTestUtils.createConnectContext();
+        context.getSessionVariable().setEnableSqlCache(true);
+        LanceExternalTable table = mockSearchTable();
+        try (MockedStatic<LanceExternalSearchTableValuedFunction> lookup = Mockito.mockStatic(
+                LanceExternalSearchTableValuedFunction.class, Mockito.CALLS_REAL_METHODS)) {
+            lookup.when(() -> LanceExternalSearchTableValuedFunction.findLanceExternalTable(
+                    Mockito.any(TableName.class))).thenReturn(table);
+            for (String tvf : new String[] {
+                    "vector_search('table'='catalog.db.items', 'column'='embedding', 'query_vector'='[1,2]', "
+                            + "'tag'='rel')",
+                    "full_text_search('table'='catalog.db.items', 'column'='body', 'query'='lance', "
+                            + "'tag'='rel')"}) {
+                String sql = "select * from " + tvf;
+                StatementContext statement = MemoTestUtils.createStatementContext(context, sql);
+                SqlCacheContext sqlCache = statement.getSqlCacheContext().orElseThrow(
+                        () -> new IllegalStateException("SQL cache is not enabled for " + sql));
+                Assertions.assertFalse(sqlCache.isCannotProcessExpression(), sql);
+                LogicalPlan plan = new NereidsParser().parseMultiple(sql).get(0).first;
+                CascadesContext.initContext(statement, plan, PhysicalProperties.ANY).newAnalyzer().analyze();
+                Assertions.assertTrue(sqlCache.isCannotProcessExpression(), sql);
+            }
+        } finally {
+            ConnectContext.remove();
+            if (previous != null) {
+                previous.setThreadLocalInfo();
+            }
+        }
+    }
+
+    /** A table with a vector and a text column whose metadata is version 3 for every selector. */
+    private static LanceExternalTable mockSearchTable() {
+        Field item = Field.nullable("item", new ArrowType.FloatingPoint(FloatingPointPrecision.SINGLE));
+        Field embedding = new Field("embedding", org.apache.arrow.vector.types.pojo.FieldType.nullable(
+                new ArrowType.FixedSizeList(2)), Collections.singletonList(item));
+        Schema schema = new Schema(Arrays.asList(Field.nullable("id", new ArrowType.Int(64, true)),
+                embedding, Field.nullable("body", ArrowType.Utf8.INSTANCE)));
+        LanceExternalTable table = Mockito.mock(LanceExternalTable.class);
+        Mockito.when(table.loadMetadataForSearch(Mockito.any(LanceRefSelector.class))).thenAnswer(
+                invocation -> LanceTableMetadata.createSnapshotWithIndexes(
+                        new LanceTableAccess("s3://bucket/items.lance", Collections.emptyMap()), 3, schema,
+                        Collections.emptyList(), ImmutableMap.of("id", 0, "embedding", 1, "body", 2),
+                        Collections.emptyList()));
+        Mockito.when(table.loadBasicMetadata(Mockito.any(LanceRefSelector.class))).thenAnswer(
+                invocation -> table.loadMetadataForSearch(invocation.getArgument(0)));
         return table;
     }
 
+    private LanceRefSelector selectorOf(LanceExternalTable table, String tvf, ConnectContext context) {
+        Mockito.clearInvocations(table);
+        LogicalPlan plan = new NereidsParser().parseMultiple("select * from " + tvf).get(0).first;
+        CascadesContext cascades = CascadesContext.initContext(
+                MemoTestUtils.createStatementContext(context, ""), plan, PhysicalProperties.ANY);
+        cascades.newAnalyzer().analyze();
+        org.mockito.ArgumentCaptor<LanceRefSelector> selectors =
+                org.mockito.ArgumentCaptor.forClass(LanceRefSelector.class);
+        Mockito.verify(table, Mockito.atLeast(0)).loadMetadataForSearch(selectors.capture());
+        Mockito.verify(table, Mockito.atLeast(0)).loadBasicMetadata(selectors.capture());
+        Assertions.assertFalse(selectors.getAllValues().isEmpty(), tvf);
+        return selectors.getAllValues().get(0);
+    }
+
     private VectorSearchTableValuedFunction analyze(LogicalPlan plan, StatementContext statement) {
         CascadesContext cascades = CascadesContext.initContext(statement, plan, PhysicalProperties.ANY);
         cascades.newAnalyzer().analyze();
diff --git a/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LanceSearchSelectorTest.java b/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LanceSearchSelectorTest.java
new file mode 100644
index 00000000000..6446785150a
--- /dev/null
+++ b/fe/fe-core/src/test/java/org/apache/doris/tablefunction/LanceSearchSelectorTest.java
@@ -0,0 +1,189 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.apache.doris.tablefunction;
+
+import org.apache.doris.analysis.TableSnapshot;
+import org.apache.doris.common.AnalysisException;
+import org.apache.doris.datasource.lance.metadata.LanceRefSelector;
+import org.apache.doris.datasource.lance.metadata.LanceSnapshotResolver;
+import org.apache.doris.nereids.util.MemoTestUtils;
+import org.apache.doris.qe.ConnectContext;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+public class LanceSearchSelectorTest {
+
+    private static LanceRefSelector parse(String... keyValues) throws AnalysisException {
+        Map<String, String> params = new HashMap<>();
+        for (int i = 0; i < keyValues.length; i += 2) {
+            params.put(keyValues[i], keyValues[i + 1]);
+        }
+        return LanceExternalSearchTableValuedFunction.parseSelector(params);
+    }
+
+    private static String error(String... keyValues) {
+        return Assertions.assertThrows(AnalysisException.class, () -> parse(keyValues)).getDetailMessage();
+    }
+
+    private static void assertSnapshot(LanceRefSelector selector, TableSnapshot.VersionType type, String value) {
+        Assertions.assertTrue(selector.getSnapshot().isPresent());
+        Assertions.assertEquals(type, selector.getSnapshot().get().getType());
+        Assertions.assertEquals(value, selector.getSnapshot().get().getValue());
+    }
+
+    @Test
+    public void testNoSelectorIsLatestMain() throws Exception {
+        Assertions.assertSame(LanceRefSelector.latest(),
+                LanceExternalSearchTableValuedFunction.parseSelector(Collections.emptyMap()));
+        Assertions.assertSame(LanceRefSelector.latest(), parse("column", "embedding"));
+    }
+
+    @Test
+    public void testVersionIsAPositiveIntegerOnly() throws Exception {
+        LanceRefSelector selector = parse("version", " 007 ");
+        assertSnapshot(selector, TableSnapshot.VersionType.VERSION, "7");
+        Assertions.assertFalse(selector.getBranch().isPresent());
+        Assertions.assertFalse(selector.getTag().isPresent());
+        // A tag name is not a version here, although FOR VERSION AS OF takes one.
+        for (String invalid : new String[] {"0", "-1", "+3", "v3", "1.5", "release"}) {
+            Assertions.assertEquals("'version' must be a positive integer, but was '" + invalid + "'",
+                    error("version", invalid));
+        }
+        Assertions.assertTrue(error("version", "9223372036854775808").contains("out of range"));
+    }
+
+    @Test
+    public void testTimestampFormats() throws Exception {
+        assertSnapshot(parse("timestamp", "2026-09-20 12:00:00"), TableSnapshot.VersionType.TIME,
+                "2026-09-20 12:00:00");
+        assertSnapshot(parse("timestamp", " 2026-09-20 12:00:00.123 "), TableSnapshot.VersionType.TIME,
+                "2026-09-20 12:00:00.123");
+        for (String invalid : new String[] {"1758369600000", "2026-09-20", "2026-09-20T12:00:00",
+                "2026-09-20 12:00:00.1234", "yesterday", "+300000000-01-01 00:00:00"}) {
+            Assertions.assertTrue(error("timestamp", invalid).startsWith("'timestamp' must be "
+                    + LanceSnapshotResolver.TIMESTAMP_FORMATS + " in the session time zone"), invalid);
+        }
+    }
+
+    @Test
+    public void testTimestampUsesSessionTimeZone() {
+        ConnectContext previous = ConnectContext.get();
+        ConnectContext context = MemoTestUtils.createConnectContext();
+        try {
+            context.getSessionVariable().setTimeZone("UTC");
+            long utc = LanceSnapshotResolver.parseTimestamp("2026-09-20 12:00:00").getAsLong();
+            Assertions.assertEquals(1789905600000L, utc);
+            Assertions.assertEquals(utc + 123,
+                    LanceSnapshotResolver.parseTimestamp("2026-09-20 12:00:00.123").getAsLong());
+            context.getSessionVariable().setTimeZone("Asia/Shanghai");
+            Assertions.assertEquals(utc - 8 * 3600 * 1000L,
+                    LanceSnapshotResolver.parseTimestamp("2026-09-20 12:00:00").getAsLong());
+            Assertions.assertFalse(LanceSnapshotResolver.parseTimestamp("2026-09-20").isPresent());
+        } finally {
+            ConnectContext.remove();
+            if (previous != null) {
+                previous.setThreadLocalInfo();
+            }
+        }
+    }
+
+    @Test
+    public void testTagStandsAlone() throws Exception {
+        LanceRefSelector selector = parse("tag", "release");
+        Assertions.assertEquals(Optional.of("release"), selector.getTag());
+        Assertions.assertFalse(selector.getSnapshot().isPresent());
+        Assertions.assertFalse(selector.getBranch().isPresent());
+        // A numeric tag name is a tag here; FOR VERSION AS OF would read it as a version.
+        Assertions.assertEquals(Optional.of("123"), parse("tag", "123").getTag());
+        for (String other : new String[] {"version", "timestamp", "branch"}) {
+            String value = other.equals("timestamp") ? "2026-09-20 12:00:00" : other.equals("version") ? "3" : "dev";
+            Assertions.assertEquals("'tag' and '" + other + "' are mutually exclusive;"
+                    + " a tag already determines its branch and version", error("tag", "release", other, value));
+        }
+        // Even main names a chain, which the tag already determines.
+        Assertions.assertTrue(error("tag", "release", "branch", "main").contains("mutually exclusive"));
+    }
+
+    @Test
+    public void testVersionAndTimestampAreMutuallyExclusive() {
+        Assertions.assertEquals("'version' and 'timestamp' are mutually exclusive",
+                error("version", "3", "timestamp", "2026-09-20 12:00:00"));
+        Assertions.assertEquals("'version' and 'timestamp' are mutually exclusive",
+                error("version", "3", "timestamp", "2026-09-20 12:00:00", "branch", "dev"));
+    }
+
+    @Test
+    public void testBranchAloneOrWithVersionOrTimestamp() throws Exception {
+        LanceRefSelector latest = parse("branch", "dev");
+        Assertions.assertEquals(Optional.of("dev"), latest.getBranch());
+        Assertions.assertFalse(latest.getSnapshot().isPresent());
+
+        LanceRefSelector version = parse("branch", "team/dev", "version", "4");
+        Assertions.assertEquals(Optional.of("team/dev"), version.getBranch());
+        assertSnapshot(version, TableSnapshot.VersionType.VERSION, "4");
+
+        LanceRefSelector time = parse("branch", "dev", "timestamp", "2026-09-20 12:00:00");
+        Assertions.assertEquals(Optional.of("dev"), time.getBranch());
+        assertSnapshot(time, TableSnapshot.VersionType.TIME, "2026-09-20 12:00:00");
+    }
+
+    @Test
+    public void testMainBranchIsTheMainChain() throws Exception {
+        Assertions.assertSame(LanceRefSelector.latest(), parse("branch", "main"));
+        LanceRefSelector version = parse("branch", "main", "version", "4");
+        Assertions.assertFalse(version.getBranch().isPresent());
+        assertSnapshot(version, TableSnapshot.VersionType.VERSION, "4");
+        LanceRefSelector time = parse("branch", "main", "timestamp", "2026-09-20 12:00:00");
+        Assertions.assertFalse(time.getBranch().isPresent());
+        assertSnapshot(time, TableSnapshot.VersionType.TIME, "2026-09-20 12:00:00");
+    }
+
+    /** The table hands the selector, unchanged, to the catalog's search metadata loaders. */
+    @Test
+    public void testTableForwardsTheSelectorToTheCatalog() throws Exception {
+        org.apache.doris.datasource.lance.LanceExternalCatalog catalog =
+                org.mockito.Mockito.mock(org.apache.doris.datasource.lance.LanceExternalCatalog.class);
+        org.apache.doris.datasource.lance.LanceExternalDatabase db =
+                org.mockito.Mockito.mock(org.apache.doris.datasource.lance.LanceExternalDatabase.class);
+        org.mockito.Mockito.when(db.getRemoteName()).thenReturn("remote_db");
+        org.apache.doris.datasource.lance.LanceExternalTable table =
+                new org.apache.doris.datasource.lance.LanceExternalTable(1, "t", "remote_t", catalog, db);
+        LanceRefSelector selector = parse("branch", "dev", "version", "4");
+        table.loadMetadataForSearch(selector);
+        org.mockito.Mockito.verify(catalog).loadTableMetadataForSearch("remote_db", "remote_t", selector);
+        table.loadBasicMetadata(selector);
+        org.mockito.Mockito.verify(catalog).loadBasicTableMetadata("remote_db", "remote_t", selector);
+    }
+
+    @Test
+    public void testEmptySelectorIsAnError() {
+        for (String key : new String[] {"version", "timestamp", "tag", "branch"}) {
+            for (String empty : new String[] {"", "   "}) {
+                Assertions.assertEquals("'" + key + "' must not be empty", error(key, empty));
+            }
+        }
+        // An empty selector fails before any combination is checked.
+        Assertions.assertEquals("'branch' must not be empty", error("tag", "release", "branch", ""));
+    }
+}
diff --git a/fe/fe-core/src/test/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunctionTest.java b/fe/fe-core/src/test/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunctionTest.java
index c8c3da2c6c0..a141419a1ba 100644
--- a/fe/fe-core/src/test/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunctionTest.java
+++ b/fe/fe-core/src/test/java/org/apache/doris/tablefunction/VectorSearchTableValuedFunctionTest.java
@@ -90,7 +90,8 @@ public class VectorSearchTableValuedFunctionTest {
             AnalysisException exception = Assert.assertThrows(AnalysisException.class,
                     () -> VectorSearchTableValuedFunction.parseTableName(table));
             Assert.assertTrue(exception.getMessage(),
-                    exception.getMessage().contains("cannot select a version, tag or branch"));
+                    exception.getMessage().contains("cannot select a version, tag or branch;"
+                            + " use the 'version', 'timestamp', 'tag' or 'branch' property"));
         }
     }
 
diff --git a/regression-test/data/external_table_p0/lance/test_lance_rest_catalog.out b/regression-test/data/external_table_p0/lance/test_lance_rest_catalog.out
index 17e65ed4f29..78f2409fba1 100644
--- a/regression-test/data/external_table_p0/lance/test_lance_rest_catalog.out
+++ b/regression-test/data/external_table_p0/lance/test_lance_rest_catalog.out
@@ -7,6 +7,10 @@ mysql
 -- !rest_tables --
 all_types
 all_types_unprefixed
+search_snapshot
+search_snapshot_managed
+search_snapshot_managed_partial
+search_snapshot_pruned
 time_travel
 time_travel_managed
 time_travel_managed_lagging
@@ -16,6 +20,7 @@ time_travel_managed_pending
 time_travel_managed_staged
 time_travel_managed_unprefixed
 time_travel_managed_untimed
+unicode_branch_managed
 
 -- !rest_scan --
 12	12	1	12	78
diff --git a/regression-test/data/external_table_p0/lance/test_lance_rest_search_snapshot.out b/regression-test/data/external_table_p0/lance/test_lance_rest_search_snapshot.out
new file mode 100644
index 00000000000..57462eff9ec
--- /dev/null
+++ b/regression-test/data/external_table_p0/lance/test_lance_rest_search_snapshot.out
@@ -0,0 +1,59 @@
+-- This file is automatically generated. You should know what you did if you want to edit this
+-- !plain_version_5 --
+17	0.0
+16	4.0
+18	4.0
+
+-- !managed_version_5 --
+17	0.0
+16	4.0
+18	4.0
+
+-- !managed_branch --
+101	4.0
+102	16.0
+103	36.0
+
+-- !managed_branch_two_phase --
+101	doc 101 doris	4.0
+102	doc 102 lance	16.0
+103	doc 103 doris	36.0
+
+-- !managed_version_two_phase --
+17	doc 17 doris	0.25
+18	doc 18 lance	2.25
+16	doc 16 lance	6.25
+
+-- !managed_branch_tag_fts --
+10
+12
+14
+16
+2
+4
+6
+8
+
+-- !managed_fts_version_4 --
+10
+12
+14
+16
+2
+4
+6
+8
+
+-- !unicode_branch_scan --
+12	204
+
+-- !unicode_branch_search --
+201	4.0
+202	16.0
+203	36.0
+
+-- !unicode_branch_two_phase --
+201	doc 201	2.25
+202	doc 202	12.25
+203	doc 203	30.25
+
diff --git a/regression-test/data/external_table_p0/lance/test_lance_rest_time_travel.out b/regression-test/data/external_table_p0/lance/test_lance_rest_time_travel.out
index ea9662a455a..9e9b6777ea4 100644
--- a/regression-test/data/external_table_p0/lance/test_lance_rest_time_travel.out
+++ b/regression-test/data/external_table_p0/lance/test_lance_rest_time_travel.out
@@ -2,6 +2,10 @@
 -- !tables --
 all_types
 all_types_unprefixed
+search_snapshot
+search_snapshot_managed
+search_snapshot_managed_partial
+search_snapshot_pruned
 time_travel
 time_travel_managed
 time_travel_managed_lagging
@@ -11,6 +15,7 @@ time_travel_managed_pending
 time_travel_managed_staged
 time_travel_managed_unprefixed
 time_travel_managed_untimed
+unicode_branch_managed
 
 -- !plain_latest --
 9	9
diff --git a/regression-test/data/external_table_p0/lance/test_lance_search_snapshot.out b/regression-test/data/external_table_p0/lance/test_lance_search_snapshot.out
new file mode 100644
index 00000000000..e7344fd0702
--- /dev/null
+++ b/regression-test/data/external_table_p0/lance/test_lance_search_snapshot.out
@@ -0,0 +1,182 @@
+-- This file is automatically generated. You should know what you did if you want to edit this
+-- !latest --
+1	4.0
+2	16.0
+4	64.0
+
+-- !version_2 --
+1	4.0
+2	16.0
+3	36.0
+
+-- !version_5 --
+17	0.0
+16	4.0
+18	4.0
+
+-- !version_5_fts --
+10
+12
+14
+16
+2
+4
+6
+8
+
+-- !version_4_fts_strict --
+10
+12
+14
+16
+2
+4
+6
+8
+
+-- !version_6 --
+4	2.25
+2	6.25
+5	12.25
+
+-- !version_5_not_deleted --
+3	0.25
+4	2.25
+2	6.25
+
+-- !version_5_fts_doris --
+1
+11
+13
+15
+3
+5
+7
+9
+
+-- !version_6_fts_doris --
+1
+13
+15
+5
+7
+9
+
+-- !version_5_no_index --
+17	0.0
+16	4.0
+18	4.0
+
+-- !tag_rel --
+17	0.0
+16	4.0
+18	4.0
+
+-- !main_branch --
+1	4.0
+2	16.0
+3	36.0
+
+-- !branch_latest --
+101	4.0
+102	16.0
+103	36.0
+
+-- !main_same_query --
+24	23104.0
+23	23716.0
+22	24336.0
+
+-- !branch_fts_strict --
+10
+102
+104
+106
+108
+12
+14
+16
+2
+4
+6
+8
+
+-- !branch_no_index --
+101	4.0
+102	16.0
+103	36.0
+
+-- !branch_fork --
+16	28224.0
+15	28900.0
+14	29584.0
+
+-- !branch_version_5 --
+101	4.0
+102	16.0
+103	36.0
+
+-- !branch_version_6_fts_strict --
+10
+102
+104
+106
+108
+12
+14
+16
+2
+4
+6
+8
+
+-- !branch_tag_fts --
+10
+12
+14
+16
+2
+4
+6
+8
+
+-- !branch_two_phase --
+101	doc 101 doris	4.0
+102	doc 102 lance	16.0
+103	doc 103 doris	36.0
+
+-- !tag_two_phase --
+3	doc 3 doris	0.25
+4	doc 4 lance	2.25
+2	doc 2 lance	6.25
+
+-- !evolved_two_phase --
+2	[2, 3, 4, 5]	note 2	doc 2 lance	0.25
+3	[3, 4, 5, 6]	note 3	doc 3 doris	2.25
+1	[1, 2, 3, 4]	note 1	doc 1 doris	6.25
+
+-- !evolved_old_two_phase --
+2	[2, 3, 4, 5]	note 2	doc 2 lance	0.25
+3	[3, 4, 5, 6]	note 3	doc 3 doris	2.25
+1	[1, 2, 3, 4]	note 1	doc 1 doris	6.25
+
+-- !evolved_version_2 --
+2	0.25
+3	2.25
+1	6.25
+
+-- !evolved_version_4 --
+2	0.25
+3	2.25
+1	6.25
+
+-- !evolved_latest --
+12	0.25
+13	2.25
+11	6.25
+
+-- !pruned_latest --
+1	4.0
+2	16.0
+3	36.0
+
diff --git a/regression-test/data/external_table_p0/lance/test_lance_vector_search_legacy_index.out b/regression-test/data/external_table_p0/lance/test_lance_vector_search_legacy_index.out
new file mode 100644
index 00000000000..865d1ece304
--- /dev/null
+++ b/regression-test/data/external_table_p0/lance/test_lance_vector_search_legacy_index.out
@@ -0,0 +1,11 @@
+-- This file is automatically generated. You should know what you did if you want to edit this
+-- !legacy_indexed --
+100	0.25
+101	2.25
+99	6.25
+
+-- !legacy_flat --
+100	0.25
+101	2.25
+99	6.25
+
diff --git a/regression-test/suites/external_table_p0/lance/test_lance_rest_search_snapshot.groovy b/regression-test/suites/external_table_p0/lance/test_lance_rest_search_snapshot.groovy
new file mode 100644
index 00000000000..362ed549b42
--- /dev/null
+++ b/regression-test/suites/external_table_p0/lance/test_lance_rest_search_snapshot.groovy
@@ -0,0 +1,202 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+suite("test_lance_rest_search_snapshot", "p0,external") {
+    /*
+     * The search TVFs' snapshot selectors through a Lance REST Namespace, with and without
+     * managed versioning. All tables are search_snapshot.lance (seven main versions, branch dev
+     * with versions 4 to 6, tags rel and dev_rel; see test_lance_search_snapshot):
+     *
+     *   search_snapshot                  managed_versioning=false: versions come from _versions/
+     *   search_snapshot_managed          managed_versioning=true, records every version and dev
+     *   search_snapshot_managed_partial  managed_versioning=true, records every main version but 6
+     *   unicode_branch_managed           managed_versioning=true, unicode_branch.lance: version 1
+     *                                    has row_id 1..8; branch dev\u1c89 adds row_id 201..204
+     *                                    in its version 2 (see lance_build_unicode_branch.py)
+     *
+     * For a managed table the namespace decides which versions exist, as for FOR VERSION AS OF
+     * (see test_lance_rest_time_travel); the search TVFs follow the same rules.
+     */
+    String enabled = context.config.otherConfigs.get("enableIcebergTest")
+    if (enabled == null || !enabled.equalsIgnoreCase("true")) {
+        logger.info("disable Lance REST test because the Iceberg MinIO environment is disabled.")
+        return
+    }
+
+    String externalEnvIp = context.config.otherConfigs.get("externalEnvIp")
+    String minioPort = context.config.otherConfigs.get("iceberg_minio_port")
+    String lanceRestPort = context.config.otherConfigs.get("lance_rest_port")
+    String catalogName = "test_lance_rest_search_snapshot"
+    String plain = "${catalogName}.`default`.search_snapshot"
+    String managed = "${catalogName}.`default`.search_snapshot_managed"
+    String partial = "${catalogName}.`default`.search_snapshot_managed_partial"
+    String unicodeManaged = "${catalogName}.`default`.unicode_branch_managed"
+    // U+1C89 was added in Unicode 16: Lance accepts the name, and JDK 17 leaves it unassigned.
+    String unicodeBranch = "dev\u1c89"
+    def vectorSearch = { String target, String selector, String query = "[0,1,2,3]" ->
+        """vector_search(
+                "table"="${target}",
+                "column"="vec",
+                "query_vector"="${query}",
+                "top_k"="3",
+                "metric"="l2",
+                "nprobes"="2"${selector})"""
+    }
+    def fullTextSearch = { String target, String selector ->
+        """full_text_search(
+                "table"="${target}",
+                "column"="body",
+                "query"="lance",
+                "top_k"="30",
+                "coverage_mode"="index_only"${selector})"""
+    }
+    def scannerV2Rows = sql """SHOW VARIABLES LIKE 'enable_file_scanner_v2'"""
+    String originalScannerV2 = scannerV2Rows[0][1].toString()
+    String originalTimeZone = (sql """SHOW VARIABLES LIKE 'time_zone'""")[0][1].toString()
+    String originalLazy = (sql """SHOW VARIABLES LIKE 'enable_lance_lazy_materialization'""")[0][1].toString()
+
+    sql """DROP CATALOG IF EXISTS `${catalogName}`"""
+    try {
+        sql """SET enable_file_scanner_v2 = true"""
+        sql """SET time_zone = 'UTC'"""
+        // No static access key or secret key: every read below uses vended credentials.
+        sql """
+            CREATE CATALOG `${catalogName}` PROPERTIES (
+                "type" = "lance",
+                "lance.catalog.type" = "rest",
+                "lance.rest.uri" = "http://${externalEnvIp}:${lanceRestPort}",
+                "lance.rest.security.type" = "bearer",
+                "lance.rest.bearer-token" = "doris-lance-rest-test-token",
+                "lance.namespace.root_database" = "default",
+                "s3.endpoint" = "http://${externalEnvIp}:${minioPort}",
+                "s3.region" = "us-east-1",
+                "use_path_style" = "true",
+                "test_connection" = "true"
+            )
+        """
+
+        for (String target : [plain, managed]) {
+            String managedFlag = target == managed ? "true" : "false"
+            explain {
+                sql("SELECT row_id FROM ${vectorSearch(target, "")}")
+                contains "lanceCatalogType=rest"
+                contains "lanceVersion=7"
+                contains "lanceManagedVersioning=${managedFlag}"
+            }
+            explain {
+                sql("SELECT row_id FROM ${vectorSearch(target, ', "tag"="rel"')}")
+                contains "lanceVersion=5"
+                contains "lanceManagedVersioning=${managedFlag}"
+            }
+            explain {
+                sql("SELECT row_id FROM ${vectorSearch(target, ', "branch"="dev"')}")
+                contains "lanceVersion=6"
+                contains "lanceBranch=dev"
+                contains "lanceManagedVersioning=${managedFlag}"
+            }
+            explain {
+                sql("SELECT row_id FROM ${vectorSearch(target, ', "timestamp"="2026-09-29 14:51:58"')}")
+                contains "lanceVersion=5"
+            }
+        }
+        qt_plain_version_5 """
+            SELECT row_id, _distance FROM ${vectorSearch(plain, ', "version"="5"', "[17,18,19,20]")}
+            ORDER BY _distance, row_id
+        """
+        qt_managed_version_5 """
+            SELECT row_id, _distance FROM ${vectorSearch(managed, ', "version"="5"', "[17,18,19,20]")}
+            ORDER BY _distance, row_id
+        """
+        qt_managed_branch """
+            SELECT row_id, _distance FROM ${vectorSearch(managed, ', "branch"="dev"', "[100,101,102,103]")}
+            ORDER BY _distance, row_id
+        """
+        // Two-phase reads of a managed table: the second phase reopens the version and branch
+        // directory the namespace resolved, with the first phase's vended credentials.
+        sql """SET enable_lance_lazy_materialization = true"""
+        String managedTwoPhase = """
+            SELECT row_id, body, _distance
+            FROM ${vectorSearch(managed, ', "branch"="dev"', "[100,101,102,103]")}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        explain {
+            sql "verbose ${managedTwoPhase}"
+            contains "VMaterializeNode"
+        }
+        qt_managed_branch_two_phase "${managedTwoPhase}"
+        qt_managed_version_two_phase """
+            SELECT row_id, body, _distance
+            FROM ${vectorSearch(managed, ', "version"="5"', "[17.25,18.25,19.25,20.25]")}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        sql """SET enable_lance_lazy_materialization = ${originalLazy}"""
+        order_qt_managed_branch_tag_fts """SELECT row_id FROM ${fullTextSearch(managed, ', "tag"="dev_rel"')}"""
+        order_qt_managed_fts_version_4 """SELECT row_id FROM ${fullTextSearch(managed, ', "version"="4"')}"""
+
+        // A managed branch whose name has a letter newer than the JDK's Unicode tables is opened by
+        // the URI Doris joins, for table scans, searches and the second phase alike.
+        order_qt_unicode_branch_scan """
+            SELECT count(*), max(row_id) FROM ${unicodeManaged}@branch('name'='${unicodeBranch}')
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(unicodeManaged, ', "branch"="' + unicodeBranch + '"')}")
+            contains "lanceVersion=2"
+            contains "lanceBranch=${unicodeBranch}"
+        }
+        qt_unicode_branch_search """
+            SELECT row_id, _distance
+            FROM ${vectorSearch(unicodeManaged, ', "branch"="' + unicodeBranch + '"', "[200,201,202,203]")}
+            ORDER BY _distance, row_id
+        """
+        sql """SET enable_lance_lazy_materialization = true"""
+        String unicodeTwoPhase = """
+            SELECT row_id, body, _distance
+            FROM ${vectorSearch(unicodeManaged, ', "branch"="' + unicodeBranch + '"', "[200.25,201.25,202.25,203.25]")}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        explain {
+            sql "verbose ${unicodeTwoPhase}"
+            contains "VMaterializeNode"
+        }
+        qt_unicode_branch_two_phase "${unicodeTwoPhase}"
+        sql """SET enable_lance_lazy_materialization = ${originalLazy}"""
+
+        // The namespace does not record version 6 of the partial table, so it cannot be searched
+        // even though storage holds it; the latest version is still 7.
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(partial, "")}")
+            contains "lanceVersion=7"
+            contains "lanceManagedVersioning=true"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(partial, ', "version"="6"')}"""
+            exception "Lance version 6 of default.search_snapshot_managed_partial was not found in the namespace"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(managed, ', "branch"="dev", "version"="9"')}"""
+            exception "Lance version 9 of default.search_snapshot_managed@dev was not found in the namespace"
+        }
+    } finally {
+        sql """SET enable_file_scanner_v2 = ${originalScannerV2}"""
+        sql """SET time_zone = '${originalTimeZone}'"""
+        sql """SET enable_lance_lazy_materialization = ${originalLazy}"""
+        sql """DROP CATALOG IF EXISTS `${catalogName}`"""
+    }
+}
diff --git a/regression-test/suites/external_table_p0/lance/test_lance_search_snapshot.groovy b/regression-test/suites/external_table_p0/lance/test_lance_search_snapshot.groovy
new file mode 100644
index 00000000000..b155327770d
--- /dev/null
+++ b/regression-test/suites/external_table_p0/lance/test_lance_search_snapshot.groovy
@@ -0,0 +1,452 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+suite("test_lance_search_snapshot", "p0,external") {
+    /*
+     * vector_search() and full_text_search() with the version, timestamp, tag and branch
+     * properties, on a Lance filesystem catalog.
+     *
+     * search_snapshot.lance (see lance_build_search_snapshot.py), main chain:
+     *   version 1  row_id 1..8     fragment 0      committed 2026-09-29 14:51:51.410834 UTC
+     *   version 2  row_id 9..16    fragment 1      committed 2026-09-29 14:51:52.929307 UTC
+     *   version 3  vec_idx over fragments 0, 1     committed 2026-09-29 14:51:54.457459 UTC
+     *   version 4  body_idx over fragments 0, 1    committed 2026-09-29 14:51:55.985957 UTC
+     *   version 5  row_id 17..24   fragment 2      committed 2026-09-29 14:51:57.507267 UTC
+     *   version 6  delete row_id 3, 11             committed 2026-09-29 14:51:59.031043 UTC
+     *   version 7  vec_idx rebuilt over 0, 1, 2    committed 2026-09-29 14:52:00.565680 UTC
+     * Tag rel points at version 5. Branch dev forks from version 4; its version 5 appends
+     * row_id 101..108 as fragment 2, and its version 6 rebuilds body_idx over all fragments.
+     * Tag dev_rel points at dev version 5. Dev versions 4, 5 and 6 were committed at
+     * 14:52:16.005995, 14:52:17.762386 and 14:52:19.576617 UTC, after every main version.
+     * vec is [row_id, row_id + 1, row_id + 2, row_id + 3],
+     * so the squared L2 distance between rows r and n is 4 * (n - r)^2, and nprobes=2 makes
+     * the two-partition IVF_FLAT index exact. body is "doc <row_id> lance" for even row_ids and
+     * "doc <row_id> doris" for odd ones.
+     *
+     * search_snapshot_pruned.lance lost version 1 to cleanup; version 2, pinned by tag kept,
+     * still opens but its vector index files are gone; version 3 rebuilt the index.
+     *
+     * search_snapshot_evolved.lance changes its schema after its vector index: version 1 has
+     * row_id 1..8 as fragment 0, version 2 builds vec_idx over it, version 3 adds note
+     * ("note <row_id>"), version 4 renames vec to embedding (vec_idx still serves it), and
+     * version 5 appends row_id 9..16 as fragment 1, which vec_idx does not cover.
+     */
+    String enabled = context.config.otherConfigs.get("enableIcebergTest")
+    if (enabled == null || !enabled.equalsIgnoreCase("true")) {
+        logger.info("disable Lance test because the Iceberg MinIO environment is disabled.")
+        return
+    }
+
+    String externalEnvIp = context.config.otherConfigs.get("externalEnvIp")
+    String minioPort = context.config.otherConfigs.get("iceberg_minio_port")
+    String catalogName = "test_lance_search_snapshot"
+    String table = "${catalogName}.`default`.search_snapshot"
+    String pruned = "${catalogName}.`default`.search_snapshot_pruned"
+    String evolved = "${catalogName}.`default`.search_snapshot_evolved"
+    def vectorSearch = { String selector, String query = "[0,1,2,3]", String topK = "3",
+            String target = table ->
+        """vector_search(
+                "table"="${target}",
+                "column"="vec",
+                "query_vector"="${query}",
+                "top_k"="${topK}",
+                "metric"="l2",
+                "nprobes"="2"${selector})"""
+    }
+    def fullTextSearch = { String selector, String coverageMode = "index_only", String query = "lance" ->
+        """full_text_search(
+                "table"="${table}",
+                "column"="body",
+                "query"="${query}",
+                "top_k"="30",
+                "coverage_mode"="${coverageMode}"${selector})"""
+    }
+    // Queries sit a quarter step past a row, so no two rows tie.
+    def evolvedSearch = { String column, String selector, String query = "[2.25,3.25,4.25,5.25]" ->
+        """vector_search(
+                "table"="${evolved}",
+                "column"="${column}",
+                "query_vector"="${query}",
+                "top_k"="3",
+                "metric"="l2",
+                "nprobes"="2"${selector})"""
+    }
+    def scannerV2Rows = sql """SHOW VARIABLES LIKE 'enable_file_scanner_v2'"""
+    String originalScannerV2 = scannerV2Rows[0][1].toString()
+    String originalTimeZone = (sql """SHOW VARIABLES LIKE 'time_zone'""")[0][1].toString()
+    String originalLazy = (sql """SHOW VARIABLES LIKE 'enable_lance_lazy_materialization'""")[0][1].toString()
+
+    sql """DROP CATALOG IF EXISTS `${catalogName}`"""
+    try {
+        sql """SET enable_file_scanner_v2 = true"""
+        sql """SET time_zone = 'UTC'"""
+        sql """
+            CREATE CATALOG `${catalogName}` PROPERTIES (
+                "type" = "lance",
+                "lance.catalog.type" = "filesystem",
+                "warehouse" = "s3://warehouse/lance",
+                "s3.endpoint" = "http://${externalEnvIp}:${minioPort}",
+                "s3.access_key" = "admin",
+                "s3.secret_key" = "password",
+                "s3.region" = "us-east-1",
+                "use_path_style" = "true"
+            )
+        """
+
+        // Without a selector: the latest main version, where rows 3 and 11 are deleted.
+        qt_latest """SELECT row_id, _distance FROM ${vectorSearch("")} ORDER BY _distance, row_id"""
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch("")}")
+            contains "lanceCatalogType=filesystem"
+            contains "lanceVersion=7"
+            contains "lanceManagedVersioning=false"
+            notContains "lanceBranch="
+            contains "lanceSearchIndexFragments=3"
+            contains "lanceSearchUnindexedFragments=0"
+        }
+
+        // Before any index: a flat search over that version's two fragments.
+        qt_version_2 """SELECT row_id, _distance FROM ${vectorSearch(', "version"="2"')} ORDER BY _distance, row_id"""
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "version"="2"')}")
+            contains "lanceVersion=2"
+            contains "lanceVectorIndexStatus=NO_MATCH"
+            contains "lanceSearchIndexSegments=0"
+            contains "lanceSearchUnindexedFragments=2"
+        }
+        test {
+            sql """SELECT row_id FROM ${fullTextSearch(', "version"="3"')}"""
+            exception "No committed Lance FTS index exists for column 'body' at dataset version 3"
+        }
+
+        // Version 5 appended fragment 2 after both indexes: the vector search combines the index
+        // over fragments 0 and 1 with a flat search of fragment 2, and full-text search covers
+        // only the indexed fragments.
+        qt_version_5 """
+            SELECT row_id, _distance FROM ${vectorSearch(', "version"="5"', "[17,18,19,20]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "version"="5"')}")
+            contains "lanceVersion=5"
+            contains "lanceSearchIndexFragments=2"
+            contains "lanceSearchUnindexedFragments=1"
+        }
+        order_qt_version_5_fts """SELECT row_id FROM ${fullTextSearch(', "version"="5"')}"""
+        test {
+            sql """SELECT row_id FROM ${fullTextSearch(', "version"="5"', "strict")}"""
+            exception "requires every fragment at dataset version 5 to be indexed"
+        }
+        order_qt_version_4_fts_strict """SELECT row_id FROM ${fullTextSearch(', "version"="4"', "strict")}"""
+
+        // Version 6 deleted rows 3 and 11 and still uses the original index; version 7 rebuilt it.
+        // The query sits a quarter step past row 3, so no two rows tie.
+        qt_version_6 """
+            SELECT row_id, _distance FROM ${vectorSearch(', "version"="6"', "[3.25,4.25,5.25,6.25]")}
+            ORDER BY _distance, row_id
+        """
+        qt_version_5_not_deleted """
+            SELECT row_id, _distance FROM ${vectorSearch(', "version"="5"', "[3.25,4.25,5.25,6.25]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "version"="6"')}")
+            contains "lanceSearchIndexFragments=2"
+            contains "lanceSearchUnindexedFragments=1"
+        }
+        // Full-text search sees the deletion too: rows 3 and 11 are "doris" rows.
+        order_qt_version_5_fts_doris """SELECT row_id FROM ${fullTextSearch(', "version"="5"', "index_only", "doris")}"""
+        order_qt_version_6_fts_doris """SELECT row_id FROM ${fullTextSearch(', "version"="6"', "index_only", "doris")}"""
+
+        // use_index=false loads metadata without indexes, from the selected snapshot as well.
+        qt_version_5_no_index """
+            SELECT row_id, _distance FROM ${vectorSearch(', "version"="5", "use_index"="false"', "[17,18,19,20]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "version"="5", "use_index"="false"')}")
+            contains "lanceVersion=5"
+            contains "lanceVectorIndexStatus=DISABLED"
+            contains "lanceSearchUnindexedFragments=3"
+        }
+
+        // A tag and main written as a branch select main versions.
+        qt_tag_rel """
+            SELECT row_id, _distance FROM ${vectorSearch(', "tag"="rel"', "[17,18,19,20]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "tag"="rel"')}")
+            contains "lanceVersion=5"
+            notContains "lanceBranch="
+        }
+        qt_main_branch """
+            SELECT row_id, _distance FROM ${vectorSearch(', "branch"="main", "version"="2"')}
+            ORDER BY _distance, row_id
+        """
+
+        // Branch dev: its version 6 shares main's version numbers and fragment ids, not its rows.
+        qt_branch_latest """
+            SELECT row_id, _distance FROM ${vectorSearch(', "branch"="dev"', "[100,101,102,103]")}
+            ORDER BY _distance, row_id
+        """
+        qt_main_same_query """
+            SELECT row_id, _distance FROM ${vectorSearch(', "version"="6"', "[100,101,102,103]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "branch"="dev"')}")
+            contains "lanceVersion=6"
+            contains "lanceBranch=dev"
+            contains "lanceSearchIndexFragments=2"
+            contains "lanceSearchUnindexedFragments=1"
+        }
+        order_qt_branch_fts_strict """SELECT row_id FROM ${fullTextSearch(', "branch"="dev"', "strict")}"""
+        qt_branch_no_index """
+            SELECT row_id, _distance
+            FROM ${vectorSearch(', "branch"="dev", "use_index"="false"', "[100,101,102,103]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "branch"="dev", "use_index"="false"')}")
+            contains "lanceVersion=6"
+            contains "lanceBranch=dev"
+            contains "lanceVectorIndexStatus=DISABLED"
+        }
+        qt_branch_fork """
+            SELECT row_id, _distance FROM ${vectorSearch(', "branch"="dev", "version"="4"', "[100,101,102,103]")}
+            ORDER BY _distance, row_id
+        """
+        // Historical branch versions past the fork differ from main's versions of the same number:
+        // dev version 5 has row_id 101..108 where main version 5 has 17..24, and dev version 6
+        // rebuilt body_idx over fragment 2, which main version 6 does not cover.
+        qt_branch_version_5 """
+            SELECT row_id, _distance FROM ${vectorSearch(', "branch"="dev", "version"="5"', "[100,101,102,103]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "branch"="dev", "version"="5"')}")
+            contains "lanceVersion=5"
+            contains "lanceBranch=dev"
+            contains "lanceSearchUnindexedFragments=1"
+        }
+        order_qt_branch_version_6_fts_strict """
+            SELECT row_id FROM ${fullTextSearch(', "branch"="dev", "version"="6"', "strict")}
+        """
+        test {
+            sql """SELECT row_id FROM ${fullTextSearch(', "version"="6"', "strict")}"""
+            exception "requires every fragment at dataset version 6 to be indexed"
+        }
+        // dev_rel points at dev version 5, not the branch's latest; its FTS index covers only
+        // the fork's fragments, and the error names the branch.
+        order_qt_branch_tag_fts """SELECT row_id FROM ${fullTextSearch(', "tag"="dev_rel"')}"""
+        test {
+            sql """SELECT row_id FROM ${fullTextSearch(', "tag"="dev_rel"', "strict")}"""
+            exception "dataset version 5 of branch 'dev' to be indexed"
+        }
+
+        // Timestamps in the session time zone: between versions 5 and 6 selects version 5.
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "timestamp"="2026-09-29 14:51:58"')}")
+            contains "lanceVersion=5"
+        }
+        sql """SET time_zone = 'Asia/Shanghai'"""
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "timestamp"="2026-09-29 22:51:58.000"')}")
+            contains "lanceVersion=5"
+        }
+        sql """SET time_zone = 'UTC'"""
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "branch"="dev", "timestamp"="2999-01-01 00:00:00"')}")
+            contains "lanceVersion=6"
+            contains "lanceBranch=dev"
+        }
+        // Between dev versions 5 and 6: ignoring the time would select dev version 6, and resolving
+        // it on main would select main version 7.
+        explain {
+            sql("SELECT row_id FROM ${vectorSearch(', "branch"="dev", "timestamp"="2026-09-29 14:52:18"')}")
+            contains "lanceVersion=5"
+            contains "lanceBranch=dev"
+        }
+        test {
+            sql """SELECT row_id FROM ${fullTextSearch(', "branch"="dev", "timestamp"="2026-09-29 14:52:18"', "strict")}"""
+            exception "dataset version 5 of branch 'dev' to be indexed"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "timestamp"="2026-09-29 14:51:51"')}"""
+            exception "Lance table default.search_snapshot has no version at or before '2026-09-29 14:51:51'"
+        }
+
+        // Two-phase materialization reads the branch's rows, not main's fragment 2.
+        sql """SET enable_lance_lazy_materialization = true"""
+        String twoPhase = """
+            SELECT row_id, body, _distance
+            FROM ${vectorSearch(', "branch"="dev"', "[100,101,102,103]")}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        explain {
+            sql "verbose ${twoPhase}"
+            contains "VMaterializeNode"
+        }
+        qt_branch_two_phase "${twoPhase}"
+        // rel is version 5, where row 3 still exists; version 6 deleted it, so a second phase
+        // that reopened a later version would fetch fewer rows than it asked for.
+        String tagTwoPhase = """
+            SELECT row_id, body, _distance
+            FROM ${vectorSearch(', "tag"="rel"', "[3.25,4.25,5.25,6.25]")}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        explain {
+            sql "verbose ${tagTwoPhase}"
+            contains "VMaterializeNode"
+        }
+        qt_tag_two_phase "${tagTwoPhase}"
+        // The second phase fetches the payload by the column names of the planned version: vec
+        // exists only up to version 3, note only from version 3 and embedding only from version 4,
+        // so fetching from any other version fails.
+        String evolvedTwoPhase = """
+            SELECT row_id, embedding, note, body, _distance
+            FROM ${evolvedSearch("embedding", ', "version"="4"')}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        explain {
+            sql "verbose ${evolvedTwoPhase}"
+            contains "VMaterializeNode"
+        }
+        qt_evolved_two_phase "${evolvedTwoPhase}"
+        String evolvedOldTwoPhase = """
+            SELECT row_id, vec, note, body, _distance
+            FROM ${evolvedSearch("vec", ', "version"="3"')}
+            ORDER BY _distance
+            LIMIT 3
+        """
+        explain {
+            sql "verbose ${evolvedOldTwoPhase}"
+            contains "VMaterializeNode"
+        }
+        qt_evolved_old_two_phase "${evolvedOldTwoPhase}"
+        sql """SET enable_lance_lazy_materialization = ${originalLazy}"""
+
+        // Schema changes: each search binds the column names, the index and the fragments of the
+        // version it reads. The rename keeps the field id, so vec_idx serves embedding.
+        qt_evolved_version_2 """
+            SELECT row_id, _distance FROM ${evolvedSearch("vec", ', "version"="2"')} ORDER BY _distance, row_id
+        """
+        qt_evolved_version_4 """
+            SELECT row_id, _distance FROM ${evolvedSearch("embedding", ', "version"="4"')}
+            ORDER BY _distance, row_id
+        """
+        for (String version : ["2", "4"]) {
+            String column = version == "2" ? "vec" : "embedding"
+            explain {
+                sql("SELECT row_id FROM ${evolvedSearch(column, ', "version"="' + version + '"')}")
+                contains "lanceVersion=${version}"
+                contains "lanceVectorColumn=${column}"
+                contains "lanceVectorIndexStatus=USED"
+                contains "lanceSearchIndexFragments=1"
+                contains "lanceSearchUnindexedFragments=0"
+            }
+        }
+        qt_evolved_latest """
+            SELECT row_id, _distance FROM ${evolvedSearch("embedding", "", "[12.25,13.25,14.25,15.25]")}
+            ORDER BY _distance, row_id
+        """
+        explain {
+            sql("SELECT row_id FROM ${evolvedSearch("embedding", "")}")
+            contains "lanceVersion=5"
+            contains "lanceSearchIndexFragments=1"
+            contains "lanceSearchUnindexedFragments=1"
+        }
+        test {
+            sql """SELECT row_id FROM ${evolvedSearch("embedding", ', "version"="2"')}"""
+            exception "Lance vector column 'embedding' does not exist"
+        }
+        test {
+            sql """SELECT row_id FROM ${evolvedSearch("vec", ', "version"="4"')}"""
+            exception "Lance vector column 'vec' does not exist"
+        }
+        test {
+            sql """SELECT row_id, note FROM ${evolvedSearch("vec", ', "version"="2"')}"""
+            exception "Unknown column 'note'"
+        }
+
+        // A selector that cannot be resolved fails; nothing falls back to the latest version.
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "version"="99"')}"""
+            exception "Lance version 99 of default.search_snapshot was not found"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "tag"="nope"')}"""
+            exception "Lance tag 'nope' of default.search_snapshot was not found"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "branch"="nope"')}"""
+            exception "Lance branch 'nope' of default.search_snapshot was not found"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "branch"="dev", "version"="9"')}"""
+            exception "Lance version 9 of default.search_snapshot@dev was not found"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "version"="2", "timestamp"="2026-09-29 14:51:58"')}"""
+            exception "'version' and 'timestamp' are mutually exclusive"
+        }
+        test {
+            sql """SELECT row_id FROM ${fullTextSearch(', "tag"="rel", "branch"="dev"')}"""
+            exception "'tag' and 'branch' are mutually exclusive"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "version"="rel"')}"""
+            exception "'version' must be a positive integer, but was 'rel'"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "branch"=""')}"""
+            exception "'branch' must not be empty"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "timestamp"="1790693517507"')}"""
+            exception "'timestamp' must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd HH:mm:ss.SSS'"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch("", "[0,1,2,3]", "3", table + "@branch(dev)")}"""
+            exception "use the 'version', 'timestamp', 'tag' or 'branch' property"
+        }
+
+        // Cleanup: a removed version is missing, and a kept version whose index files are gone
+        // fails at execution instead of searching another version.
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "version"="1"', "[0,1,2,3]", "3", pruned)}"""
+            exception "Lance version 1 of default.search_snapshot_pruned was not found"
+        }
+        test {
+            sql """SELECT row_id FROM ${vectorSearch(', "tag"="kept"', "[0,1,2,3]", "3", pruned)}"""
+            exception "at Lance dataset version 2 at s3://warehouse/lance/search_snapshot_pruned.lance failed"
+        }
+        qt_pruned_latest """
+            SELECT row_id, _distance FROM ${vectorSearch("", "[0,1,2,3]", "3", pruned)}
+            ORDER BY _distance, row_id
+        """
+    } finally {
+        sql """SET enable_file_scanner_v2 = ${originalScannerV2}"""
+        sql """SET time_zone = '${originalTimeZone}'"""
+        sql """SET enable_lance_lazy_materialization = ${originalLazy}"""
+        sql """DROP CATALOG IF EXISTS `${catalogName}`"""
+    }
+}
diff --git a/regression-test/suites/external_table_p0/lance/test_lance_vector_search_legacy_index.groovy b/regression-test/suites/external_table_p0/lance/test_lance_vector_search_legacy_index.groovy
new file mode 100644
index 00000000000..e2e5da1ae5b
--- /dev/null
+++ b/regression-test/suites/external_table_p0/lance/test_lance_vector_search_legacy_index.groovy
@@ -0,0 +1,90 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+suite("test_lance_vector_search_legacy_index", "p0,external") {
+    /*
+     * A vector index without index details, as Lance writers before 0.20 produced. Lance infers
+     * the missing details from the index files when it loads the index, so the FE plans the
+     * index like any other and the BE searches it through the planned segment. A split without
+     * index segments always searches flat, so a legacy index the FE skipped would lose ANN.
+     *
+     * Fixture: legacy_vector_index.lance (see lance_build_legacy_vector_index.py), written by
+     * pylance 0.18.2: row_id 1..512 in fragment 0, vec = [row_id, row_id + 1, row_id + 2,
+     * row_id + 3], and vec_idx (IVF_PQ, l2, 2 partitions, 2 sub-vectors) over fragment 0. The
+     * squared L2 distance between rows r and n is 4 * (n - r)^2; refine_factor recomputes it
+     * from the stored vectors, so the indexed search returns the flat search's rows.
+     */
+    String enabled = context.config.otherConfigs.get("enableIcebergTest")
+    if (enabled == null || !enabled.equalsIgnoreCase("true")) {
+        logger.info("disable Lance legacy vector index test because the Iceberg MinIO environment is disabled.")
+        return
+    }
+
+    String externalEnvIp = context.config.otherConfigs.get("externalEnvIp")
+    String minioPort = context.config.otherConfigs.get("iceberg_minio_port")
+    String catalogName = "test_lance_vector_search_legacy_index"
+    String tableName = "${catalogName}.`default`.legacy_vector_index"
+    // The query sits a quarter step past row 100, so no two rows tie.
+    String query = "[100.25,101.25,102.25,103.25]"
+    def search = { String options ->
+        """vector_search("table"="${tableName}", "column"="vec", "query_vector"="${query}", "top_k"="3", "metric"="l2"${options})"""
+    }
+    String originalScannerV2 = (sql """SHOW VARIABLES LIKE 'enable_file_scanner_v2'""")[0][1].toString()
+
+    sql """DROP CATALOG IF EXISTS `${catalogName}`"""
+    try {
+        sql """SET enable_file_scanner_v2 = true"""
+        sql """
+            CREATE CATALOG `${catalogName}` PROPERTIES (
+                "type" = "lance",
+                "lance.catalog.type" = "filesystem",
+                "warehouse" = "s3://warehouse/lance",
+                "s3.endpoint" = "http://${externalEnvIp}:${minioPort}",
+                "s3.access_key" = "admin",
+                "s3.secret_key" = "password",
+                "s3.region" = "us-east-1",
+                "use_path_style" = "true"
+            )
+        """
+
+        explain {
+            sql("SELECT row_id FROM ${search(', "nprobes"="2", "refine_factor"="4"')}")
+            contains "lanceVectorIndexStatus=USED"
+            contains "lanceVersion=2"
+            contains "lanceSearchIndexSegments=1"
+            contains "lanceSearchIndexFragments=1"
+            contains "lanceSearchUnindexedFragments=0"
+        }
+        qt_legacy_indexed """
+            SELECT row_id, _distance FROM ${search(', "nprobes"="2", "refine_factor"="4"')}
+            ORDER BY _distance, row_id
+        """
+        qt_legacy_flat """
+            SELECT row_id, _distance FROM ${search(', "use_index"="false"')}
+            ORDER BY _distance, row_id
+        """
+        // Before the index was built, the same search plans no index.
+        explain {
+            sql("SELECT row_id FROM ${search(', "version"="1"')}")
+            contains "lanceVectorIndexStatus=NO_MATCH"
+            contains "lanceSearchUnindexedFragments=1"
+        }
+    } finally {
+        sql """SET enable_file_scanner_v2 = ${originalScannerV2}"""
+        sql """DROP CATALOG IF EXISTS `${catalogName}`"""
+    }
+}


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org