Skip to content

[core] Support batch vector search - #7857

Merged
JingsongLi merged 1 commit into
apache:masterfrom
XiaoHongbo-Hope:batch_vector_search
Jun 18, 2026
Merged

[core] Support batch vector search#7857
JingsongLi merged 1 commit into
apache:masterfrom
XiaoHongbo-Hope:batch_vector_search

Conversation

@XiaoHongbo-Hope

@XiaoHongbo-Hope XiaoHongbo-Hope commented May 14, 2026

Copy link
Copy Markdown
Contributor

Purpose

Tests

@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.

This batch query is not meaningful for performance, we need to ensure that the local file cache is enabled. See ce38b2c

@XiaoHongbo-Hope

Copy link
Copy Markdown
Contributor Author

This batch query is not meaningful for performance, we need to ensure that the local file cache is enabled. See ce38b2c

Do you mean we should add a validation for local-cache.enabled=true?

@XiaoHongbo-Hope
XiaoHongbo-Hope force-pushed the batch_vector_search branch 3 times, most recently from 1e339c3 to 6f73663 Compare June 2, 2026 05:52
@apache apache deleted a comment from JingsongLi Jun 2, 2026
@XiaoHongbo-Hope

XiaoHongbo-Hope commented Jun 2, 2026

Copy link
Copy Markdown
Contributor Author

@JingsongLi Sorry, I accidentally deleted your comment while trying to reply.

I want to confirm if I understood your point correctly.

Batch query vectors share one scan and one reader/native index loading per split within one invocation. Do you mean that local file cache for meta/global-index files is sufficient for repeated single-vector queries, so the reader/native-index reuse provided by this batch API is not necessary?

@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.

Maybe we can introduce a new BatchVectorSearch?

@JingsongLi

Copy link
Copy Markdown
Contributor

Also, how is the return value handled? How do users know which input corresponds to which one?

@XiaoHongbo-Hope
XiaoHongbo-Hope force-pushed the batch_vector_search branch 2 times, most recently from 973c670 to a417c1a Compare June 11, 2026 07:26
@XiaoHongbo-Hope

Copy link
Copy Markdown
Contributor Author

Also, how is the return value handled? How do users know which input corresponds to which one?

Results keep the same order as input vectors — results.get(i) corresponds to queryVectors[i]

@XiaoHongbo-Hope
XiaoHongbo-Hope force-pushed the batch_vector_search branch 4 times, most recently from 2dc3a71 to 93b02e6 Compare June 11, 2026 10:01
@XiaoHongbo-Hope

Copy link
Copy Markdown
Contributor Author

This batch query is not meaningful for performance, we need to ensure that the local file cache is enabled. See ce38b2c

I ran an OSS benchmark with a 529MB Lumina index, 100 queries, dim=1024.

  Without Paimon local cache:
  - user-level loop: 188.6s
  - batch: 39.7s

  With warm local memory cache:
  - user-level loop: 41.4s
  - batch: 39.7s

So without cache, batch is effective. With warm cache, the benefit is very small, which matches your
point.

Since users need a batch API, for the Spark/Flink batch API, which direction do you prefer?

  1. implement it by looping single-vector search internally and relying on local cache;
  2. continue this PR and add a batch vector search/readBatch path.

@XiaoHongbo-Hope
XiaoHongbo-Hope force-pushed the batch_vector_search branch 2 times, most recently from 8285af1 to 424f109 Compare June 16, 2026 07:45
@XiaoHongbo-Hope

Copy link
Copy Markdown
Contributor Author

@JingsongLi @yunfengzhou-hub Could you help take a look again when you are free

@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.

My suggestion is that the API design should not be mixed with previous single search, and there should also be a corresponding BatchVectorSearchBuilder.

@JingsongLi

Copy link
Copy Markdown
Contributor

And we should also support Python api.

@XiaoHongbo-Hope
XiaoHongbo-Hope force-pushed the batch_vector_search branch 4 times, most recently from 223dbd3 to a15f65a Compare June 18, 2026 03:45
Add batch vector search: one call searches multiple query vectors against a
vector column, with result i corresponding to query vector i.

- New BatchVectorSearch predicate and GlobalIndexReader.visitBatchVectorSearch
  with a concurrent per-vector fan-out default for indexes without a native
  batch path.
- Lumina and paimon-vector-index (IVF) readers override it to run all vectors
  in a single native call; single-vector batches short-circuit to the scalar
  path. Shared filter/offset/scoring logic is factored out (VectorSearchUtils,
  resolveScope/SearchScope, buildScoredResult).
- Dedicated BatchVectorSearchBuilder (Java) / BatchVectorSearchBuilder
  (pypaimon), kept separate from the single-vector builder, exposed via
  Table.newBatchVectorSearchBuilder(). The new Table method is a default
  (Java) / non-abstract (Python) so the @public interface stays compatible
  for external implementations; options are defensively copied and inputs
  validated up front.
- Tests across core, Lumina, paimon-vector-index and pypaimon, plus docs.
@JingsongLi

Copy link
Copy Markdown
Contributor

+1

@JingsongLi
JingsongLi merged commit f7d77e7 into apache:master Jun 18, 2026
18 of 19 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