feat(search): document and validate calibrated effort tiers (#4882)

Lance beta.11 calibrates lower `search_effort` tiers by metric and
requested `k`. With the Rust dependency and Python/Node execution tests
already on main via #4881, document the tiers across Rust, Python, Node
and the search guide, extend the remote request matrix to cover `0.1`
and `0.25`, and align the Python test package with beta.11.

`0.1` and `0.25` target empirical mean partition-routing recall of 80%
and 90% for L2, cosine and dot through `k=100000`. These are not
per-query or final Recall@k guarantees. Default Auto is unchanged;
Hamming and larger `k` remain uncalibrated, and remote queries require
corresponding server support. This PR makes no additional performance
claim. See [Lance
#10695](https://github.com/lance-format/lance/pull/10695) for
measurements and limitations.

Validation: both strict workspace Clippy configurations, Rust
formatting, 13 Rust effort tests, 208 Python query tests, 41 Node query
tests, native binding builds, TypeScript, Node lint/generated docs,
Python lint/format, full lockfile check and two dependency guards passed
on `a8b09170`. All validated Rust/Python/Node source and dependency
files are byte-identical at `2a82d07c`; the only subsequent change
restores the Java POM to main. Root Ruff has 59 existing diagnostics and
six formatting files, all byte-identical to the base; the Python package
passes.

The Java REST/Namespace client has no changed API here, and its
dependency remains identical to main. The separate [Java beta
publication failure](https://github.com/lance-format/lance/issues/10773)
is not claimed resolved or validated. Official SDK release, automatic
mirror, Sophon adoption and measured consumer acceptance remain
follow-up stages.
This commit is contained in:
Yang Cen
2026-11-06 17:37:52 +08:00
committed by GitHub
parent 06fcd628cf
commit a9028ef441
8 changed files with 59 additions and 11 deletions
+5
View File
@@ -854,6 +854,11 @@ export class VectorQuery extends StandardQueryBase<NativeVectorQuery> {
/**
* Set the initial IVF search effort to a finite value in [0, 1].
*
* Efforts 0.1 and 0.25 target empirical mean partition-routing recall of
* 80% and 90% for L2, cosine and dot through k=100000. The probe budget
* adapts to the metric and k. Hamming and larger k remain uncalibrated;
* 100000 is not an API limit. Remote queries also require server support.
*
* The default, null, uses Auto (internally 0.5). Zero starts at the caller
* minimum; one searches all partitions within the caller maximum. Later
* probing may continue when too few candidates are found.