You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pinot.apache.org by xi...@apache.org on 2026/04/07 09:19:17 UTC
(pinot) branch master updated: Add vector query execution semantics: filtered ANN, threshold search, and compound retrieval (Phase 3) (#18114)
This is an automated email from the ASF dual-hosted git repository.
xiangfu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pinot.git
The following commit(s) were added to refs/heads/master by this push:
new 6753e95e7f6 Add vector query execution semantics: filtered ANN, threshold search, and compound retrieval (Phase 3) (#18114)
6753e95e7f6 is described below
commit 6753e95e7f676603a9d509d9821cc2317267d0f6
Author: Xiang Fu <xi...@apache.org>
AuthorDate: Tue Apr 7 02:19:10 2026 -0700
Add vector query execution semantics: filtered ANN, threshold search, and compound retrieval (Phase 3) (#18114)
* Add explicit vector query execution semantics with filtered ANN, threshold search, and compound retrieval (Phase 3)
Introduces backend capability model, execution mode enum (8 modes), filtered ANN
with candidate over-fetch, approximate threshold/radius search via exact refinement,
compound query patterns, and execution mode reporting in explain output. All existing
VECTOR_SIMILARITY queries remain backward compatible with no SQL changes required.
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Remove docs folder from tracked files
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Simplify filtered vector detection in FilterPlanNode
Replace pre-scan with inline check: isVectorSimilarityFilter(childFilter) && childFilters.size() > 1.
Remove unused hasVectorSimilarityChild helper.
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Add warning when threshold refinement skipped due to missing forward index
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Fix adversarial review findings: immutable bitmap return, volatile snapshot, enum switch comment
- ExactVectorScanFilterOperator.computeExactThreshold: call toImmutableRoaringBitmap()
- VectorSimilarityFilterOperator.applyThresholdRefinement: snapshot volatile _vectorExplainContext
- VectorBackendType.buildCapabilities: add comment explaining why name() is used in switch
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Adjust benchmark thresholds for 128-dim Gaussian vectors
L2 squared distances average ~256 for 128-dim Gaussian vectors.
Use thresholds 200/240/260 to produce meaningful result counts.
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Add Phase 3 integration tests for filtered ANN, threshold search, and compound retrieval
Tests cover:
- Basic top-K backward compatibility
- Filtered ANN (vector + metadata filter AND)
- Filtered ANN reduces result count
- Threshold/radius search with vectorDistanceThreshold
- Compound filter + threshold
- Execution mode in EXPLAIN output
- Filtered ANN mode in EXPLAIN output
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Merge Phase 3 integration tests into existing VectorTest and IvfFlatVectorTest
VectorTest (HNSW/COSINE):
- Add category column for filtered ANN testing
- testFilteredAnn: vector + metadata filter AND, verify filter + ordering
- testFilteredAnnReducesResults: filtered count <= unfiltered count
- testExplainShowsExecutionMode: execution mode in EXPLAIN output
IvfFlatVectorTest (IVF_FLAT/EUCLIDEAN):
- Add category column for compound query testing
- testThresholdSearch: vectorDistanceThreshold returns within-distance results
- testCompoundFilterAndThreshold: filter + threshold, both conditions verified
Removes standalone VectorPhase3QuerySemanticsTest.
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Address PR review comments
1. Threshold mode now honors explicit vectorMaxCandidates via
getEffectiveMaxCandidates instead of falling through to topK
2. Remove unused capabilities parameter from selectExecutionMode;
the method now takes 4 boolean args instead of 4 booleans + capabilities
3. FilterPlanNode sets hasMetadataFilter only when AND has a non-vector
sibling (hasNonVectorSibling), not just any sibling
4. Strengthen EXPLAIN assertion in VectorTest to require executionMode
presence rather than accepting VECTOR_SIMILARITY as a fallback
5. Replace brittle testModeCount (hardcoded 8) with testExpectedModesExist
that asserts each expected mode by name
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Fix filtered ANN over-fetch returning more than topK docs
Remove the 2x over-fetch for filtered ANN queries. vectorSimilarity(col, q, 10)
must return at most 10 docs regardless of metadata filters. The bitmap AND with
the metadata filter correctly reduces the result set.
Also document the approximate nature of threshold search via ANN candidates:
recall is limited by the candidate pool size (vectorMaxCandidates).
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
* Fail fast when threshold requires missing forward index; trim threshold input; document FILTER_THEN_ANN as reserved
- Throw IllegalStateException when vectorDistanceThreshold is set but forward
index is unavailable (instead of silently returning raw ANN results)
- Add Preconditions.checkState in FilterPlanNode for early detection
- Trim whitespace before parsing vectorDistanceThreshold for robustness
- Add Javadoc to FILTER_THEN_ANN clarifying it is reserved for future backends
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <no...@anthropic.com>
---
.../common/utils/config/QueryOptionsUtils.java | 24 ++
.../filter/ExactVectorScanFilterOperator.java | 64 ++++-
.../core/operator/filter/VectorExplainContext.java | 22 ++
.../filter/VectorQueryExecutionContext.java | 233 ++++++++++++++++++
.../core/operator/filter/VectorSearchParams.java | 41 +++-
.../filter/VectorSimilarityFilterOperator.java | 112 ++++++++-
.../org/apache/pinot/core/plan/FilterPlanNode.java | 59 ++++-
.../operator/filter/VectorCompoundQueryTest.java | 232 ++++++++++++++++++
.../filter/VectorQueryExecutionContextTest.java | 203 ++++++++++++++++
.../operator/filter/VectorSearchParamsTest.java | 41 ++++
.../filter/VectorSimilarityFilterOperatorTest.java | 147 ++++++++++++
.../tests/custom/IvfFlatVectorTest.java | 84 ++++++-
.../pinot/integration/tests/custom/VectorTest.java | 87 +++++++
.../apache/pinot/perf/BenchmarkVectorPhase3.java | 264 +++++++++++++++++++++
.../index/creator/VectorBackendCapabilities.java | 149 ++++++++++++
.../spi/index/creator/VectorBackendType.java | 46 ++++
.../spi/index/creator/VectorExecutionMode.java | 150 ++++++++++++
.../creator/VectorBackendCapabilitiesTest.java | 120 ++++++++++
.../spi/index/creator/VectorExecutionModeTest.java | 101 ++++++++
.../apache/pinot/spi/utils/CommonConstants.java | 5 +
20 files changed, 2160 insertions(+), 24 deletions(-)
diff --git a/pinot-common/src/main/java/org/apache/pinot/common/utils/config/QueryOptionsUtils.java b/pinot-common/src/main/java/org/apache/pinot/common/utils/config/QueryOptionsUtils.java
index 1ccc0d2b8a6..0e5649899bb 100644
--- a/pinot-common/src/main/java/org/apache/pinot/common/utils/config/QueryOptionsUtils.java
+++ b/pinot-common/src/main/java/org/apache/pinot/common/utils/config/QueryOptionsUtils.java
@@ -705,6 +705,30 @@ public class QueryOptionsUtils {
return checkedParseIntPositive(QueryOptionKey.VECTOR_MAX_CANDIDATES, maxCandidates);
}
+ /**
+ * Returns the distance threshold for vector radius/threshold search, or {@code null} if not set.
+ */
+ @Nullable
+ public static Float getVectorDistanceThreshold(Map<String, String> queryOptions) {
+ String threshold = queryOptions.get(QueryOptionKey.VECTOR_DISTANCE_THRESHOLD);
+ if (threshold == null) {
+ return null;
+ }
+ try {
+ float value = Float.parseFloat(threshold.trim());
+ if (Float.isNaN(value) || Float.isInfinite(value)) {
+ throw new IllegalArgumentException(
+ QueryOptionKey.VECTOR_DISTANCE_THRESHOLD + " must be a finite number, got: " + threshold);
+ }
+ // Negative thresholds are valid for dot-product/inner-product distance functions
+ // where VectorDistanceUtils.computeDistance returns negated dot product.
+ return value;
+ } catch (NumberFormatException e) {
+ throw new IllegalArgumentException(
+ QueryOptionKey.VECTOR_DISTANCE_THRESHOLD + " must be a valid number, got: " + threshold);
+ }
+ }
+
public static int getSortExchangeCopyThreshold(Map<String, String> options, int i) {
String sortExchangeCopyThreshold = options.get(QueryOptionKey.SORT_EXCHANGE_COPY_THRESHOLD);
if (sortExchangeCopyThreshold != null) {
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/ExactVectorScanFilterOperator.java b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/ExactVectorScanFilterOperator.java
index 39f76f07782..6186d249aef 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/ExactVectorScanFilterOperator.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/ExactVectorScanFilterOperator.java
@@ -29,6 +29,7 @@ import org.apache.pinot.core.common.BlockDocIdSet;
import org.apache.pinot.core.common.Operator;
import org.apache.pinot.core.operator.ExplainAttributeBuilder;
import org.apache.pinot.core.operator.docidsets.BitmapDocIdSet;
+import org.apache.pinot.segment.spi.index.creator.VectorExecutionMode;
import org.apache.pinot.segment.spi.index.creator.VectorIndexConfig;
import org.apache.pinot.segment.spi.index.reader.ForwardIndexReader;
import org.apache.pinot.segment.spi.index.reader.ForwardIndexReaderContext;
@@ -66,6 +67,8 @@ public class ExactVectorScanFilterOperator extends BaseFilterOperator {
private final VectorSimilarityPredicate _predicate;
private final String _column;
private final VectorExplainContext _vectorExplainContext;
+ private final boolean _hasDistanceThreshold;
+ private final float _distanceThreshold;
private ImmutableRoaringBitmap _matches;
/**
@@ -78,19 +81,29 @@ public class ExactVectorScanFilterOperator extends BaseFilterOperator {
*/
public ExactVectorScanFilterOperator(ForwardIndexReader<?> forwardIndexReader,
VectorSimilarityPredicate predicate, String column, int numDocs) {
- this(forwardIndexReader, predicate, column, numDocs, null, "vector_index_missing");
+ this(forwardIndexReader, predicate, column, numDocs, null, "vector_index_missing",
+ VectorSearchParams.DEFAULT);
}
public ExactVectorScanFilterOperator(ForwardIndexReader<?> forwardIndexReader,
VectorSimilarityPredicate predicate, String column, int numDocs, @Nullable VectorIndexConfig vectorIndexConfig,
String fallbackReason) {
+ this(forwardIndexReader, predicate, column, numDocs, vectorIndexConfig, fallbackReason,
+ VectorSearchParams.DEFAULT);
+ }
+
+ public ExactVectorScanFilterOperator(ForwardIndexReader<?> forwardIndexReader,
+ VectorSimilarityPredicate predicate, String column, int numDocs, @Nullable VectorIndexConfig vectorIndexConfig,
+ String fallbackReason, VectorSearchParams searchParams) {
super(numDocs, false);
_forwardIndexReader = forwardIndexReader;
_predicate = predicate;
_column = column;
+ _hasDistanceThreshold = searchParams.hasDistanceThreshold();
+ _distanceThreshold = searchParams.getDistanceThreshold();
_vectorExplainContext = new VectorExplainContext(VectorDistanceUtils.resolveBackendType(vectorIndexConfig),
- VectorDistanceUtils.resolveDistanceFunction(vectorIndexConfig), VectorSearchParams.DEFAULT_NPROBE, false,
- predicate.getTopK(), fallbackReason);
+ VectorDistanceUtils.resolveDistanceFunction(vectorIndexConfig), VectorExecutionMode.EXACT_SCAN,
+ VectorSearchParams.DEFAULT_NPROBE, false, predicate.getTopK(), fallbackReason);
}
@Override
@@ -132,6 +145,7 @@ public class ExactVectorScanFilterOperator extends BaseFilterOperator {
public String toExplainString() {
return EXPLAIN_NAME + "(indexLookUp:exact_scan"
+ ", operator:" + _predicate.getType()
+ + ", executionMode:" + VectorExecutionMode.EXACT_SCAN
+ ", vector identifier:" + _column
+ ", backend:" + _vectorExplainContext.getBackendType()
+ ", distanceFunction:" + _vectorExplainContext.getDistanceFunction()
@@ -151,6 +165,7 @@ public class ExactVectorScanFilterOperator extends BaseFilterOperator {
super.explainAttributes(attributeBuilder);
attributeBuilder.putString("indexLookUp", "exact_scan");
attributeBuilder.putString("operator", _predicate.getType().name());
+ attributeBuilder.putString("executionMode", VectorExecutionMode.EXACT_SCAN.name());
attributeBuilder.putString("vectorIdentifier", _column);
attributeBuilder.putString("backend", _vectorExplainContext.getBackendType().name());
attributeBuilder.putString("distanceFunction", _vectorExplainContext.getDistanceFunction().name());
@@ -161,15 +176,23 @@ public class ExactVectorScanFilterOperator extends BaseFilterOperator {
/**
* Performs brute-force exact search over all documents in the segment.
- * Uses a max-heap to maintain the top-K closest vectors.
+ * When a distance threshold is set, returns all vectors within the threshold.
+ * Otherwise uses a max-heap to maintain the top-K closest vectors.
*/
@SuppressWarnings("unchecked")
private ImmutableRoaringBitmap computeExactTopK() {
LOGGER.warn("Performing exact vector scan fallback on column: {} for segment with {} docs. "
- + "reason={}, distanceFunction={}. This is expensive -- consider adding a vector index.",
- _column, _numDocs, _vectorExplainContext.getFallbackReason(), _vectorExplainContext.getDistanceFunction());
+ + "reason={}, distanceFunction={}, hasThreshold={}. "
+ + "This is expensive -- consider adding a vector index.",
+ _column, _numDocs, _vectorExplainContext.getFallbackReason(),
+ _vectorExplainContext.getDistanceFunction(), _hasDistanceThreshold);
float[] queryVector = _predicate.getValue();
+
+ if (_hasDistanceThreshold) {
+ return computeExactThreshold(queryVector);
+ }
+
int topK = _predicate.getTopK();
// Max-heap: entry with largest distance is at the top so we can efficiently evict it
@@ -207,6 +230,35 @@ public class ExactVectorScanFilterOperator extends BaseFilterOperator {
return result;
}
+ /**
+ * Performs brute-force threshold scan: returns all vectors within the distance threshold.
+ */
+ @SuppressWarnings("unchecked")
+ private ImmutableRoaringBitmap computeExactThreshold(float[] queryVector) {
+ MutableRoaringBitmap result = new MutableRoaringBitmap();
+ ForwardIndexReader rawReader = _forwardIndexReader;
+ try (ForwardIndexReaderContext context = rawReader.createContext()) {
+ for (int docId = 0; docId < _numDocs; docId++) {
+ float[] docVector = rawReader.getFloatMV(docId, context);
+ if (docVector == null || docVector.length == 0) {
+ continue;
+ }
+ float distance = VectorDistanceUtils.computeDistance(queryVector, docVector,
+ _vectorExplainContext.getDistanceFunction());
+ if (distance <= _distanceThreshold) {
+ result.add(docId);
+ }
+ }
+ } catch (Exception e) {
+ throw new RuntimeException("Error during exact threshold scan on column: " + _column, e);
+ }
+
+ LOGGER.debug("Exact threshold scan on column: {} returned {} results from {} docs (threshold={})",
+ _column, result.getCardinality(), _numDocs, _distanceThreshold);
+
+ return result.toImmutableRoaringBitmap();
+ }
+
/**
* Computes the squared L2 (Euclidean) distance between two vectors.
* Delegates to {@link VectorFunctions#euclideanDistance(float[], float[])} which returns
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorExplainContext.java b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorExplainContext.java
index 6b65d24dbfa..005aea134cf 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorExplainContext.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorExplainContext.java
@@ -20,15 +20,20 @@ package org.apache.pinot.core.operator.filter;
import javax.annotation.Nullable;
import org.apache.pinot.segment.spi.index.creator.VectorBackendType;
+import org.apache.pinot.segment.spi.index.creator.VectorExecutionMode;
import org.apache.pinot.segment.spi.index.creator.VectorIndexConfig;
/**
* Runtime-visible vector metadata for explain and debug output.
+ *
+ * <p>Includes the {@link VectorExecutionMode} so that explain output makes the execution
+ * strategy explicit and understandable.</p>
*/
public final class VectorExplainContext {
private final VectorBackendType _backendType;
private final VectorIndexConfig.VectorDistanceFunction _distanceFunction;
+ private final VectorExecutionMode _executionMode;
private final int _effectiveNprobe;
private final boolean _effectiveExactRerank;
private final int _effectiveSearchCount;
@@ -38,8 +43,17 @@ public final class VectorExplainContext {
public VectorExplainContext(VectorBackendType backendType,
VectorIndexConfig.VectorDistanceFunction distanceFunction, int effectiveNprobe, boolean effectiveExactRerank,
int effectiveSearchCount, @Nullable String fallbackReason) {
+ this(backendType, distanceFunction, null, effectiveNprobe, effectiveExactRerank, effectiveSearchCount,
+ fallbackReason);
+ }
+
+ public VectorExplainContext(VectorBackendType backendType,
+ VectorIndexConfig.VectorDistanceFunction distanceFunction, @Nullable VectorExecutionMode executionMode,
+ int effectiveNprobe, boolean effectiveExactRerank, int effectiveSearchCount,
+ @Nullable String fallbackReason) {
_backendType = backendType;
_distanceFunction = distanceFunction;
+ _executionMode = executionMode;
_effectiveNprobe = effectiveNprobe;
_effectiveExactRerank = effectiveExactRerank;
_effectiveSearchCount = effectiveSearchCount;
@@ -54,6 +68,14 @@ public final class VectorExplainContext {
return _distanceFunction;
}
+ /**
+ * Returns the execution mode selected for this query, or null if not yet determined.
+ */
+ @Nullable
+ public VectorExecutionMode getExecutionMode() {
+ return _executionMode;
+ }
+
public int getEffectiveNprobe() {
return _effectiveNprobe;
}
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorQueryExecutionContext.java b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorQueryExecutionContext.java
new file mode 100644
index 00000000000..cedbed4d0f3
--- /dev/null
+++ b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorQueryExecutionContext.java
@@ -0,0 +1,233 @@
+/**
+ * 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.pinot.core.operator.filter;
+
+import javax.annotation.Nullable;
+import org.apache.pinot.segment.spi.index.creator.VectorBackendCapabilities;
+import org.apache.pinot.segment.spi.index.creator.VectorBackendType;
+import org.apache.pinot.segment.spi.index.creator.VectorExecutionMode;
+
+
+/**
+ * Captures the runtime execution plan for a vector query within a single segment.
+ *
+ * <p>This context is populated by the query planner (in {@code FilterPlanNode}) and carried
+ * through to the filter operator so that execution decisions are explicit and reportable.
+ * It is also surfaced in explain/debug output.</p>
+ *
+ * <p>The context is immutable once created. Use the {@link Builder} to construct instances.</p>
+ */
+public final class VectorQueryExecutionContext {
+
+ private final VectorExecutionMode _executionMode;
+ private final VectorBackendType _backendType;
+ private final VectorBackendCapabilities _capabilities;
+ private final boolean _exactRerank;
+ private final boolean _hasMetadataFilter;
+ private final boolean _hasThresholdPredicate;
+ private final int _topK;
+ private final int _candidateBudget;
+ private final float _distanceThreshold;
+ @Nullable
+ private final String _fallbackReason;
+
+ private VectorQueryExecutionContext(Builder builder) {
+ _executionMode = builder._executionMode;
+ _backendType = builder._backendType;
+ _capabilities = builder._capabilities;
+ _exactRerank = builder._exactRerank;
+ _hasMetadataFilter = builder._hasMetadataFilter;
+ _hasThresholdPredicate = builder._hasThresholdPredicate;
+ _topK = builder._topK;
+ _candidateBudget = builder._candidateBudget;
+ _distanceThreshold = builder._distanceThreshold;
+ _fallbackReason = builder._fallbackReason;
+ }
+
+ public VectorExecutionMode getExecutionMode() {
+ return _executionMode;
+ }
+
+ public VectorBackendType getBackendType() {
+ return _backendType;
+ }
+
+ public VectorBackendCapabilities getCapabilities() {
+ return _capabilities;
+ }
+
+ public boolean isExactRerank() {
+ return _exactRerank;
+ }
+
+ public boolean hasMetadataFilter() {
+ return _hasMetadataFilter;
+ }
+
+ public boolean hasThresholdPredicate() {
+ return _hasThresholdPredicate;
+ }
+
+ public int getTopK() {
+ return _topK;
+ }
+
+ public int getCandidateBudget() {
+ return _candidateBudget;
+ }
+
+ public float getDistanceThreshold() {
+ return _distanceThreshold;
+ }
+
+ @Nullable
+ public String getFallbackReason() {
+ return _fallbackReason;
+ }
+
+ @Override
+ public String toString() {
+ StringBuilder sb = new StringBuilder("VectorQueryExecutionContext{");
+ sb.append("mode=").append(_executionMode);
+ sb.append(", backend=").append(_backendType);
+ sb.append(", topK=").append(_topK);
+ if (_hasMetadataFilter) {
+ sb.append(", hasFilter=true");
+ }
+ if (_hasThresholdPredicate) {
+ sb.append(", threshold=").append(_distanceThreshold);
+ }
+ if (_exactRerank) {
+ sb.append(", rerank=true, candidateBudget=").append(_candidateBudget);
+ }
+ if (_fallbackReason != null) {
+ sb.append(", fallbackReason=").append(_fallbackReason);
+ }
+ sb.append('}');
+ return sb.toString();
+ }
+
+ /**
+ * Selects the execution mode for a vector query based on query shape.
+ *
+ * <p>This is the centralized decision point. The rules are conservative and explicit:</p>
+ * <ol>
+ * <li>No vector index -> EXACT_SCAN</li>
+ * <li>Threshold query + filter -> ANN_THRESHOLD_THEN_FILTER</li>
+ * <li>Threshold query (no filter) -> ANN_THRESHOLD_SCAN</li>
+ * <li>Filter + rerank -> ANN_THEN_FILTER_THEN_RERANK</li>
+ * <li>Filter (no rerank) -> ANN_THEN_FILTER</li>
+ * <li>Rerank (no filter) -> ANN_TOP_K_WITH_RERANK</li>
+ * <li>Plain top-K -> ANN_TOP_K</li>
+ * </ol>
+ */
+ public static VectorExecutionMode selectExecutionMode(boolean hasVectorIndex,
+ boolean hasMetadataFilter, boolean hasThresholdPredicate, boolean exactRerank) {
+ if (!hasVectorIndex) {
+ return VectorExecutionMode.EXACT_SCAN;
+ }
+ if (hasThresholdPredicate && hasMetadataFilter) {
+ return VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER;
+ }
+ if (hasThresholdPredicate) {
+ return VectorExecutionMode.ANN_THRESHOLD_SCAN;
+ }
+ if (hasMetadataFilter && exactRerank) {
+ return VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK;
+ }
+ if (hasMetadataFilter) {
+ return VectorExecutionMode.ANN_THEN_FILTER;
+ }
+ if (exactRerank) {
+ return VectorExecutionMode.ANN_TOP_K_WITH_RERANK;
+ }
+ return VectorExecutionMode.ANN_TOP_K;
+ }
+
+ public static final class Builder {
+ private VectorExecutionMode _executionMode = VectorExecutionMode.ANN_TOP_K;
+ private VectorBackendType _backendType = VectorBackendType.HNSW;
+ private VectorBackendCapabilities _capabilities;
+ private boolean _exactRerank;
+ private boolean _hasMetadataFilter;
+ private boolean _hasThresholdPredicate;
+ private int _topK;
+ private int _candidateBudget;
+ private float _distanceThreshold = Float.NaN;
+ private String _fallbackReason;
+
+ public Builder executionMode(VectorExecutionMode mode) {
+ _executionMode = mode;
+ return this;
+ }
+
+ public Builder backendType(VectorBackendType type) {
+ _backendType = type;
+ _capabilities = type.getCapabilities();
+ return this;
+ }
+
+ public Builder capabilities(VectorBackendCapabilities capabilities) {
+ _capabilities = capabilities;
+ return this;
+ }
+
+ public Builder exactRerank(boolean value) {
+ _exactRerank = value;
+ return this;
+ }
+
+ public Builder hasMetadataFilter(boolean value) {
+ _hasMetadataFilter = value;
+ return this;
+ }
+
+ public Builder hasThresholdPredicate(boolean value) {
+ _hasThresholdPredicate = value;
+ return this;
+ }
+
+ public Builder topK(int value) {
+ _topK = value;
+ return this;
+ }
+
+ public Builder candidateBudget(int value) {
+ _candidateBudget = value;
+ return this;
+ }
+
+ public Builder distanceThreshold(float value) {
+ _distanceThreshold = value;
+ return this;
+ }
+
+ public Builder fallbackReason(String reason) {
+ _fallbackReason = reason;
+ return this;
+ }
+
+ public VectorQueryExecutionContext build() {
+ if (_capabilities == null && _backendType != null) {
+ _capabilities = _backendType.getCapabilities();
+ }
+ return new VectorQueryExecutionContext(this);
+ }
+ }
+}
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSearchParams.java b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSearchParams.java
index d12eae6ecf5..6ad057deb1d 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSearchParams.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSearchParams.java
@@ -46,6 +46,8 @@ public final class VectorSearchParams {
private final Boolean _exactRerankOverride;
private final int _maxCandidates;
private final boolean _maxCandidatesExplicit;
+ private final float _distanceThreshold;
+ private final boolean _hasDistanceThreshold;
/**
* Constructs search params from raw query option values.
@@ -57,10 +59,26 @@ public final class VectorSearchParams {
*/
public VectorSearchParams(@Nullable Integer nprobe, @Nullable Boolean exactRerankOverride,
@Nullable Integer maxCandidates) {
+ this(nprobe, exactRerankOverride, maxCandidates, null);
+ }
+
+ /**
+ * Constructs search params from raw query option values.
+ *
+ * @param nprobe number of IVF probes, or null for default
+ * @param exactRerankOverride whether to re-score ANN candidates with exact distance, or null to use the backend
+ * default
+ * @param maxCandidates max candidates before final top-K, or null for default (topK * 10)
+ * @param distanceThreshold distance threshold for radius search, or null for top-K mode
+ */
+ public VectorSearchParams(@Nullable Integer nprobe, @Nullable Boolean exactRerankOverride,
+ @Nullable Integer maxCandidates, @Nullable Float distanceThreshold) {
_nprobe = nprobe != null ? nprobe : DEFAULT_NPROBE;
_exactRerankOverride = exactRerankOverride;
_maxCandidates = maxCandidates != null ? maxCandidates : 0;
_maxCandidatesExplicit = maxCandidates != null;
+ _distanceThreshold = distanceThreshold != null ? distanceThreshold : Float.NaN;
+ _hasDistanceThreshold = distanceThreshold != null;
}
/**
@@ -78,12 +96,13 @@ public final class VectorSearchParams {
Integer nprobe = QueryOptionsUtils.getVectorNprobe(queryOptions);
Boolean exactRerank = QueryOptionsUtils.getVectorExactRerank(queryOptions);
Integer maxCandidates = QueryOptionsUtils.getVectorMaxCandidates(queryOptions);
+ Float distanceThreshold = QueryOptionsUtils.getVectorDistanceThreshold(queryOptions);
- if (nprobe == null && exactRerank == null && maxCandidates == null) {
+ if (nprobe == null && exactRerank == null && maxCandidates == null && distanceThreshold == null) {
return DEFAULT;
}
- return new VectorSearchParams(nprobe, exactRerank, maxCandidates);
+ return new VectorSearchParams(nprobe, exactRerank, maxCandidates, distanceThreshold);
}
/**
@@ -131,10 +150,26 @@ public final class VectorSearchParams {
return _maxCandidatesExplicit;
}
+ /**
+ * Returns the distance threshold for radius/threshold search, or NaN if not set.
+ */
+ public float getDistanceThreshold() {
+ return _distanceThreshold;
+ }
+
+ /**
+ * Returns true if a distance threshold is set, indicating radius/threshold search mode.
+ */
+ public boolean hasDistanceThreshold() {
+ return _hasDistanceThreshold;
+ }
+
@Override
public String toString() {
return "VectorSearchParams{nprobe=" + _nprobe + ", exactRerank="
+ (_exactRerankOverride != null ? _exactRerankOverride : "backend_default")
- + ", maxCandidates=" + (_maxCandidatesExplicit ? _maxCandidates : "default(topK*10)") + '}';
+ + ", maxCandidates=" + (_maxCandidatesExplicit ? _maxCandidates : "default(topK*10)")
+ + (_hasDistanceThreshold ? ", distanceThreshold=" + _distanceThreshold : "")
+ + '}';
}
}
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperator.java b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperator.java
index a2b348102ef..747812cc4f7 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperator.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperator.java
@@ -31,6 +31,7 @@ import org.apache.pinot.core.common.Operator;
import org.apache.pinot.core.operator.ExplainAttributeBuilder;
import org.apache.pinot.core.operator.docidsets.BitmapDocIdSet;
import org.apache.pinot.segment.spi.index.creator.VectorBackendType;
+import org.apache.pinot.segment.spi.index.creator.VectorExecutionMode;
import org.apache.pinot.segment.spi.index.creator.VectorIndexConfig;
import org.apache.pinot.segment.spi.index.reader.ForwardIndexReader;
import org.apache.pinot.segment.spi.index.reader.ForwardIndexReaderContext;
@@ -78,6 +79,9 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
private final VectorIndexConfig.VectorDistanceFunction _distanceFunction;
private final boolean _requestedExactRerank;
private final boolean _effectiveExactRerank;
+ private final boolean _hasMetadataFilter;
+ private final boolean _hasThresholdPredicate;
+ private final float _distanceThreshold;
private final int _effectiveSearchCount;
private volatile VectorExplainContext _vectorExplainContext;
private volatile int _annCandidateCount;
@@ -90,7 +94,7 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
*/
public VectorSimilarityFilterOperator(VectorIndexReader vectorIndexReader, VectorSimilarityPredicate predicate,
int numDocs) {
- this(vectorIndexReader, predicate, numDocs, VectorSearchParams.DEFAULT, null, null);
+ this(vectorIndexReader, predicate, numDocs, VectorSearchParams.DEFAULT, null, null, false);
}
/**
@@ -104,12 +108,29 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
*/
public VectorSimilarityFilterOperator(VectorIndexReader vectorIndexReader, VectorSimilarityPredicate predicate,
int numDocs, VectorSearchParams searchParams, @Nullable ForwardIndexReader<?> forwardIndexReader) {
- this(vectorIndexReader, predicate, numDocs, searchParams, forwardIndexReader, null);
+ this(vectorIndexReader, predicate, numDocs, searchParams, forwardIndexReader, null, false);
}
public VectorSimilarityFilterOperator(VectorIndexReader vectorIndexReader, VectorSimilarityPredicate predicate,
int numDocs, VectorSearchParams searchParams, @Nullable ForwardIndexReader<?> forwardIndexReader,
@Nullable VectorIndexConfig vectorIndexConfig) {
+ this(vectorIndexReader, predicate, numDocs, searchParams, forwardIndexReader, vectorIndexConfig, false);
+ }
+
+ /**
+ * Full constructor with metadata filter awareness.
+ *
+ * @param vectorIndexReader the ANN index reader
+ * @param predicate the vector similarity predicate
+ * @param numDocs total docs in the segment
+ * @param searchParams vector search parameters from query options
+ * @param forwardIndexReader forward index reader for exact rerank (may be null if rerank is not needed)
+ * @param vectorIndexConfig vector index configuration (may be null)
+ * @param hasMetadataFilter true if this operator is combined with metadata filters in an AND
+ */
+ public VectorSimilarityFilterOperator(VectorIndexReader vectorIndexReader, VectorSimilarityPredicate predicate,
+ int numDocs, VectorSearchParams searchParams, @Nullable ForwardIndexReader<?> forwardIndexReader,
+ @Nullable VectorIndexConfig vectorIndexConfig, boolean hasMetadataFilter) {
super(numDocs, false);
_vectorIndexReader = vectorIndexReader;
_predicate = predicate;
@@ -120,9 +141,27 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
_distanceFunction = VectorDistanceUtils.resolveDistanceFunction(vectorIndexConfig);
_requestedExactRerank = searchParams.isExactRerank(_backendType);
_effectiveExactRerank = _requestedExactRerank && forwardIndexReader != null;
- _effectiveSearchCount = _effectiveExactRerank
- ? searchParams.getEffectiveMaxCandidates(predicate.getTopK(), numDocs)
- : predicate.getTopK();
+ _hasMetadataFilter = hasMetadataFilter;
+ _hasThresholdPredicate = searchParams.hasDistanceThreshold();
+ _distanceThreshold = searchParams.getDistanceThreshold();
+ // When metadata filter is present, over-fetch ANN candidates to compensate for filter loss.
+ // Default over-fetch factor is 2x topK for filtered queries without explicit maxCandidates.
+ // For threshold queries, use a larger candidate pool since we need distance refinement.
+ int baseSearchCount;
+ if (_hasThresholdPredicate) {
+ // Threshold queries need a larger candidate pool for exact distance refinement.
+ // Honor explicit vectorMaxCandidates; otherwise default to topK * 10.
+ baseSearchCount = searchParams.getEffectiveMaxCandidates(predicate.getTopK(), numDocs);
+ } else if (_effectiveExactRerank) {
+ baseSearchCount = searchParams.getEffectiveMaxCandidates(predicate.getTopK(), numDocs);
+ } else {
+ // For plain top-K and filtered queries (no rerank, no threshold), always ask
+ // the ANN index for exactly topK candidates. Over-fetching would change the
+ // predicate semantics: vectorSimilarity(col, q, 10) must return at most 10 docs.
+ // The metadata filter (bitmap AND) reduces this set further, which is correct.
+ baseSearchCount = predicate.getTopK();
+ }
+ _effectiveSearchCount = baseSearchCount;
refreshExplainContext(null);
_annCandidateCount = -1;
_rerankedCandidateCount = -1;
@@ -169,6 +208,8 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
VectorExplainContext explainContext = _vectorExplainContext;
return EXPLAIN_NAME + "(indexLookUp:vector_index"
+ ", operator:" + _predicate.getType()
+ + ", executionMode:" + (explainContext.getExecutionMode() != null
+ ? explainContext.getExecutionMode() : "UNKNOWN")
+ ", vector identifier:" + _predicate.getLhs().getIdentifier()
+ ", backend:" + explainContext.getBackendType()
+ ", distanceFunction:" + explainContext.getDistanceFunction()
@@ -191,6 +232,9 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
super.explainAttributes(attributeBuilder);
attributeBuilder.putString("indexLookUp", "vector_index");
attributeBuilder.putString("operator", _predicate.getType().name());
+ if (explainContext.getExecutionMode() != null) {
+ attributeBuilder.putString("executionMode", explainContext.getExecutionMode().name());
+ }
attributeBuilder.putString("vectorIdentifier", _predicate.getLhs().getIdentifier());
attributeBuilder.putString("backend", explainContext.getBackendType().name());
attributeBuilder.putString("distanceFunction", explainContext.getDistanceFunction().name());
@@ -239,7 +283,29 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
column);
}
- // 4. Apply exact rerank if requested
+ // 4. Apply threshold refinement if distance threshold is set.
+ // NOTE: This is approximate threshold search. The ANN index generates a candidate pool
+ // (controlled by vectorMaxCandidates, default topK*10), and only those candidates are
+ // checked against the threshold. Vectors within the threshold but outside the ANN candidate
+ // pool will be missed. For exact threshold search, use a table without a vector index
+ // (ExactVectorScanFilterOperator handles threshold correctly via brute-force scan).
+ // Increase vectorMaxCandidates to improve recall at the cost of latency.
+ if (_hasThresholdPredicate && _forwardIndexReader == null) {
+ throw new IllegalStateException(
+ "Vector distance threshold was requested on column: " + column
+ + " but no forward index reader is available to apply threshold refinement");
+ }
+ if (_hasThresholdPredicate && annCandidateCount > 0) {
+ ImmutableRoaringBitmap thresholded = applyThresholdRefinement(
+ annResults, queryVector, _distanceThreshold, column);
+ _rerankedCandidateCount = thresholded.getCardinality();
+ LOGGER.debug("Approximate threshold refinement on column: {}, threshold: {}, "
+ + "annCandidates: {} -> thresholded: {} (recall limited by candidate pool size)",
+ column, _distanceThreshold, annCandidateCount, thresholded.getCardinality());
+ return thresholded;
+ }
+
+ // 5. Apply exact rerank if requested
if (explainContext.isEffectiveExactRerank() && _forwardIndexReader != null && annCandidateCount > 0) {
ImmutableRoaringBitmap reranked = applyExactRerank(annResults, queryVector, _predicate.getTopK(), column);
_rerankedCandidateCount = reranked.getCardinality();
@@ -271,6 +337,36 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
}
}
+ /**
+ * Applies exact distance threshold refinement to ANN candidates.
+ * Returns only candidates whose exact distance is within the threshold.
+ */
+ @SuppressWarnings("unchecked")
+ private ImmutableRoaringBitmap applyThresholdRefinement(ImmutableRoaringBitmap annResults, float[] queryVector,
+ float threshold, String column) {
+ MutableRoaringBitmap result = new MutableRoaringBitmap();
+ VectorExplainContext explainContext = _vectorExplainContext;
+ ForwardIndexReader rawReader = _forwardIndexReader;
+ try (ForwardIndexReaderContext context = rawReader.createContext()) {
+ org.roaringbitmap.IntIterator it = annResults.getIntIterator();
+ while (it.hasNext()) {
+ int docId = it.next();
+ float[] docVector = rawReader.getFloatMV(docId, context);
+ if (docVector == null || docVector.length == 0) {
+ continue;
+ }
+ float distance = VectorDistanceUtils.computeDistance(queryVector, docVector,
+ explainContext.getDistanceFunction());
+ if (distance <= threshold) {
+ result.add(docId);
+ }
+ }
+ } catch (Exception e) {
+ throw new RuntimeException("Error during threshold refinement on column: " + column, e);
+ }
+ return result;
+ }
+
/**
* Re-scores ANN candidates using exact distance from the forward index and returns top-K.
*/
@@ -318,7 +414,9 @@ public class VectorSimilarityFilterOperator extends BaseFilterOperator {
}
private void refreshExplainContext(@Nullable String fallbackReason) {
- _vectorExplainContext = new VectorExplainContext(_backendType, _distanceFunction,
+ VectorExecutionMode executionMode = VectorQueryExecutionContext.selectExecutionMode(
+ true, _hasMetadataFilter, _hasThresholdPredicate, _effectiveExactRerank);
+ _vectorExplainContext = new VectorExplainContext(_backendType, _distanceFunction, executionMode,
resolveEffectiveNprobe(_backendType, _searchParams, _vectorIndexReader.getIndexDebugInfo()),
_effectiveExactRerank, _effectiveSearchCount, fallbackReason);
}
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/plan/FilterPlanNode.java b/pinot-core/src/main/java/org/apache/pinot/core/plan/FilterPlanNode.java
index 43e68791d34..97cbafa4f42 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/plan/FilterPlanNode.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/plan/FilterPlanNode.java
@@ -223,7 +223,13 @@ public class FilterPlanNode implements PlanNode {
childFilters = filter.getChildren();
childFilterOperators = new ArrayList<>(childFilters.size());
for (FilterContext childFilter : childFilters) {
- BaseFilterOperator childFilterOperator = constructPhysicalOperator(childFilter, numDocs);
+ BaseFilterOperator childFilterOperator;
+ if (isVectorSimilarityFilter(childFilter) && hasNonVectorSibling(childFilters)) {
+ // Pass filtered context so vector operator reports correct execution mode
+ childFilterOperator = constructFilteredVectorOperator(childFilter, numDocs);
+ } else {
+ childFilterOperator = constructPhysicalOperator(childFilter, numDocs);
+ }
if (childFilterOperator.isResultEmpty()) {
// Return empty filter operator if any of the child filter operator's result is empty
return EmptyFilterOperator.getInstance();
@@ -330,7 +336,7 @@ public class FilterPlanNode implements PlanNode {
return new JsonMatchFilterOperator(jsonIndex, (JsonMatchPredicate) predicate, numDocs);
case VECTOR_SIMILARITY:
return constructVectorSimilarityOperator(dataSource, (VectorSimilarityPredicate) predicate, column,
- numDocs);
+ numDocs, false);
case IS_NULL: {
NullValueVectorReader nullValueVector = dataSource.getNullValueVector();
if (nullValueVector != null) {
@@ -371,22 +377,27 @@ public class FilterPlanNode implements PlanNode {
* <li>If no vector index exists, fall back to {@link ExactVectorScanFilterOperator} which
* performs brute-force scan of the forward index.</li>
* </ol>
+ *
+ * @param hasMetadataFilter true if this vector predicate is combined with metadata filters (AND)
*/
private BaseFilterOperator constructVectorSimilarityOperator(DataSource dataSource,
- VectorSimilarityPredicate predicate, String column, int numDocs) {
+ VectorSimilarityPredicate predicate, String column, int numDocs, boolean hasMetadataFilter) {
VectorIndexReader vectorIndex = dataSource.getVectorIndex();
VectorIndexConfig vectorIndexConfig = dataSource.getVectorIndexConfig();
VectorSearchParams searchParams = VectorSearchParams.fromQueryOptions(_queryContext.getQueryOptions());
if (vectorIndex != null) {
- // ANN index path: pass forward index reader only if rerank is enabled
+ // ANN index path: pass forward index reader if rerank or threshold search requires exact distances
ForwardIndexReader<?> forwardIndexReader = null;
VectorBackendType backendType = VectorDistanceUtils.resolveBackendType(vectorIndexConfig);
- if (searchParams.isExactRerank(backendType)) {
+ if (searchParams.isExactRerank(backendType) || searchParams.hasDistanceThreshold()) {
forwardIndexReader = dataSource.getForwardIndex();
+ Preconditions.checkState(!searchParams.hasDistanceThreshold() || forwardIndexReader != null,
+ "Cannot apply vectorDistanceThreshold on column: %s -- forward index required for threshold refinement",
+ column);
}
return new VectorSimilarityFilterOperator(vectorIndex, predicate, numDocs, searchParams, forwardIndexReader,
- vectorIndexConfig);
+ vectorIndexConfig, hasMetadataFilter);
}
// Exact scan fallback: no vector index on this segment
@@ -394,7 +405,41 @@ public class FilterPlanNode implements PlanNode {
Preconditions.checkState(forwardIndexReader != null,
"Cannot apply VECTOR_SIMILARITY on column: %s -- no vector index and no forward index available", column);
return new ExactVectorScanFilterOperator(forwardIndexReader, predicate, column, numDocs, vectorIndexConfig,
- getVectorFallbackReason(vectorIndexConfig));
+ getVectorFallbackReason(vectorIndexConfig), searchParams);
+ }
+
+ /**
+ * Constructs a vector operator for a VECTOR_SIMILARITY predicate that is part of an AND
+ * with metadata filters. This sets the hasMetadataFilter flag so the operator reports
+ * the correct filtered ANN execution mode.
+ */
+ private BaseFilterOperator constructFilteredVectorOperator(FilterContext filter, int numDocs) {
+ Predicate predicate = filter.getPredicate();
+ String column = predicate.getLhs().getIdentifier();
+ DataSource dataSource = _indexSegment.getDataSource(column, _queryContext.getSchema());
+ return constructVectorSimilarityOperator(dataSource, (VectorSimilarityPredicate) predicate, column,
+ numDocs, true);
+ }
+
+ /**
+ * Returns true if the child list contains at least one non-VECTOR_SIMILARITY predicate
+ * (i.e., a real metadata filter sibling).
+ */
+ private static boolean hasNonVectorSibling(List<FilterContext> childFilters) {
+ for (FilterContext child : childFilters) {
+ if (!isVectorSimilarityFilter(child)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Returns true if the filter is a VECTOR_SIMILARITY predicate.
+ */
+ private static boolean isVectorSimilarityFilter(FilterContext filter) {
+ return filter.getType() == FilterContext.Type.PREDICATE
+ && filter.getPredicate().getType() == Predicate.Type.VECTOR_SIMILARITY;
}
private static String getVectorFallbackReason(@Nullable VectorIndexConfig vectorIndexConfig) {
diff --git a/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorCompoundQueryTest.java b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorCompoundQueryTest.java
new file mode 100644
index 00000000000..a05aa072e7c
--- /dev/null
+++ b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorCompoundQueryTest.java
@@ -0,0 +1,232 @@
+/**
+ * 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.pinot.core.operator.filter;
+
+import java.util.Map;
+import org.apache.pinot.common.request.context.ExpressionContext;
+import org.apache.pinot.common.request.context.predicate.VectorSimilarityPredicate;
+import org.apache.pinot.segment.spi.index.creator.VectorBackendType;
+import org.apache.pinot.segment.spi.index.creator.VectorExecutionMode;
+import org.apache.pinot.segment.spi.index.creator.VectorIndexConfig;
+import org.apache.pinot.segment.spi.index.reader.ForwardIndexReader;
+import org.apache.pinot.segment.spi.index.reader.ForwardIndexReaderContext;
+import org.apache.pinot.segment.spi.index.reader.VectorIndexReader;
+import org.apache.pinot.spi.data.FieldSpec.DataType;
+import org.mockito.Mockito;
+import org.roaringbitmap.buffer.ImmutableRoaringBitmap;
+import org.roaringbitmap.buffer.MutableRoaringBitmap;
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+
+/**
+ * Tests for compound vector retrieval patterns:
+ * <ul>
+ * <li>metadata filter + top-K ANN</li>
+ * <li>metadata filter + threshold/radius</li>
+ * <li>top-K + threshold combination</li>
+ * </ul>
+ */
+public class VectorCompoundQueryTest {
+
+ // --- Execution mode selection for compound patterns ---
+
+ @Test
+ public void testFilterPlusTopKSelectsAnnThenFilter() {
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ true, true, false, false);
+ Assert.assertEquals(mode, VectorExecutionMode.ANN_THEN_FILTER);
+ }
+
+ @Test
+ public void testFilterPlusTopKWithRerankSelectsAnnThenFilterThenRerank() {
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ true, true, false, true);
+ Assert.assertEquals(mode, VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK);
+ }
+
+ @Test
+ public void testFilterPlusThresholdSelectsAnnThresholdThenFilter() {
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ true, true, true, false);
+ Assert.assertEquals(mode, VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER);
+ }
+
+ @Test
+ public void testThresholdAloneSelectsAnnThresholdScan() {
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ true, false, true, false);
+ Assert.assertEquals(mode, VectorExecutionMode.ANN_THRESHOLD_SCAN);
+ }
+
+ @Test
+ public void testFilterPlusThresholdPlusRerankPrioritizesThreshold() {
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ true, true, true, true);
+ Assert.assertEquals(mode, VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER);
+ }
+
+ // --- Compound operator behavior tests ---
+
+ @Test
+ public void testFilterPlusTopKOperator() {
+ // Simulates: WHERE VECTOR_SIMILARITY(col, vec, 2) AND metadata_col = 'x'
+ // The vector operator returns exactly topK docs; bitmap AND with metadata filter
+ // reduces further. No over-fetch: vectorSimilarity(col, q, 2) returns at most 2.
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+ annResult.add(1);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(queryVector, 2)).thenReturn(annResult);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 2);
+
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(
+ mockReader, predicate, 100, VectorSearchParams.DEFAULT, null, null, true);
+
+ ImmutableRoaringBitmap result = operator.getBitmaps().reduce();
+ Assert.assertEquals(result.getCardinality(), 2);
+
+ String explain = operator.toExplainString();
+ Assert.assertTrue(explain.contains("executionMode:ANN_THEN_FILTER"));
+ }
+
+ @Test
+ public void testFilterPlusThresholdOperator() {
+ // Simulates: WHERE VECTOR_SIMILARITY(col, vec, 10) AND metadata_col = 'x'
+ // with vectorDistanceThreshold=0.5
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+ annResult.add(1);
+ annResult.add(2);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(Mockito.eq(queryVector), Mockito.anyInt())).thenReturn(annResult);
+
+ float[][] vectors = {
+ {1.0f, 0.0f}, // distance 0.0 -> within
+ {0.0f, 1.0f}, // distance 2.0 -> outside
+ {0.95f, 0.05f}, // distance ~0.005 -> within
+ };
+ ForwardIndexReader<?> mockForward = createMockForwardIndexReader(vectors);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 10);
+
+ VectorSearchParams params = new VectorSearchParams(null, null, null, 0.5f);
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(
+ mockReader, predicate, 100, params, mockForward,
+ createVectorIndexConfig("HNSW", VectorIndexConfig.VectorDistanceFunction.EUCLIDEAN), true);
+
+ ImmutableRoaringBitmap result = operator.getBitmaps().reduce();
+ // After threshold refinement: docs 0 and 2 survive (distance <= 0.5)
+ Assert.assertTrue(result.contains(0));
+ Assert.assertFalse(result.contains(1));
+ Assert.assertTrue(result.contains(2));
+
+ String explain = operator.toExplainString();
+ Assert.assertTrue(explain.contains("executionMode:ANN_THRESHOLD_THEN_FILTER"),
+ "Expected ANN_THRESHOLD_THEN_FILTER but got: " + explain);
+ }
+
+ @Test
+ public void testCompoundContextBuilder() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder()
+ .executionMode(VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER)
+ .backendType(VectorBackendType.HNSW)
+ .hasMetadataFilter(true)
+ .hasThresholdPredicate(true)
+ .distanceThreshold(0.5f)
+ .topK(10)
+ .candidateBudget(100)
+ .build();
+
+ Assert.assertEquals(ctx.getExecutionMode(), VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER);
+ Assert.assertTrue(ctx.hasMetadataFilter());
+ Assert.assertTrue(ctx.hasThresholdPredicate());
+ Assert.assertEquals(ctx.getDistanceThreshold(), 0.5f);
+ Assert.assertEquals(ctx.getTopK(), 10);
+ Assert.assertEquals(ctx.getCandidateBudget(), 100);
+
+ String str = ctx.toString();
+ Assert.assertTrue(str.contains("ANN_THRESHOLD_THEN_FILTER"));
+ Assert.assertTrue(str.contains("hasFilter=true"));
+ Assert.assertTrue(str.contains("threshold=0.5"));
+ }
+
+ // --- Backward compatibility: ensure non-compound queries still work ---
+
+ @Test
+ public void testPlainTopKBackwardCompatible() {
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(5);
+ annResult.add(10);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(queryVector, 2)).thenReturn(annResult);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 2);
+
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(
+ mockReader, predicate, 100);
+
+ ImmutableRoaringBitmap result = operator.getBitmaps().reduce();
+ Assert.assertEquals(result.getCardinality(), 2);
+ Assert.assertTrue(result.contains(5));
+ Assert.assertTrue(result.contains(10));
+
+ String explain = operator.toExplainString();
+ Assert.assertTrue(explain.contains("executionMode:ANN_TOP_K"));
+ }
+
+ // --- Helper methods ---
+
+ @SuppressWarnings({"unchecked", "rawtypes"})
+ private ForwardIndexReader<?> createMockForwardIndexReader(float[][] vectors) {
+ ForwardIndexReader mockReader = mock(ForwardIndexReader.class);
+ ForwardIndexReaderContext mockContext = mock(ForwardIndexReaderContext.class);
+ try {
+ when(mockReader.createContext()).thenReturn(mockContext);
+ } catch (Exception e) {
+ throw new RuntimeException(e);
+ }
+ when(mockReader.isSingleValue()).thenReturn(false);
+ when(mockReader.isDictionaryEncoded()).thenReturn(false);
+ when(mockReader.getStoredType()).thenReturn(DataType.FLOAT);
+
+ for (int i = 0; i < vectors.length; i++) {
+ when(mockReader.getFloatMV(Mockito.eq(i), Mockito.any())).thenReturn(vectors[i]);
+ }
+ return mockReader;
+ }
+
+ private VectorIndexConfig createVectorIndexConfig(String backendType,
+ VectorIndexConfig.VectorDistanceFunction distanceFunction) {
+ return new VectorIndexConfig(false, backendType, 2, 1, distanceFunction, Map.of());
+ }
+}
diff --git a/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorQueryExecutionContextTest.java b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorQueryExecutionContextTest.java
new file mode 100644
index 00000000000..de213258f87
--- /dev/null
+++ b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorQueryExecutionContextTest.java
@@ -0,0 +1,203 @@
+/**
+ * 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.pinot.core.operator.filter;
+
+import org.apache.pinot.segment.spi.index.creator.VectorBackendType;
+import org.apache.pinot.segment.spi.index.creator.VectorExecutionMode;
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertFalse;
+import static org.testng.Assert.assertNotNull;
+import static org.testng.Assert.assertNull;
+import static org.testng.Assert.assertTrue;
+
+
+/**
+ * Tests for {@link VectorQueryExecutionContext} and its execution mode selection logic.
+ */
+public class VectorQueryExecutionContextTest {
+
+ // --- Execution mode selection tests ---
+
+ @Test
+ public void testSelectModeNoVectorIndex() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(false, false, false, false),
+ VectorExecutionMode.EXACT_SCAN);
+ }
+
+ @Test
+ public void testSelectModeNoVectorIndexWithFilter() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(false, true, false, false),
+ VectorExecutionMode.EXACT_SCAN);
+ }
+
+ @Test
+ public void testSelectModePlainTopK() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(true, false, false, false),
+ VectorExecutionMode.ANN_TOP_K);
+ }
+
+ @Test
+ public void testSelectModeTopKWithRerank() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(true, false, false, true),
+ VectorExecutionMode.ANN_TOP_K_WITH_RERANK);
+ }
+
+ @Test
+ public void testSelectModeAnnThenFilter() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(true, true, false, false),
+ VectorExecutionMode.ANN_THEN_FILTER);
+ }
+
+ @Test
+ public void testSelectModeAnnThenFilterThenRerank() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(true, true, false, true),
+ VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK);
+ }
+
+ @Test
+ public void testSelectModeThresholdScan() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(true, false, true, false),
+ VectorExecutionMode.ANN_THRESHOLD_SCAN);
+ }
+
+ @Test
+ public void testSelectModeThresholdThenFilter() {
+ assertEquals(
+ VectorQueryExecutionContext.selectExecutionMode(true, true, true, false),
+ VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER);
+ }
+
+ // --- Builder and context tests ---
+
+ @Test
+ public void testBuilderDefaults() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder().build();
+ assertEquals(ctx.getExecutionMode(), VectorExecutionMode.ANN_TOP_K);
+ assertEquals(ctx.getBackendType(), VectorBackendType.HNSW);
+ assertFalse(ctx.isExactRerank());
+ assertFalse(ctx.hasMetadataFilter());
+ assertFalse(ctx.hasThresholdPredicate());
+ assertEquals(ctx.getTopK(), 0);
+ assertNull(ctx.getFallbackReason());
+ }
+
+ @Test
+ public void testBuilderFull() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder()
+ .executionMode(VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK)
+ .backendType(VectorBackendType.IVF_PQ)
+ .exactRerank(true)
+ .hasMetadataFilter(true)
+ .hasThresholdPredicate(false)
+ .topK(10)
+ .candidateBudget(100)
+ .fallbackReason(null)
+ .build();
+
+ assertEquals(ctx.getExecutionMode(), VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK);
+ assertEquals(ctx.getBackendType(), VectorBackendType.IVF_PQ);
+ assertNotNull(ctx.getCapabilities());
+ assertTrue(ctx.isExactRerank());
+ assertTrue(ctx.hasMetadataFilter());
+ assertFalse(ctx.hasThresholdPredicate());
+ assertEquals(ctx.getTopK(), 10);
+ assertEquals(ctx.getCandidateBudget(), 100);
+ assertNull(ctx.getFallbackReason());
+ }
+
+ @Test
+ public void testBuilderWithFallback() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder()
+ .executionMode(VectorExecutionMode.EXACT_SCAN)
+ .fallbackReason("vector_index_missing")
+ .build();
+
+ assertEquals(ctx.getExecutionMode(), VectorExecutionMode.EXACT_SCAN);
+ assertEquals(ctx.getFallbackReason(), "vector_index_missing");
+ }
+
+ @Test
+ public void testBuilderWithThreshold() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder()
+ .executionMode(VectorExecutionMode.ANN_THRESHOLD_SCAN)
+ .hasThresholdPredicate(true)
+ .distanceThreshold(0.5f)
+ .topK(100)
+ .candidateBudget(1000)
+ .build();
+
+ assertTrue(ctx.hasThresholdPredicate());
+ assertEquals(ctx.getDistanceThreshold(), 0.5f);
+ assertEquals(ctx.getTopK(), 100);
+ assertEquals(ctx.getCandidateBudget(), 1000);
+ }
+
+ @Test
+ public void testToString() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder()
+ .executionMode(VectorExecutionMode.ANN_THEN_FILTER)
+ .backendType(VectorBackendType.HNSW)
+ .hasMetadataFilter(true)
+ .topK(10)
+ .build();
+
+ String str = ctx.toString();
+ assertTrue(str.contains("ANN_THEN_FILTER"));
+ assertTrue(str.contains("HNSW"));
+ assertTrue(str.contains("hasFilter=true"));
+ assertTrue(str.contains("topK=10"));
+ }
+
+ @Test
+ public void testCapabilitiesAutoPopulated() {
+ VectorQueryExecutionContext ctx = new VectorQueryExecutionContext.Builder()
+ .backendType(VectorBackendType.IVF_FLAT)
+ .build();
+
+ assertNotNull(ctx.getCapabilities());
+ assertTrue(ctx.getCapabilities().supportsRuntimeSearchParams());
+ }
+
+ // --- Mode selection priority tests ---
+
+ @Test
+ public void testThresholdTakesPriorityOverFilter() {
+ // When both threshold and filter are present, threshold mode wins
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ true, true, true, true);
+ assertEquals(mode, VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER);
+ }
+
+ @Test
+ public void testNoIndexAlwaysFallsBackToExactScan() {
+ // Even with threshold, filter, and rerank, no index means exact scan
+ VectorExecutionMode mode = VectorQueryExecutionContext.selectExecutionMode(
+ false, true, true, true);
+ assertEquals(mode, VectorExecutionMode.EXACT_SCAN);
+ }
+}
diff --git a/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSearchParamsTest.java b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSearchParamsTest.java
index fad78a08a82..a823aea2ce1 100644
--- a/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSearchParamsTest.java
+++ b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSearchParamsTest.java
@@ -155,4 +155,45 @@ public class VectorSearchParamsTest {
VectorSearchParams params = new VectorSearchParams(null, false, null);
Assert.assertFalse(params.isExactRerank(VectorBackendType.IVF_PQ));
}
+
+ @Test
+ public void testDistanceThresholdFromQueryOptions() {
+ Map<String, String> opts = new HashMap<>();
+ opts.put(QueryOptionKey.VECTOR_DISTANCE_THRESHOLD, "0.5");
+ VectorSearchParams params = VectorSearchParams.fromQueryOptions(opts);
+ Assert.assertTrue(params.hasDistanceThreshold());
+ Assert.assertEquals(params.getDistanceThreshold(), 0.5f);
+ }
+
+ @Test
+ public void testNoDistanceThresholdByDefault() {
+ VectorSearchParams params = VectorSearchParams.DEFAULT;
+ Assert.assertFalse(params.hasDistanceThreshold());
+ Assert.assertTrue(Float.isNaN(params.getDistanceThreshold()));
+ }
+
+ @Test
+ public void testDistanceThresholdToString() {
+ VectorSearchParams params = new VectorSearchParams(null, null, null, 0.3f);
+ String s = params.toString();
+ Assert.assertTrue(s.contains("distanceThreshold=0.3"));
+ }
+
+ @Test
+ public void testDistanceThresholdDirectConstructor() {
+ VectorSearchParams params = new VectorSearchParams(4, null, null, 1.5f);
+ Assert.assertTrue(params.hasDistanceThreshold());
+ Assert.assertEquals(params.getDistanceThreshold(), 1.5f);
+ Assert.assertEquals(params.getNprobe(), 4);
+ }
+
+ @Test
+ public void testNegativeDistanceThresholdForDotProduct() {
+ // Negative thresholds are valid for dot-product distance (negated dot product)
+ Map<String, String> opts = new HashMap<>();
+ opts.put(QueryOptionKey.VECTOR_DISTANCE_THRESHOLD, "-0.8");
+ VectorSearchParams params = VectorSearchParams.fromQueryOptions(opts);
+ Assert.assertTrue(params.hasDistanceThreshold());
+ Assert.assertEquals(params.getDistanceThreshold(), -0.8f);
+ }
}
diff --git a/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperatorTest.java b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperatorTest.java
index 16048efe068..49ce8c2100e 100644
--- a/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperatorTest.java
+++ b/pinot-core/src/test/java/org/apache/pinot/core/operator/filter/VectorSimilarityFilterOperatorTest.java
@@ -392,6 +392,153 @@ public class VectorSimilarityFilterOperatorTest {
Assert.assertTrue(result.contains(0), "Configured cosine rerank should keep the cosine-identical vector");
}
+ @Test
+ public void testFilteredAnnReportsCorrectExecutionMode() {
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+ annResult.add(1);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(Mockito.eq(queryVector), Mockito.anyInt())).thenReturn(annResult);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 2);
+
+ // Without metadata filter: ANN_TOP_K
+ VectorSimilarityFilterOperator noFilter = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, VectorSearchParams.DEFAULT, null, null, false);
+ String explainNoFilter = noFilter.toExplainString();
+ Assert.assertTrue(explainNoFilter.contains("executionMode:ANN_TOP_K"),
+ "Expected ANN_TOP_K but got: " + explainNoFilter);
+
+ // With metadata filter: ANN_THEN_FILTER
+ VectorSimilarityFilterOperator withFilter = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, VectorSearchParams.DEFAULT, null, null, true);
+ String explainWithFilter = withFilter.toExplainString();
+ Assert.assertTrue(explainWithFilter.contains("executionMode:ANN_THEN_FILTER"),
+ "Expected ANN_THEN_FILTER but got: " + explainWithFilter);
+ }
+
+ @Test
+ public void testFilteredAnnWithRerankReportsCorrectMode() {
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(Mockito.eq(queryVector), Mockito.anyInt())).thenReturn(annResult);
+
+ ForwardIndexReader<?> mockForward = createMockForwardIndexReader(new float[][]{{1.0f, 0.0f}});
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 1);
+
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, new VectorSearchParams(null, true, null), mockForward, null, true);
+ String explain = operator.toExplainString();
+ Assert.assertTrue(explain.contains("executionMode:ANN_THEN_FILTER_THEN_RERANK"),
+ "Expected ANN_THEN_FILTER_THEN_RERANK but got: " + explain);
+ }
+
+ @Test
+ public void testThresholdSearchReturnsOnlyWithinDistance() {
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+ annResult.add(1);
+ annResult.add(2);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(Mockito.eq(queryVector), Mockito.anyInt())).thenReturn(annResult);
+
+ // Doc 0: exact distance 0.0 (same vector) -> within threshold 0.5
+ // Doc 1: exact distance 2.0 (L2 squared to [0,1]) -> outside threshold 0.5
+ // Doc 2: exact distance 0.01 (L2 squared to [0.9,0.1]) -> within threshold 0.5
+ float[][] vectors = {
+ {1.0f, 0.0f},
+ {0.0f, 1.0f},
+ {0.9f, 0.1f},
+ };
+ ForwardIndexReader<?> mockForward = createMockForwardIndexReader(vectors);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 10);
+
+ VectorSearchParams params = new VectorSearchParams(null, null, null, 0.5f);
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, params, mockForward,
+ createVectorIndexConfig("HNSW", VectorIndexConfig.VectorDistanceFunction.EUCLIDEAN), false);
+
+ ImmutableRoaringBitmap result = operator.getBitmaps().reduce();
+ Assert.assertTrue(result.contains(0), "Doc 0 should be within threshold");
+ Assert.assertFalse(result.contains(1), "Doc 1 should be outside threshold");
+ Assert.assertTrue(result.contains(2), "Doc 2 should be within threshold");
+ }
+
+ @Test
+ public void testThresholdSearchReportsCorrectExecutionMode() {
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(Mockito.eq(queryVector), Mockito.anyInt())).thenReturn(annResult);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 10);
+
+ VectorSearchParams params = new VectorSearchParams(null, null, null, 0.5f);
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, params, null, null, false);
+
+ String explain = operator.toExplainString();
+ Assert.assertTrue(explain.contains("executionMode:ANN_THRESHOLD_SCAN"),
+ "Expected ANN_THRESHOLD_SCAN but got: " + explain);
+ }
+
+ @Test
+ public void testThresholdWithFilterReportsCorrectMode() {
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(Mockito.eq(queryVector), Mockito.anyInt())).thenReturn(annResult);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 10);
+
+ VectorSearchParams params = new VectorSearchParams(null, null, null, 0.5f);
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, params, null, null, true);
+
+ String explain = operator.toExplainString();
+ Assert.assertTrue(explain.contains("executionMode:ANN_THRESHOLD_THEN_FILTER"),
+ "Expected ANN_THRESHOLD_THEN_FILTER but got: " + explain);
+ }
+
+ @Test
+ public void testFilteredAnnDoesNotOverfetch() {
+ // Filtered ANN should NOT over-fetch: vectorSimilarity(col, q, 5) must return at most 5 docs.
+ // The metadata filter (bitmap AND) reduces this set further.
+ MutableRoaringBitmap annResult = new MutableRoaringBitmap();
+ annResult.add(0);
+
+ VectorIndexReader mockReader = mock(VectorIndexReader.class);
+ float[] queryVector = {1.0f, 0.0f};
+ when(mockReader.getDocIds(queryVector, 5)).thenReturn(annResult);
+
+ ExpressionContext lhs = ExpressionContext.forIdentifier("embedding");
+ VectorSimilarityPredicate predicate = new VectorSimilarityPredicate(lhs, queryVector, 5);
+
+ VectorSimilarityFilterOperator operator = new VectorSimilarityFilterOperator(mockReader, predicate,
+ 100, VectorSearchParams.DEFAULT, null, null, true);
+ operator.getBitmaps();
+ // Verify topK is used as-is (no over-fetch)
+ verify(mockReader).getDocIds(queryVector, 5);
+ }
+
/**
* Interface combining VectorIndexReader and NprobeAware for mocking IVF_FLAT readers.
*/
diff --git a/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/IvfFlatVectorTest.java b/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/IvfFlatVectorTest.java
index 28de2e7cf6e..3f0598b718a 100644
--- a/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/IvfFlatVectorTest.java
+++ b/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/IvfFlatVectorTest.java
@@ -53,8 +53,10 @@ public class IvfFlatVectorTest extends CustomDataQueryClusterIntegrationTest {
private static final String DEFAULT_TABLE_NAME = "IvfFlatVectorTest";
private static final String VECTOR_COL = "embedding";
private static final String VECTORS_L2_DIST = "embeddingL2Dist";
+ private static final String CATEGORY = "category";
private static final int VECTOR_DIM_SIZE = 128;
private static final int NLIST = 8;
+ private static final int NUM_CATEGORIES = 5;
@Override
protected long getCountStarResult() {
@@ -90,6 +92,7 @@ public class IvfFlatVectorTest extends CustomDataQueryClusterIntegrationTest {
return new Schema.SchemaBuilder().setSchemaName(getTableName())
.addMultiValueDimension(VECTOR_COL, FieldSpec.DataType.FLOAT)
.addSingleValueDimension(VECTORS_L2_DIST, FieldSpec.DataType.DOUBLE)
+ .addSingleValueDimension(CATEGORY, FieldSpec.DataType.STRING)
.build();
}
@@ -102,7 +105,9 @@ public class IvfFlatVectorTest extends CustomDataQueryClusterIntegrationTest {
avroSchema.setFields(List.of(
new org.apache.avro.Schema.Field(VECTOR_COL, floatArraySchema, null, null),
new org.apache.avro.Schema.Field(VECTORS_L2_DIST,
- org.apache.avro.Schema.create(org.apache.avro.Schema.Type.DOUBLE), null, null)
+ org.apache.avro.Schema.create(org.apache.avro.Schema.Type.DOUBLE), null, null),
+ new org.apache.avro.Schema.Field(CATEGORY,
+ org.apache.avro.Schema.create(org.apache.avro.Schema.Type.STRING), null, null)
));
float[] queryVector = new float[VECTOR_DIM_SIZE];
@@ -117,6 +122,7 @@ public class IvfFlatVectorTest extends CustomDataQueryClusterIntegrationTest {
float[] vector = createRandomVector(VECTOR_DIM_SIZE);
record.put(VECTOR_COL, convertToFloatCollection(vector));
record.put(VECTORS_L2_DIST, l2Distance(vector, queryVector));
+ record.put(CATEGORY, "cat_" + (i % NUM_CATEGORIES));
writers.get(i % getNumAvroFiles()).append(record);
}
return avroFilesAndWriters.getAvroFiles();
@@ -204,6 +210,82 @@ public class IvfFlatVectorTest extends CustomDataQueryClusterIntegrationTest {
}
}
+ /**
+ * Tests threshold search with vectorDistanceThreshold query option.
+ * The threshold is in euclideanDistance space (squared L2, no sqrt).
+ */
+ @Test(dataProvider = "useBothQueryEngines")
+ public void testThresholdSearch(boolean useMultiStageQueryEngine)
+ throws Exception {
+ setUseMultiStageQueryEngine(useMultiStageQueryEngine);
+ String queryVector = "ARRAY[1.1" + StringUtils.repeat(", 1.1", VECTOR_DIM_SIZE - 1) + "]";
+
+ // Get p25 of L2 distances (sqrt), then square it for the internal threshold
+ String percentileQuery = String.format(
+ "SELECT PERCENTILE(%s, 25) FROM %s", VECTORS_L2_DIST, getTableName());
+ JsonNode percentileResult = postQuery(percentileQuery);
+ double l2Dist = percentileResult.get("resultTable").get("rows").get(0).get(0).asDouble();
+ double threshold = l2Dist * l2Dist;
+
+ String thresholdQuery = String.format(
+ "SET vectorDistanceThreshold = %f; "
+ + "SELECT l2Distance(%s, %s) AS dist FROM %s "
+ + "WHERE vectorSimilarity(%s, %s, %d) "
+ + "ORDER BY dist ASC LIMIT 100",
+ threshold, VECTOR_COL, queryVector, getTableName(),
+ VECTOR_COL, queryVector, 200);
+
+ JsonNode result = postQuery(thresholdQuery);
+ assertNotNull(result.get("resultTable"), "Threshold query should return a resultTable");
+ JsonNode rows = result.get("resultTable").get("rows");
+ assertTrue(rows.size() > 0, "Threshold search should return results");
+
+ for (int i = 0; i < rows.size(); i++) {
+ double dist = rows.get(i).get(0).asDouble();
+ assertTrue(dist <= l2Dist + 1e-3,
+ "Row " + i + " l2Distance (" + dist + ") should be within sqrt(threshold) (" + l2Dist + ")");
+ }
+ }
+
+ /**
+ * Tests compound pattern: metadata filter + threshold search.
+ */
+ @Test(dataProvider = "useBothQueryEngines")
+ public void testCompoundFilterAndThreshold(boolean useMultiStageQueryEngine)
+ throws Exception {
+ setUseMultiStageQueryEngine(useMultiStageQueryEngine);
+ String queryVector = "ARRAY[1.1" + StringUtils.repeat(", 1.1", VECTOR_DIM_SIZE - 1) + "]";
+ String targetCategory = "cat_1";
+
+ String percentileQuery = String.format(
+ "SELECT PERCENTILE(%s, 50) FROM %s", VECTORS_L2_DIST, getTableName());
+ JsonNode percentileResult = postQuery(percentileQuery);
+ double l2Dist = percentileResult.get("resultTable").get("rows").get(0).get(0).asDouble();
+ double threshold = l2Dist * l2Dist;
+
+ String compoundQuery = String.format(
+ "SET vectorDistanceThreshold = %f; "
+ + "SELECT l2Distance(%s, %s) AS dist, %s FROM %s "
+ + "WHERE vectorSimilarity(%s, %s, %d) AND %s = '%s' "
+ + "ORDER BY dist ASC LIMIT 100",
+ threshold, VECTOR_COL, queryVector, CATEGORY, getTableName(),
+ VECTOR_COL, queryVector, 200, CATEGORY, targetCategory);
+
+ JsonNode result = postQuery(compoundQuery);
+ assertNotNull(result.get("resultTable"), "Compound query should return a resultTable");
+ JsonNode rows = result.get("resultTable").get("rows");
+ assertTrue(rows.size() > 0, "Compound query should return results");
+
+ for (int i = 0; i < rows.size(); i++) {
+ double dist = rows.get(i).get(0).asDouble();
+ String cat = rows.get(i).get(1).asText();
+ assertTrue(dist <= l2Dist + 1e-3,
+ "Row " + i + " l2Distance (" + dist + ") exceeds threshold");
+ assertEquals(cat, targetCategory,
+ "Row " + i + " category mismatch");
+ }
+ }
+
private static double l2Distance(float[] a, float[] b) {
double sum = 0;
for (int i = 0; i < a.length; i++) {
diff --git a/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/VectorTest.java b/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/VectorTest.java
index 5f9b0a25d02..4971c23b605 100644
--- a/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/VectorTest.java
+++ b/pinot-integration-tests/src/test/java/org/apache/pinot/integration/tests/custom/VectorTest.java
@@ -38,6 +38,7 @@ import org.apache.pinot.spi.utils.builder.TableConfigBuilder;
import org.testng.annotations.Test;
import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertTrue;
@Test(suiteName = "CustomClusterIntegrationTest")
@@ -55,7 +56,9 @@ public class VectorTest extends CustomDataQueryClusterIntegrationTest {
private static final String VECTORS_L2_DIST = "vectorsL2Dist";
private static final String VECTOR_ZERO_L1_DIST = "vectorZeroL1Dist";
private static final String VECTOR_ZERO_L2_DIST = "vectorZeroL2Dist";
+ private static final String CATEGORY = "category";
private static final int VECTOR_DIM_SIZE = 512;
+ private static final int NUM_CATEGORIES = 5;
@Override
protected long getCountStarResult() {
@@ -208,6 +211,85 @@ public class VectorTest extends CustomDataQueryClusterIntegrationTest {
}
}
+ /**
+ * Tests filtered ANN: VECTOR_SIMILARITY combined with a metadata filter.
+ * All returned rows must match the filter predicate and be ordered by distance.
+ */
+ @Test(dataProvider = "useBothQueryEngines")
+ public void testFilteredAnn(boolean useMultiStageQueryEngine)
+ throws Exception {
+ setUseMultiStageQueryEngine(useMultiStageQueryEngine);
+ int topK = 5;
+ String queryVector = "ARRAY[1.1" + StringUtils.repeat(", 1.1", VECTOR_DIM_SIZE - 1) + "]";
+ String targetCategory = "cat_0";
+
+ String filteredQuery = String.format(
+ "SELECT cosineDistance(%s, %s) AS dist, %s FROM %s "
+ + "WHERE vectorSimilarity(%s, %s, %d) AND %s = '%s' "
+ + "ORDER BY dist ASC LIMIT %d",
+ VECTOR_1, queryVector, CATEGORY, getTableName(),
+ VECTOR_1, queryVector, topK * 10, CATEGORY, targetCategory, topK);
+
+ JsonNode result = postQuery(filteredQuery);
+ JsonNode rows = result.get("resultTable").get("rows");
+ assertTrue(rows.size() > 0, "Filtered ANN should return results");
+
+ double prevDist = -1;
+ for (int i = 0; i < rows.size(); i++) {
+ double dist = rows.get(i).get(0).asDouble();
+ String cat = rows.get(i).get(1).asText();
+ assertEquals(cat, targetCategory, "All results must match the filter");
+ assertTrue(dist >= prevDist, "Results must be ordered by distance");
+ prevDist = dist;
+ }
+ }
+
+ /**
+ * Tests that filtered ANN returns fewer or equal results compared to unfiltered ANN.
+ */
+ @Test(dataProvider = "useBothQueryEngines")
+ public void testFilteredAnnReducesResults(boolean useMultiStageQueryEngine)
+ throws Exception {
+ setUseMultiStageQueryEngine(useMultiStageQueryEngine);
+ int topK = 20;
+ String queryVector = "ARRAY[1.1" + StringUtils.repeat(", 1.1", VECTOR_DIM_SIZE - 1) + "]";
+
+ String unfilteredQuery = String.format(
+ "SELECT count(*) FROM %s WHERE vectorSimilarity(%s, %s, %d)",
+ getTableName(), VECTOR_1, queryVector, topK);
+ String filteredQuery = String.format(
+ "SELECT count(*) FROM %s WHERE vectorSimilarity(%s, %s, %d) AND %s = 'cat_0'",
+ getTableName(), VECTOR_1, queryVector, topK, CATEGORY);
+
+ long unfilteredCount = postQuery(unfilteredQuery).get("resultTable").get("rows").get(0).get(0).asLong();
+ long filteredCount = postQuery(filteredQuery).get("resultTable").get("rows").get(0).get(0).asLong();
+
+ assertTrue(filteredCount <= unfilteredCount,
+ "Filtered (" + filteredCount + ") should be <= unfiltered (" + unfilteredCount + ")");
+ assertTrue(filteredCount > 0, "Filtered ANN should return at least 1 result");
+ }
+
+ /**
+ * Tests that EXPLAIN output includes execution mode for vector queries.
+ */
+ @Test(dataProvider = "useBothQueryEngines")
+ public void testExplainShowsExecutionMode(boolean useMultiStageQueryEngine)
+ throws Exception {
+ setUseMultiStageQueryEngine(useMultiStageQueryEngine);
+ String queryVector = "ARRAY[1.1" + StringUtils.repeat(", 1.1", VECTOR_DIM_SIZE - 1) + "]";
+
+ String explainQuery = String.format(
+ "set explainAskingServers=true; EXPLAIN PLAN FOR "
+ + "SELECT cosineDistance(%s, %s) AS dist FROM %s "
+ + "WHERE vectorSimilarity(%s, %s, %d) ORDER BY dist ASC LIMIT %d",
+ VECTOR_1, queryVector, getTableName(), VECTOR_1, queryVector, 5, 5);
+
+ JsonNode result = postQuery(explainQuery);
+ String explain = result.get("resultTable").toString();
+ assertTrue(explain.contains("executionMode"),
+ "EXPLAIN should contain executionMode: " + explain);
+ }
+
@Override
public String getTableName() {
return DEFAULT_TABLE_NAME;
@@ -245,6 +327,7 @@ public class VectorTest extends CustomDataQueryClusterIntegrationTest {
.addSingleValueDimension(VECTORS_L2_DIST, FieldSpec.DataType.DOUBLE)
.addSingleValueDimension(VECTOR_ZERO_L1_DIST, FieldSpec.DataType.DOUBLE)
.addSingleValueDimension(VECTOR_ZERO_L2_DIST, FieldSpec.DataType.DOUBLE)
+ .addSingleValueDimension(CATEGORY, FieldSpec.DataType.STRING)
.build();
}
@@ -286,6 +369,9 @@ public class VectorTest extends CustomDataQueryClusterIntegrationTest {
null, null),
new org.apache.avro.Schema.Field(VECTOR_ZERO_L2_DIST,
org.apache.avro.Schema.create(org.apache.avro.Schema.Type.DOUBLE),
+ null, null),
+ new org.apache.avro.Schema.Field(CATEGORY,
+ org.apache.avro.Schema.create(org.apache.avro.Schema.Type.STRING),
null, null)
));
@@ -310,6 +396,7 @@ public class VectorTest extends CustomDataQueryClusterIntegrationTest {
record.put(VECTORS_L2_DIST, VectorFunctions.l2Distance(vector1, vector2));
record.put(VECTOR_ZERO_L1_DIST, VectorFunctions.l1Distance(vector1, zeroVector));
record.put(VECTOR_ZERO_L2_DIST, VectorFunctions.l2Distance(vector1, zeroVector));
+ record.put(CATEGORY, "cat_" + (i % NUM_CATEGORIES));
// add avro record to file
writers.get(i % getNumAvroFiles()).append(record);
diff --git a/pinot-perf/src/main/java/org/apache/pinot/perf/BenchmarkVectorPhase3.java b/pinot-perf/src/main/java/org/apache/pinot/perf/BenchmarkVectorPhase3.java
new file mode 100644
index 00000000000..e991672e310
--- /dev/null
+++ b/pinot-perf/src/main/java/org/apache/pinot/perf/BenchmarkVectorPhase3.java
@@ -0,0 +1,264 @@
+/**
+ * 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.pinot.perf;
+
+import java.io.PrintStream;
+import java.util.Arrays;
+import java.util.Random;
+import org.apache.pinot.common.function.scalar.VectorFunctions;
+import org.apache.pinot.segment.spi.index.creator.VectorIndexConfig;
+
+
+/**
+ * Benchmark harness for Phase 3 vector query semantics: filtered ANN, threshold search,
+ * and compound retrieval patterns.
+ *
+ * <p>This benchmark operates at the vector-level (no full segment/query engine) to measure
+ * the isolated cost of execution mode selection, filtered candidate reduction, and threshold
+ * refinement.</p>
+ *
+ * <h3>Usage</h3>
+ * <pre>
+ * ./mvnw -pl pinot-perf -am compile
+ * java -cp pinot-perf/target/classes:... org.apache.pinot.perf.BenchmarkVectorPhase3
+ * </pre>
+ */
+public final class BenchmarkVectorPhase3 {
+
+ private static final long SEED = 42L;
+ private static final int NUM_QUERIES = 200;
+ private static final int WARMUP_QUERIES = 50;
+ private static final PrintStream OUT = System.out;
+
+ private BenchmarkVectorPhase3() {
+ }
+
+ public static void main(String[] args) {
+ int n = Integer.getInteger("pinot.perf.vector.n", 50000);
+ int dim = Integer.getInteger("pinot.perf.vector.dim", 128);
+ int topK = Integer.getInteger("pinot.perf.vector.topK", 10);
+
+ OUT.println("=== Phase 3 Vector Query Semantics Benchmark ===");
+ OUT.printf("Corpus: %d vectors, dimension: %d, topK: %d%n%n", n, dim, topK);
+
+ float[][] corpus = BenchmarkVectorIndex.generateGaussianVectors(n, dim, SEED);
+ float[][] queries = BenchmarkVectorIndex.generateGaussianVectors(NUM_QUERIES, dim, SEED + 1000);
+ boolean[] filterMask = generateFilterMask(n, SEED + 2000);
+
+ VectorIndexConfig.VectorDistanceFunction distFunc = VectorIndexConfig.VectorDistanceFunction.EUCLIDEAN;
+
+ // 1. Exact scan baseline
+ benchmarkExactScan(corpus, queries, topK, distFunc);
+
+ // 2. Filtered exact scan at various selectivities
+ for (double selectivity : new double[]{0.01, 0.1, 0.5, 0.9}) {
+ boolean[] selectiveFilter = generateSelectiveFilter(n, selectivity, SEED + 3000);
+ benchmarkFilteredExactScan(corpus, queries, topK, distFunc, selectiveFilter, selectivity);
+ }
+
+ // 3. Threshold scan baseline
+ // For 128-dim Gaussian vectors, L2 squared distances are ~256 on average.
+ // Use thresholds that produce meaningful result counts.
+ for (float threshold : new float[]{200.0f, 240.0f, 260.0f}) {
+ benchmarkThresholdScan(corpus, queries, threshold, distFunc);
+ }
+
+ // 4. Filtered threshold scan
+ for (float threshold : new float[]{240.0f}) {
+ for (double selectivity : new double[]{0.1, 0.5}) {
+ boolean[] selectiveFilter = generateSelectiveFilter(n, selectivity, SEED + 3000);
+ benchmarkFilteredThresholdScan(corpus, queries, threshold, distFunc, selectiveFilter, selectivity);
+ }
+ }
+
+ OUT.println("\n=== Benchmark complete ===");
+ }
+
+ private static void benchmarkExactScan(float[][] corpus, float[][] queries, int topK,
+ VectorIndexConfig.VectorDistanceFunction distFunc) {
+ // Warmup
+ for (int i = 0; i < WARMUP_QUERIES; i++) {
+ exactTopK(corpus, queries[i % queries.length], topK, distFunc);
+ }
+
+ long[] latencies = new long[NUM_QUERIES];
+ for (int i = 0; i < NUM_QUERIES; i++) {
+ long start = System.nanoTime();
+ exactTopK(corpus, queries[i], topK, distFunc);
+ latencies[i] = System.nanoTime() - start;
+ }
+
+ Arrays.sort(latencies);
+ OUT.printf("Exact scan (topK=%d): p50=%.2fms p95=%.2fms%n",
+ topK, latencies[NUM_QUERIES / 2] / 1e6, latencies[(int) (NUM_QUERIES * 0.95)] / 1e6);
+ }
+
+ private static void benchmarkFilteredExactScan(float[][] corpus, float[][] queries, int topK,
+ VectorIndexConfig.VectorDistanceFunction distFunc, boolean[] filter, double selectivity) {
+ // Warmup
+ for (int i = 0; i < WARMUP_QUERIES; i++) {
+ filteredExactTopK(corpus, queries[i % queries.length], topK, distFunc, filter);
+ }
+
+ long[] latencies = new long[NUM_QUERIES];
+ int totalResults = 0;
+ for (int i = 0; i < NUM_QUERIES; i++) {
+ long start = System.nanoTime();
+ int[] result = filteredExactTopK(corpus, queries[i], topK, distFunc, filter);
+ latencies[i] = System.nanoTime() - start;
+ totalResults += result.length;
+ }
+
+ Arrays.sort(latencies);
+ OUT.printf("Filtered exact scan (selectivity=%.0f%%, topK=%d): p50=%.2fms p95=%.2fms avgResults=%.1f%n",
+ selectivity * 100, topK, latencies[NUM_QUERIES / 2] / 1e6, latencies[(int) (NUM_QUERIES * 0.95)] / 1e6,
+ totalResults / (double) NUM_QUERIES);
+ }
+
+ private static void benchmarkThresholdScan(float[][] corpus, float[][] queries, float threshold,
+ VectorIndexConfig.VectorDistanceFunction distFunc) {
+ // Warmup
+ for (int i = 0; i < WARMUP_QUERIES; i++) {
+ thresholdScan(corpus, queries[i % queries.length], threshold, distFunc);
+ }
+
+ long[] latencies = new long[NUM_QUERIES];
+ int totalResults = 0;
+ for (int i = 0; i < NUM_QUERIES; i++) {
+ long start = System.nanoTime();
+ int count = thresholdScan(corpus, queries[i], threshold, distFunc);
+ latencies[i] = System.nanoTime() - start;
+ totalResults += count;
+ }
+
+ Arrays.sort(latencies);
+ OUT.printf("Threshold scan (threshold=%.1f): p50=%.2fms p95=%.2fms avgResults=%.1f%n",
+ threshold, latencies[NUM_QUERIES / 2] / 1e6, latencies[(int) (NUM_QUERIES * 0.95)] / 1e6,
+ totalResults / (double) NUM_QUERIES);
+ }
+
+ private static void benchmarkFilteredThresholdScan(float[][] corpus, float[][] queries, float threshold,
+ VectorIndexConfig.VectorDistanceFunction distFunc, boolean[] filter, double selectivity) {
+ // Warmup
+ for (int i = 0; i < WARMUP_QUERIES; i++) {
+ filteredThresholdScan(corpus, queries[i % queries.length], threshold, distFunc, filter);
+ }
+
+ long[] latencies = new long[NUM_QUERIES];
+ int totalResults = 0;
+ for (int i = 0; i < NUM_QUERIES; i++) {
+ long start = System.nanoTime();
+ int count = filteredThresholdScan(corpus, queries[i], threshold, distFunc, filter);
+ latencies[i] = System.nanoTime() - start;
+ totalResults += count;
+ }
+
+ Arrays.sort(latencies);
+ OUT.printf("Filtered threshold scan (threshold=%.1f, selectivity=%.0f%%): "
+ + "p50=%.2fms p95=%.2fms avgResults=%.1f%n",
+ threshold, selectivity * 100, latencies[NUM_QUERIES / 2] / 1e6,
+ latencies[(int) (NUM_QUERIES * 0.95)] / 1e6, totalResults / (double) NUM_QUERIES);
+ }
+
+ // --- Core search methods ---
+
+ static int[] exactTopK(float[][] corpus, float[] query, int topK,
+ VectorIndexConfig.VectorDistanceFunction distFunc) {
+ return BenchmarkVectorIndex.exactTopK(corpus, query, topK, distFunc);
+ }
+
+ static int[] filteredExactTopK(float[][] corpus, float[] query, int topK,
+ VectorIndexConfig.VectorDistanceFunction distFunc, boolean[] filter) {
+ int n = corpus.length;
+ float[] distances = new float[n];
+ int validCount = 0;
+ for (int i = 0; i < n; i++) {
+ if (!filter[i]) {
+ distances[i] = Float.MAX_VALUE;
+ continue;
+ }
+ distances[i] = computeDistance(query, corpus[i], distFunc);
+ validCount++;
+ }
+ if (validCount == 0) {
+ return new int[0];
+ }
+ Integer[] indices = new Integer[n];
+ for (int i = 0; i < n; i++) {
+ indices[i] = i;
+ }
+ final float[] d = distances;
+ Arrays.sort(indices, (a, b) -> Float.compare(d[a], d[b]));
+ int resultSize = Math.min(topK, validCount);
+ int[] result = new int[resultSize];
+ for (int i = 0; i < resultSize; i++) {
+ result[i] = indices[i];
+ }
+ return result;
+ }
+
+ static int thresholdScan(float[][] corpus, float[] query, float threshold,
+ VectorIndexConfig.VectorDistanceFunction distFunc) {
+ int count = 0;
+ for (float[] vector : corpus) {
+ if (computeDistance(query, vector, distFunc) <= threshold) {
+ count++;
+ }
+ }
+ return count;
+ }
+
+ static int filteredThresholdScan(float[][] corpus, float[] query, float threshold,
+ VectorIndexConfig.VectorDistanceFunction distFunc, boolean[] filter) {
+ int count = 0;
+ for (int i = 0; i < corpus.length; i++) {
+ if (filter[i] && computeDistance(query, corpus[i], distFunc) <= threshold) {
+ count++;
+ }
+ }
+ return count;
+ }
+
+ // --- Utility methods ---
+
+ static boolean[] generateFilterMask(int n, long seed) {
+ return generateSelectiveFilter(n, 0.5, seed);
+ }
+
+ static boolean[] generateSelectiveFilter(int n, double selectivity, long seed) {
+ Random rng = new Random(seed);
+ boolean[] mask = new boolean[n];
+ for (int i = 0; i < n; i++) {
+ mask[i] = rng.nextDouble() < selectivity;
+ }
+ return mask;
+ }
+
+ static float computeDistance(float[] a, float[] b, VectorIndexConfig.VectorDistanceFunction distFunc) {
+ switch (distFunc) {
+ case EUCLIDEAN:
+ case L2:
+ return (float) VectorFunctions.euclideanDistance(a, b);
+ case COSINE:
+ return (float) VectorFunctions.cosineDistance(a, b, 1.0d);
+ default:
+ throw new IllegalArgumentException("Unsupported: " + distFunc);
+ }
+ }
+}
diff --git a/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendCapabilities.java b/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendCapabilities.java
new file mode 100644
index 00000000000..976917ed2a2
--- /dev/null
+++ b/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendCapabilities.java
@@ -0,0 +1,149 @@
+/**
+ * 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.pinot.segment.spi.index.creator;
+
+
+/**
+ * Declares the query-time capabilities of a vector index backend.
+ *
+ * <p>This model allows the query planner and runtime to reason about what a backend can do
+ * without backend-specific branching. Each {@link VectorBackendType} returns its own
+ * capabilities instance via {@link VectorBackendType#getCapabilities()}.</p>
+ *
+ * <p>Capability flags are intentionally conservative: a backend should only declare a
+ * capability if it can deliver correct results for that mode. The runtime uses these
+ * flags to select execution modes and to decide when an exact-scan fallback is required.</p>
+ *
+ * <p>This class is immutable and thread-safe.</p>
+ */
+public final class VectorBackendCapabilities {
+
+ private final boolean _supportsTopKAnn;
+ private final boolean _supportsFilterAwareSearch;
+ private final boolean _supportsApproximateRadius;
+ private final boolean _supportsExactRerank;
+ private final boolean _supportsRuntimeSearchParams;
+
+ private VectorBackendCapabilities(boolean supportsTopKAnn, boolean supportsFilterAwareSearch,
+ boolean supportsApproximateRadius, boolean supportsExactRerank, boolean supportsRuntimeSearchParams) {
+ _supportsTopKAnn = supportsTopKAnn;
+ _supportsFilterAwareSearch = supportsFilterAwareSearch;
+ _supportsApproximateRadius = supportsApproximateRadius;
+ _supportsExactRerank = supportsExactRerank;
+ _supportsRuntimeSearchParams = supportsRuntimeSearchParams;
+ }
+
+ /**
+ * Whether the backend can answer top-K approximate nearest-neighbor queries.
+ * All current backends support this.
+ */
+ public boolean supportsTopKAnn() {
+ return _supportsTopKAnn;
+ }
+
+ /**
+ * Whether the backend can internally prune candidates using a metadata filter bitmap
+ * during ANN search. When false, filtering must happen as a separate post-ANN step.
+ *
+ * <p>Currently no backend supports this; the flag exists to enable future backends
+ * (e.g., Lucene HNSW with filtered search, or a future IVF variant) without API changes.</p>
+ */
+ public boolean supportsFilterAwareSearch() {
+ return _supportsFilterAwareSearch;
+ }
+
+ /**
+ * Whether the backend can natively answer approximate radius/threshold queries
+ * (returning all vectors within a distance threshold rather than top-K).
+ *
+ * <p>When false, the runtime must use ANN candidate generation followed by exact
+ * threshold refinement.</p>
+ */
+ public boolean supportsApproximateRadius() {
+ return _supportsApproximateRadius;
+ }
+
+ /**
+ * Whether the backend's ANN results can be refined using exact distance from the
+ * forward index. All current backends support this when a forward index is available.
+ */
+ public boolean supportsExactRerank() {
+ return _supportsExactRerank;
+ }
+
+ /**
+ * Whether the backend accepts runtime search parameters (e.g., nprobe).
+ * True for IVF_FLAT and IVF_PQ; false for HNSW.
+ */
+ public boolean supportsRuntimeSearchParams() {
+ return _supportsRuntimeSearchParams;
+ }
+
+ @Override
+ public String toString() {
+ return "VectorBackendCapabilities{"
+ + "topKAnn=" + _supportsTopKAnn
+ + ", filterAwareSearch=" + _supportsFilterAwareSearch
+ + ", approximateRadius=" + _supportsApproximateRadius
+ + ", exactRerank=" + _supportsExactRerank
+ + ", runtimeSearchParams=" + _supportsRuntimeSearchParams
+ + '}';
+ }
+
+ /**
+ * Builder for constructing capability instances.
+ */
+ public static final class Builder {
+ private boolean _supportsTopKAnn;
+ private boolean _supportsFilterAwareSearch;
+ private boolean _supportsApproximateRadius;
+ private boolean _supportsExactRerank;
+ private boolean _supportsRuntimeSearchParams;
+
+ public Builder supportsTopKAnn(boolean value) {
+ _supportsTopKAnn = value;
+ return this;
+ }
+
+ public Builder supportsFilterAwareSearch(boolean value) {
+ _supportsFilterAwareSearch = value;
+ return this;
+ }
+
+ public Builder supportsApproximateRadius(boolean value) {
+ _supportsApproximateRadius = value;
+ return this;
+ }
+
+ public Builder supportsExactRerank(boolean value) {
+ _supportsExactRerank = value;
+ return this;
+ }
+
+ public Builder supportsRuntimeSearchParams(boolean value) {
+ _supportsRuntimeSearchParams = value;
+ return this;
+ }
+
+ public VectorBackendCapabilities build() {
+ return new VectorBackendCapabilities(_supportsTopKAnn, _supportsFilterAwareSearch,
+ _supportsApproximateRadius, _supportsExactRerank, _supportsRuntimeSearchParams);
+ }
+ }
+}
diff --git a/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendType.java b/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendType.java
index 85d68557c56..32cf3b18197 100644
--- a/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendType.java
+++ b/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorBackendType.java
@@ -78,15 +78,61 @@ public enum VectorBackendType {
IVF_PQ("Inverted File with product-quantized vectors");
private final String _description;
+ private final VectorBackendCapabilities _capabilities;
VectorBackendType(String description) {
_description = description;
+ _capabilities = buildCapabilities();
}
public String getDescription() {
return _description;
}
+ /**
+ * Returns the query-time capabilities of this backend.
+ * Used by the runtime to select execution modes without backend-specific branching.
+ */
+ public VectorBackendCapabilities getCapabilities() {
+ return _capabilities;
+ }
+
+ private VectorBackendCapabilities buildCapabilities() {
+ // Use name() rather than enum constants because this runs during enum construction
+ // before constants are fully initialized.
+ switch (name()) {
+ case "HNSW":
+ return new VectorBackendCapabilities.Builder()
+ .supportsTopKAnn(true)
+ .supportsFilterAwareSearch(false)
+ .supportsApproximateRadius(false)
+ .supportsExactRerank(true)
+ .supportsRuntimeSearchParams(false)
+ .build();
+ case "IVF_FLAT":
+ return new VectorBackendCapabilities.Builder()
+ .supportsTopKAnn(true)
+ .supportsFilterAwareSearch(false)
+ .supportsApproximateRadius(false)
+ .supportsExactRerank(true)
+ .supportsRuntimeSearchParams(true)
+ .build();
+ case "IVF_PQ":
+ return new VectorBackendCapabilities.Builder()
+ .supportsTopKAnn(true)
+ .supportsFilterAwareSearch(false)
+ .supportsApproximateRadius(false)
+ .supportsExactRerank(true)
+ .supportsRuntimeSearchParams(true)
+ .build();
+ default:
+ return new VectorBackendCapabilities.Builder()
+ .supportsTopKAnn(true)
+ .supportsExactRerank(true)
+ .build();
+ }
+ }
+
public boolean supportsMutableSegments() {
return this == HNSW;
}
diff --git a/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorExecutionMode.java b/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorExecutionMode.java
new file mode 100644
index 00000000000..518a1a00af8
--- /dev/null
+++ b/pinot-segment-spi/src/main/java/org/apache/pinot/segment/spi/index/creator/VectorExecutionMode.java
@@ -0,0 +1,150 @@
+/**
+ * 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.pinot.segment.spi.index.creator;
+
+
+/**
+ * Enumerates the explicit execution modes for vector queries.
+ *
+ * <p>Each mode describes a specific strategy for combining ANN search, metadata filtering,
+ * threshold predicates, and exact refinement. The runtime selects a mode based on backend
+ * capabilities, query shape, and filter selectivity, then reports it in explain/debug output.</p>
+ *
+ * <p>Execution modes are ordered from cheapest/most approximate to most expensive/exact:</p>
+ * <ol>
+ * <li>{@link #ANN_TOP_K} - pure ANN, no filter, no rerank</li>
+ * <li>{@link #ANN_TOP_K_WITH_RERANK} - ANN + exact distance rerank</li>
+ * <li>{@link #ANN_THEN_FILTER} - ANN first, then apply metadata filter</li>
+ * <li>{@link #ANN_THEN_FILTER_THEN_RERANK} - ANN, filter, then rerank survivors</li>
+ * <li>{@link #FILTER_THEN_ANN} - apply filter first, then ANN on filtered subset</li>
+ * <li>{@link #ANN_THRESHOLD_SCAN} - ANN candidates + exact threshold refinement</li>
+ * <li>{@link #ANN_THRESHOLD_THEN_FILTER} - ANN candidates + threshold + filter</li>
+ * <li>{@link #EXACT_SCAN} - brute-force scan of all vectors</li>
+ * </ol>
+ */
+public enum VectorExecutionMode {
+
+ /**
+ * Pure ANN top-K search with no metadata filter and no exact rerank.
+ * This is the default mode for simple VECTOR_SIMILARITY queries.
+ */
+ ANN_TOP_K("ANN top-K search"),
+
+ /**
+ * ANN top-K search followed by exact distance reranking from the forward index.
+ * Used when vectorExactRerank=true (or backend default) and no metadata filter is present.
+ */
+ ANN_TOP_K_WITH_RERANK("ANN top-K with exact rerank"),
+
+ /**
+ * ANN search first, then metadata filter applied to ANN results.
+ * Used when a metadata filter is present but filter selectivity is not highly restrictive.
+ * Some valid results may be lost if the filter removes too many ANN candidates.
+ */
+ ANN_THEN_FILTER("ANN search, then metadata filter"),
+
+ /**
+ * ANN search, then metadata filter, then exact rerank of surviving candidates.
+ * Combines filtered ANN with exact refinement for better accuracy.
+ */
+ ANN_THEN_FILTER_THEN_RERANK("ANN search, then metadata filter, then exact rerank"),
+
+ /**
+ * Metadata filter applied first to produce a candidate set, then vector search on the
+ * filtered subset.
+ *
+ * <p><b>Not currently selectable.</b> Reserved for future backends that declare
+ * {@code supportsFilterAwareSearch=true}. No current backend supports this mode.</p>
+ */
+ FILTER_THEN_ANN("Metadata filter, then ANN search on filtered subset"),
+
+ /**
+ * ANN candidate generation followed by exact distance threshold refinement.
+ * Used for threshold/radius queries when no backend supports native radius search.
+ */
+ ANN_THRESHOLD_SCAN("ANN candidates, then exact threshold refinement"),
+
+ /**
+ * ANN candidate generation, exact threshold refinement, then metadata filter.
+ * Used for combined threshold + filter queries.
+ */
+ ANN_THRESHOLD_THEN_FILTER("ANN candidates, then threshold refinement, then metadata filter"),
+
+ /**
+ * Brute-force exact scan of all vectors in the segment.
+ * Used as a fallback when no ANN index is available, or when the planner determines
+ * that exact scan is more appropriate (e.g., very small segment, highly selective filter).
+ */
+ EXACT_SCAN("Exact brute-force vector scan");
+
+ private final String _description;
+
+ VectorExecutionMode(String description) {
+ _description = description;
+ }
+
+ public String getDescription() {
+ return _description;
+ }
+
+ /**
+ * Returns true if this mode involves ANN (approximate) search.
+ */
+ public boolean isApproximate() {
+ return this != EXACT_SCAN;
+ }
+
+ /**
+ * Returns true if this mode applies a metadata filter.
+ */
+ public boolean hasMetadataFilter() {
+ switch (this) {
+ case ANN_THEN_FILTER:
+ case ANN_THEN_FILTER_THEN_RERANK:
+ case FILTER_THEN_ANN:
+ case ANN_THRESHOLD_THEN_FILTER:
+ return true;
+ default:
+ return false;
+ }
+ }
+
+ /**
+ * Returns true if this mode involves exact rerank or threshold refinement.
+ */
+ public boolean hasExactRefinement() {
+ switch (this) {
+ case ANN_TOP_K_WITH_RERANK:
+ case ANN_THEN_FILTER_THEN_RERANK:
+ case ANN_THRESHOLD_SCAN:
+ case ANN_THRESHOLD_THEN_FILTER:
+ case EXACT_SCAN:
+ return true;
+ default:
+ return false;
+ }
+ }
+
+ /**
+ * Returns true if this mode involves threshold/radius semantics.
+ */
+ public boolean isThresholdMode() {
+ return this == ANN_THRESHOLD_SCAN || this == ANN_THRESHOLD_THEN_FILTER;
+ }
+}
diff --git a/pinot-segment-spi/src/test/java/org/apache/pinot/segment/spi/index/creator/VectorBackendCapabilitiesTest.java b/pinot-segment-spi/src/test/java/org/apache/pinot/segment/spi/index/creator/VectorBackendCapabilitiesTest.java
new file mode 100644
index 00000000000..d9205e03da3
--- /dev/null
+++ b/pinot-segment-spi/src/test/java/org/apache/pinot/segment/spi/index/creator/VectorBackendCapabilitiesTest.java
@@ -0,0 +1,120 @@
+/**
+ * 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.pinot.segment.spi.index.creator;
+
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertFalse;
+import static org.testng.Assert.assertNotNull;
+import static org.testng.Assert.assertTrue;
+
+
+/**
+ * Tests for {@link VectorBackendCapabilities} and its integration with {@link VectorBackendType}.
+ */
+public class VectorBackendCapabilitiesTest {
+
+ @Test
+ public void testHnswCapabilities() {
+ VectorBackendCapabilities caps = VectorBackendType.HNSW.getCapabilities();
+ assertNotNull(caps);
+ assertTrue(caps.supportsTopKAnn());
+ assertFalse(caps.supportsFilterAwareSearch());
+ assertFalse(caps.supportsApproximateRadius());
+ assertTrue(caps.supportsExactRerank());
+ assertFalse(caps.supportsRuntimeSearchParams());
+ }
+
+ @Test
+ public void testIvfFlatCapabilities() {
+ VectorBackendCapabilities caps = VectorBackendType.IVF_FLAT.getCapabilities();
+ assertNotNull(caps);
+ assertTrue(caps.supportsTopKAnn());
+ assertFalse(caps.supportsFilterAwareSearch());
+ assertFalse(caps.supportsApproximateRadius());
+ assertTrue(caps.supportsExactRerank());
+ assertTrue(caps.supportsRuntimeSearchParams());
+ }
+
+ @Test
+ public void testIvfPqCapabilities() {
+ VectorBackendCapabilities caps = VectorBackendType.IVF_PQ.getCapabilities();
+ assertNotNull(caps);
+ assertTrue(caps.supportsTopKAnn());
+ assertFalse(caps.supportsFilterAwareSearch());
+ assertFalse(caps.supportsApproximateRadius());
+ assertTrue(caps.supportsExactRerank());
+ assertTrue(caps.supportsRuntimeSearchParams());
+ }
+
+ @Test
+ public void testConsistencyWithLegacyMethods() {
+ // Verify that capabilities are consistent with the existing VectorBackendType methods
+ for (VectorBackendType type : VectorBackendType.values()) {
+ VectorBackendCapabilities caps = type.getCapabilities();
+ assertEquals(caps.supportsRuntimeSearchParams(), type.supportsNprobe(),
+ "supportsRuntimeSearchParams should match supportsNprobe for " + type);
+ }
+ }
+
+ @Test
+ public void testBuilderDefaults() {
+ VectorBackendCapabilities caps = new VectorBackendCapabilities.Builder().build();
+ assertFalse(caps.supportsTopKAnn());
+ assertFalse(caps.supportsFilterAwareSearch());
+ assertFalse(caps.supportsApproximateRadius());
+ assertFalse(caps.supportsExactRerank());
+ assertFalse(caps.supportsRuntimeSearchParams());
+ }
+
+ @Test
+ public void testBuilderCustom() {
+ VectorBackendCapabilities caps = new VectorBackendCapabilities.Builder()
+ .supportsTopKAnn(true)
+ .supportsFilterAwareSearch(true)
+ .supportsApproximateRadius(true)
+ .supportsExactRerank(true)
+ .supportsRuntimeSearchParams(true)
+ .build();
+ assertTrue(caps.supportsTopKAnn());
+ assertTrue(caps.supportsFilterAwareSearch());
+ assertTrue(caps.supportsApproximateRadius());
+ assertTrue(caps.supportsExactRerank());
+ assertTrue(caps.supportsRuntimeSearchParams());
+ }
+
+ @Test
+ public void testToString() {
+ VectorBackendCapabilities caps = VectorBackendType.HNSW.getCapabilities();
+ String str = caps.toString();
+ assertTrue(str.contains("topKAnn=true"));
+ assertTrue(str.contains("filterAwareSearch=false"));
+ assertTrue(str.contains("runtimeSearchParams=false"));
+ }
+
+ @Test
+ public void testAllBackendsHaveCapabilities() {
+ for (VectorBackendType type : VectorBackendType.values()) {
+ assertNotNull(type.getCapabilities(), "Capabilities must not be null for " + type);
+ assertTrue(type.getCapabilities().supportsTopKAnn(),
+ "All current backends should support top-K ANN for " + type);
+ }
+ }
+}
diff --git a/pinot-segment-spi/src/test/java/org/apache/pinot/segment/spi/index/creator/VectorExecutionModeTest.java b/pinot-segment-spi/src/test/java/org/apache/pinot/segment/spi/index/creator/VectorExecutionModeTest.java
new file mode 100644
index 00000000000..a4245d22f8c
--- /dev/null
+++ b/pinot-segment-spi/src/test/java/org/apache/pinot/segment/spi/index/creator/VectorExecutionModeTest.java
@@ -0,0 +1,101 @@
+/**
+ * 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.pinot.segment.spi.index.creator;
+
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertFalse;
+import static org.testng.Assert.assertNotNull;
+import static org.testng.Assert.assertTrue;
+
+
+/**
+ * Tests for the {@link VectorExecutionMode} enum.
+ */
+public class VectorExecutionModeTest {
+
+ @Test
+ public void testAllModesHaveDescription() {
+ for (VectorExecutionMode mode : VectorExecutionMode.values()) {
+ assertNotNull(mode.getDescription());
+ assertFalse(mode.getDescription().isEmpty(), "Description must not be empty for " + mode);
+ }
+ }
+
+ @Test
+ public void testIsApproximate() {
+ assertTrue(VectorExecutionMode.ANN_TOP_K.isApproximate());
+ assertTrue(VectorExecutionMode.ANN_TOP_K_WITH_RERANK.isApproximate());
+ assertTrue(VectorExecutionMode.ANN_THEN_FILTER.isApproximate());
+ assertTrue(VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK.isApproximate());
+ assertTrue(VectorExecutionMode.FILTER_THEN_ANN.isApproximate());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_SCAN.isApproximate());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER.isApproximate());
+ assertFalse(VectorExecutionMode.EXACT_SCAN.isApproximate());
+ }
+
+ @Test
+ public void testHasMetadataFilter() {
+ assertFalse(VectorExecutionMode.ANN_TOP_K.hasMetadataFilter());
+ assertFalse(VectorExecutionMode.ANN_TOP_K_WITH_RERANK.hasMetadataFilter());
+ assertTrue(VectorExecutionMode.ANN_THEN_FILTER.hasMetadataFilter());
+ assertTrue(VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK.hasMetadataFilter());
+ assertTrue(VectorExecutionMode.FILTER_THEN_ANN.hasMetadataFilter());
+ assertFalse(VectorExecutionMode.ANN_THRESHOLD_SCAN.hasMetadataFilter());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER.hasMetadataFilter());
+ assertFalse(VectorExecutionMode.EXACT_SCAN.hasMetadataFilter());
+ }
+
+ @Test
+ public void testHasExactRefinement() {
+ assertFalse(VectorExecutionMode.ANN_TOP_K.hasExactRefinement());
+ assertTrue(VectorExecutionMode.ANN_TOP_K_WITH_RERANK.hasExactRefinement());
+ assertFalse(VectorExecutionMode.ANN_THEN_FILTER.hasExactRefinement());
+ assertTrue(VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK.hasExactRefinement());
+ assertFalse(VectorExecutionMode.FILTER_THEN_ANN.hasExactRefinement());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_SCAN.hasExactRefinement());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER.hasExactRefinement());
+ assertTrue(VectorExecutionMode.EXACT_SCAN.hasExactRefinement());
+ }
+
+ @Test
+ public void testIsThresholdMode() {
+ assertFalse(VectorExecutionMode.ANN_TOP_K.isThresholdMode());
+ assertFalse(VectorExecutionMode.ANN_TOP_K_WITH_RERANK.isThresholdMode());
+ assertFalse(VectorExecutionMode.ANN_THEN_FILTER.isThresholdMode());
+ assertFalse(VectorExecutionMode.ANN_THEN_FILTER_THEN_RERANK.isThresholdMode());
+ assertFalse(VectorExecutionMode.FILTER_THEN_ANN.isThresholdMode());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_SCAN.isThresholdMode());
+ assertTrue(VectorExecutionMode.ANN_THRESHOLD_THEN_FILTER.isThresholdMode());
+ assertFalse(VectorExecutionMode.EXACT_SCAN.isThresholdMode());
+ }
+
+ @Test
+ public void testExpectedModesExist() {
+ // Verify all Phase 3 modes are present (extensible: new modes don't break this test)
+ assertNotNull(VectorExecutionMode.valueOf("ANN_TOP_K"));
+ assertNotNull(VectorExecutionMode.valueOf("ANN_TOP_K_WITH_RERANK"));
+ assertNotNull(VectorExecutionMode.valueOf("ANN_THEN_FILTER"));
+ assertNotNull(VectorExecutionMode.valueOf("ANN_THEN_FILTER_THEN_RERANK"));
+ assertNotNull(VectorExecutionMode.valueOf("FILTER_THEN_ANN"));
+ assertNotNull(VectorExecutionMode.valueOf("ANN_THRESHOLD_SCAN"));
+ assertNotNull(VectorExecutionMode.valueOf("ANN_THRESHOLD_THEN_FILTER"));
+ assertNotNull(VectorExecutionMode.valueOf("EXACT_SCAN"));
+ }
+}
diff --git a/pinot-spi/src/main/java/org/apache/pinot/spi/utils/CommonConstants.java b/pinot-spi/src/main/java/org/apache/pinot/spi/utils/CommonConstants.java
index 0388a884da4..90f358c6bd9 100644
--- a/pinot-spi/src/main/java/org/apache/pinot/spi/utils/CommonConstants.java
+++ b/pinot-spi/src/main/java/org/apache/pinot/spi/utils/CommonConstants.java
@@ -927,6 +927,11 @@ public class CommonConstants {
/** Maximum number of ANN candidates to retrieve before applying exact rerank or final
* top-K selection. Defaults to topK * 10 if not set. */
public static final String VECTOR_MAX_CANDIDATES = "vectorMaxCandidates";
+
+ /** Distance threshold for vector radius/threshold search. When set, the query returns
+ * all vectors within this distance rather than a fixed top-K. ANN candidate generation
+ * is used followed by exact threshold refinement. */
+ public static final String VECTOR_DISTANCE_THRESHOLD = "vectorDistanceThreshold";
}
public static class QueryOptionValue {
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pinot.apache.org
For additional commands, e-mail: commits-help@pinot.apache.org