Skip to content

perf(vindex): read search indexes through positional ranges - #645

Merged
JingsongLi merged 1 commit into
apache:mainfrom
JunRuiLee:perf/vindex-range-read
Aug 3, 2026
Merged

perf(vindex): read search indexes through positional ranges#645
JingsongLi merged 1 commit into
apache:mainfrom
JunRuiLee:perf/vindex-range-read

Conversation

@JunRuiLee

@JunRuiLee JunRuiLee commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Purpose

This is PR 1/3 of a stacked vector-search performance series.

The regular/global-index vindex path currently buffers the complete index file
before search. For large indexes, a single query usually needs only metadata and
a subset of posting lists, so the full read adds unnecessary I/O and peak memory.

This change adds a safe positional-read foundation and switches the single-query
regular/global-index vindex path
to it.

Scope boundary

Brief change log

  • Add a SeekRead adapter backed by Paimon's asynchronous FileRead.
  • Poll asynchronous storage reads on the caller's Tokio runtime instead of a
    second runtime.
  • Return UnexpectedError instead of panicking when range-backed vindex search is
    driven outside a Tokio runtime.
  • Run synchronous vindex and Lumina search work on a dedicated executor, avoiding
    block_in_place and host blocking-pool deadlocks.
  • Honor global-index.thread-num as the per-query file fan-out while separating
    that logical limit from the process executor's physical OS-thread cap.
  • Bound physical workers to max(32, 4 * available_parallelism) and reclaim
    growth workers after one idle minute, while retaining the CPU-sized baseline.
  • Preserve strict sequential execution for a query when
    global-index.thread-num = 1.
  • Validate requested ranges and report short reads explicitly.
  • Coalesce nearby reads with bounded read amplification and share the range-I/O
    semaphore across cloned readers.
  • Forward try_clone_reader and read capabilities through the type-erased vindex
    input adapter; the range reader deliberately reports storage-agnostic defaults
    because it accepts arbitrary range counts and the optimal window is backend-specific.
  • Keep queued-task cancellation cheap and avoid blocking a current-thread Tokio
    runtime when an already-started search is cancelled.

Tests

  • cargo test -p paimon vindex --lib — 118 passed
  • cargo test -p paimon test_global_index_thread_num --lib — 2 passed
  • cargo test -p paimon --test pk_vector_baseline_test — 8 passed
  • cargo test -p paimon --test pk_vector_batch_test — 10 passed
  • cargo test -p paimon --test pk_vector_java_fixture_test — 1 passed
  • python3 scripts/dependencies.py verify
  • python3 scripts/release_licenses.py --check — 21 generated legal files validated
  • cargo fmt --all -- --check
  • git diff --check

Coverage includes caller-runtime polling, a non-Tokio error path, current-thread runtimes, clone support,
short reads, bounded coalescing, physical worker clamping, idle worker reclamation,
and local filesystem reads when the host blocking pool has only one thread.

API and Format

No public API or storage-format changes.

Documentation

The existing global-index.thread-num API documentation now includes regular
vector global-index search. No user-facing storage or query API changes are required.

@JunRuiLee
JunRuiLee force-pushed the perf/vindex-range-read branch 4 times, most recently from e2d4574 to de9cdcc Compare August 1, 2026 07:44
@JunRuiLee
JunRuiLee marked this pull request as ready for review August 1, 2026 08:12
@JunRuiLee
JunRuiLee force-pushed the perf/vindex-range-read branch from de9cdcc to f86649d Compare August 1, 2026 09:00
@JunRuiLee
JunRuiLee marked this pull request as draft August 1, 2026 09:01
@JunRuiLee
JunRuiLee marked this pull request as ready for review August 1, 2026 09:31
@JunRuiLee
JunRuiLee force-pushed the perf/vindex-range-read branch from f86649d to 9b31e1e Compare August 1, 2026 12:16

@JingsongLi JingsongLi left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@JingsongLi
JingsongLi merged commit 8cd1166 into apache:main Aug 3, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants