diff --git a/src/main/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQuery.java b/src/main/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQuery.java
index 7956217d2d..139383af74 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQuery.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQuery.java
@@ -6,14 +6,16 @@
import java.util.Objects;
/**
- * The reranking query to use for a reranking operation. Either from the $vectorize sort clause or
- * manually specified by the user.
+ * The reranking query to use for a reranking operation. Either from the $vectorize or $lexical sort
+ * clause, or manually specified by the user.
*/
public class RerankingQuery implements Recordable {
public enum Source {
/** Query came from the $vectorize sort in the user query. This is the default. */
VECTORIZE,
+ /** Query came from the $lexical sort in the user query, when the sort is only $lexical. */
+ LEXICAL,
/** Query came from the options.rerankQuery property in the user query. */
OPTIONS,
}
@@ -45,15 +47,34 @@ public Source source() {
* vectorize.
* @return Constructed RerankingQuery, with the source indicating where the query came from.
*/
- public static RerankingQuery create(String rerankQuery, String vectorizeText) {
+ public static RerankingQuery forVectorizeSort(String rerankQuery, String vectorizeText) {
+ return create(rerankQuery, vectorizeText, Source.VECTORIZE);
+ }
+
+ /**
+ * Creates a new RerankingQuery for a $lexical sort: the rerankQuery option when it
+ * is not blank, otherwise the text of the $lexical sort.
+ *
+ *
Throws {@link RequestException.Code#MISSING_RERANK_QUERY_TEXT} if both are null or blank.
+ *
+ * @param rerankQuery The rerankQuery option, may be null.
+ * @param lexicalText The text of the $lexical sort.
+ * @return Constructed RerankingQuery, with the source indicating where the query came from.
+ */
+ public static RerankingQuery forLexicalSort(String rerankQuery, String lexicalText) {
+ return create(rerankQuery, lexicalText, Source.LEXICAL);
+ }
+
+ /** The rerankQuery option when it is not blank, otherwise the sort text and its source. */
+ private static RerankingQuery create(String rerankQuery, String sortText, Source sortSource) {
if (rerankQuery != null && !rerankQuery.isBlank()) {
return new RerankingQuery(rerankQuery, Source.OPTIONS);
}
// will never be blank, but double-checking for safety
- if (vectorizeText != null && !vectorizeText.isBlank()) {
- return new RerankingQuery(vectorizeText, Source.VECTORIZE);
+ if (sortText != null && !sortText.isBlank()) {
+ return new RerankingQuery(sortText, sortSource);
}
throw RequestException.Code.MISSING_RERANK_QUERY_TEXT.get();
diff --git a/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java b/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java
index 684a422d4a..6c0da4605a 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java
@@ -6,10 +6,12 @@
import com.fasterxml.jackson.databind.node.JsonNodeFactory;
import io.stargate.sgv2.jsonapi.api.model.command.*;
import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.SortDefinition;
+import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.FindAndRerankSort;
import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.SortClause;
import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.SortExpression;
import io.stargate.sgv2.jsonapi.api.model.command.impl.FindAndRerankCommand;
import io.stargate.sgv2.jsonapi.api.model.command.impl.FindCommand;
+import io.stargate.sgv2.jsonapi.metrics.CommandFeatures;
import io.stargate.sgv2.jsonapi.service.embedding.operation.EmbeddingProvider;
import io.stargate.sgv2.jsonapi.service.operation.Operation;
import io.stargate.sgv2.jsonapi.service.operation.embeddings.EmbeddingDeferredAction;
@@ -189,11 +191,20 @@ private TaskGroupAndDeferrables
+ getOrDefault(
+ command.options(),
+ FindAndRerankCommand.Options::hybridLimits,
+ FindAndRerankCommand.HybridLimits.DEFAULT);
+ case FindAndRerankSort.SingleLeg ignored -> {
+ var readLimit = plan.legs().getFirst().readLimit();
+ yield new FindAndRerankCommand.HybridLimits(
+ readLimit, readLimit, CommandFeatures.EMPTY);
+ }
+ });
var deferrables = new ArrayList();
diff --git a/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlanner.java b/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlanner.java
index bb516aaec7..4cda640f28 100644
--- a/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlanner.java
+++ b/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlanner.java
@@ -1,11 +1,15 @@
package io.stargate.sgv2.jsonapi.service.resolver;
+import static io.stargate.sgv2.jsonapi.config.constants.DocumentConstants.Fields.LEXICAL_CONTENT_FIELD;
import static io.stargate.sgv2.jsonapi.config.constants.DocumentConstants.Fields.VECTOR_EMBEDDING_TEXT_FIELD;
import static io.stargate.sgv2.jsonapi.exception.ErrorFormatters.errVars;
import static io.stargate.sgv2.jsonapi.util.ApiOptionUtils.getOrDefault;
import io.stargate.sgv2.jsonapi.api.model.command.CommandContext;
import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.FindAndRerankSort;
+import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.SortExpression2.LexicalSortExpression;
+import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.SortExpression2.VectorSortExpression;
+import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.SortExpression2.VectorizeSortExpression;
import io.stargate.sgv2.jsonapi.api.model.command.impl.FindAndRerankCommand;
import io.stargate.sgv2.jsonapi.config.IntConfigWithBounds;
import io.stargate.sgv2.jsonapi.config.OperationsConfig;
@@ -17,6 +21,7 @@
import io.stargate.sgv2.jsonapi.service.schema.collections.CollectionRerankDef;
import io.stargate.sgv2.jsonapi.service.schema.collections.CollectionSchemaObject;
import io.stargate.sgv2.jsonapi.util.PathMatchLocator;
+import io.stargate.sgv2.jsonapi.util.StringUtil;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
@@ -37,7 +42,7 @@ private FindAndRerankPlanner() {
*
* @param command The command to plan.
* @param commandContext Context for the command, it has the collection and the config.
- * @return The plan, it always has a VECTOR_LEG.
+ * @return The plan. A $hybrid sort always has a VECTOR_LEG, any other sort has one leg.
*/
static FindAndRerankPlan plan(
FindAndRerankCommand command, CommandContext commandContext) {
@@ -51,31 +56,28 @@ static FindAndRerankPlan plan(
validateSortSupported(sort, schemaObject);
validateHybridLimits(command, operationsConfig);
- validateRerankCandidateLimit(command, operationsConfig);
+ var rerankCandidateLimit = resolveRerankCandidateLimit(command, operationsConfig);
var rerankServiceDef = resolveRerankServiceDef(command, commandContext);
- var rerankingQuery =
- RerankingQuery.create(
- getOrDefault(command.options(), FindAndRerankCommand.Options::rerankQuery, null),
- vectorizeText(sort));
- var passageLocator = passageLocator(command);
+ var rerankingQuery = buildRerankingQuery(command);
+ var passageLocator = buildPassageLocator(command);
var projector = command.buildProjector();
// NOTE: the legs are planned after the options and the projection are checked, to keep the
// error order of the command: e.g. {"$hybrid": ""} with no rerankQuery fails with
- // MISSING_RERANK_QUERY_TEXT, not MISSING_HYBRID_SORT_VALUE
+ // MISSING_RERANK_QUERY_TEXT, not MISSING_HYBRID_SORT_VALUE. And a command with no sort and no
+ // options fails with MISSING_RERANK_QUERY_TEXT, not UNSUPPORTED_FIND_AND_RERANK_SORT.
// NOTE: a sort with no $vector or $vectorize fails here with a SORT error, not later with an
// UNEXPECTED_SERVER_ERROR, see GH #2577
var legs =
switch (sort) {
- case FindAndRerankSort.MultiLeg multiLeg -> multiLegs(command, multiLeg, schemaObject);
- // TODO: GH #2602, GH #2603 - plan single leg sorts. Until then every sort without
- // $hybrid is rejected here, after the checks above
- case FindAndRerankSort.SingleLeg ignored ->
- throw SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.get();
+ case FindAndRerankSort.MultiLeg multiLeg ->
+ buildMultiLegs(command, multiLeg, schemaObject);
+ case FindAndRerankSort.SingleLeg singleLeg ->
+ List.of(buildSingleLeg(singleLeg, rerankCandidateLimit));
};
- var vectorizeStep = isVectorizeSort(sort) ? planVectorizeStep(sort, schemaObject) : null;
+ var vectorizeStep = isVectorizeSort(sort) ? buildVectorizeStep(sort, schemaObject) : null;
int limit =
getOrDefault(
@@ -117,23 +119,29 @@ private static void validateHybridLimits(
}
/**
- * Validate the user-supplied rerankCandidateLimit: it cannot be used with a $hybrid sort, and
- * must be inside the dynamic OperationsConfig bounds.
+ * Resolves the read limit for a sort without $hybrid.
+ *
+ * @param command The command. It may have the rerankCandidateLimit option.
+ * @param operationsConfig The config that has the default and the bounds for the read limit.
+ * @return The rerankCandidateLimit option, or the default from the config when the
+ * option is not set.
*/
- private static void validateRerankCandidateLimit(
+ private static int resolveRerankCandidateLimit(
FindAndRerankCommand command, OperationsConfig operationsConfig) {
+ var bounds = operationsConfig.rerankCandidateLimit();
var limit =
getOrDefault(command.options(), FindAndRerankCommand.Options::rerankCandidateLimit, null);
if (limit == null) {
- return;
+ // not set on the command, so use the default from the config
+ return bounds.defaultValue();
}
+ // rerankCandidateLimit is only for a single leg sort, so a $hybrid sort must use hybridLimits
if (command.sortClause() instanceof FindAndRerankSort.MultiLeg) {
throw RequestException.Code.UNSUPPORTED_RERANK_CANDIDATE_LIMIT_WITH_HYBRID_SORT.get();
}
- validateLimitInBounds(
- FindAndRerankCommand.Options.Names.RERANK_CANDIDATE_LIMIT,
- limit,
- operationsConfig.rerankCandidateLimit());
+
+ validateLimitInBounds(FindAndRerankCommand.Options.Names.RERANK_CANDIDATE_LIMIT, limit, bounds);
+ return limit;
}
private static void validateLimitInBounds(String field, int value, IntConfigWithBounds bounds) {
@@ -186,16 +194,21 @@ private static void validateSortSupported(
}
/**
- * The legs of a $hybrid sort: always a vector leg, and a lexical leg when the sort has lexical
- * text and the collection has a lexical index. Without a lexical index the $hybrid text skips the
- * lexical leg, and an explicit $lexical throws. Throws when the sort has no vectorize text and no
- * vector for the vector leg.
+ * Builds the legs for a $hybrid sort.
+ *
+ * @param command The command. Its hybridLimits option sets the read limit of each
+ * leg.
+ * @param multiLeg The $hybrid sort of the command.
+ * @param schemaObject The collection. The lexical leg needs its lexical index.
+ * @return A vector leg, and a lexical leg when the sort has lexical text and the collection has a
+ * lexical index.
*/
- private static List multiLegs(
+ private static List buildMultiLegs(
FindAndRerankCommand command,
FindAndRerankSort.MultiLeg multiLeg,
CollectionSchemaObject schemaObject) {
+ // every $hybrid sort reads with the vector leg, so it needs $vectorize text or a $vector
if (!isVectorizeSort(multiLeg) && !isVectorSort(multiLeg)) {
throw isLexicalSort(multiLeg)
? SortException.Code.MISSING_VECTOR_OR_VECTORIZE_IN_HYBRID_SORT.get()
@@ -239,10 +252,37 @@ private static List multiLegs(
}
/**
- * The {@link FindAndRerankPlan.VectorizeStep} for the vectorize text of the sort, using the
- * vectorize column of the collection.
+ * Builds the leg for a sort without $hybrid.
+ *
+ * @param singleLeg The sort of the command.
+ * @param readLimit The maximum number of documents the leg reads.
+ * @return A vector leg for a $vectorize or $vector sort, or a lexical leg for a $lexical sort.
+ */
+ private static FindAndRerankPlan.RerankLeg buildSingleLeg(
+ FindAndRerankSort.SingleLeg singleLeg, int readLimit) {
+ return switch (singleLeg) {
+ // the vector leg reads with the vector from the vectorize step
+ case FindAndRerankSort.VectorLeg(VectorizeSortExpression ignored) ->
+ new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, null, null, readLimit);
+ case FindAndRerankSort.VectorLeg(VectorSortExpression(var vector)) ->
+ new FindAndRerankPlan.RerankLeg(RerankLegType.VECTOR_LEG, vector, null, readLimit);
+ case FindAndRerankSort.LexicalLeg(LexicalSortExpression(var lexicalText)) ->
+ new FindAndRerankPlan.RerankLeg(RerankLegType.LEXICAL_LEG, null, lexicalText, readLimit);
+ // TODO: GH #2603 - plan the filter leg. Until then a field sort, an empty sort and no sort
+ // are rejected here, after the checks in plan()
+ case FindAndRerankSort.FilterLeg ignored ->
+ throw SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.get();
+ };
+ }
+
+ /**
+ * Builds the {@link FindAndRerankPlan.VectorizeStep} for the vectorize text of the sort.
+ *
+ * @param sort The sort of the command. It must have vectorize text.
+ * @param schemaObject The collection. The step uses its vectorize column.
+ * @return The step that vectorizes the text with the vectorize service of the collection.
*/
- private static FindAndRerankPlan.VectorizeStep planVectorizeStep(
+ private static FindAndRerankPlan.VectorizeStep buildVectorizeStep(
FindAndRerankSort sort, CollectionSchemaObject schemaObject) {
// sanity check, validateSortSupported() checked the collection has a vectorize column
@@ -288,24 +328,52 @@ private static CollectionRerankDef.RerankServiceDef resolveRerankServiceDef(
return serviceDef;
}
- private static PathMatchLocator passageLocator(FindAndRerankCommand command) {
-
- var rerankOn = getOrDefault(command.options(), FindAndRerankCommand.Options::rerankOn, null);
- var isRerankOn = rerankOn != null && !rerankOn.isBlank();
+ /**
+ * Builds the query to rerank with.
+ *
+ * @param command The command. It has the sort and may have the rerankQuery option.
+ * @return The query from the rerankQuery option, or from the sort when the option is
+ * null or blank.
+ */
+ private static RerankingQuery buildRerankingQuery(FindAndRerankCommand command) {
+ var sort = command.sortClause();
+ var rerankQueryOption =
+ getOrDefault(command.options(), FindAndRerankCommand.Options::rerankQuery, null);
+
+ // the default query is the text of the sort: the lexical text for a $lexical sort, otherwise
+ // the vectorize text for $vectorize or $hybrid
+ return sort instanceof FindAndRerankSort.LexicalLeg(LexicalSortExpression(var lexicalText))
+ ? RerankingQuery.forLexicalSort(rerankQueryOption, lexicalText)
+ : RerankingQuery.forVectorizeSort(rerankQueryOption, vectorizeText(sort));
+ }
- String finalRerankField;
+ /**
+ * Builds the locator that finds the passage to rerank in each document.
+ *
+ * @param command The command. It has the sort and may have the rerankOn option.
+ * @return The locator for the field in the rerankOn option, or for the default field
+ * of the sort when the option is null or blank.
+ */
+ private static PathMatchLocator buildPassageLocator(FindAndRerankCommand command) {
+ var sort = command.sortClause();
+ var rerankOnOption =
+ getOrDefault(command.options(), FindAndRerankCommand.Options::rerankOn, null);
- if (isVectorizeSort(command.sortClause())) {
- // use the vectorize field, unless the user has overridden
- finalRerankField = isRerankOn ? rerankOn : VECTOR_EMBEDDING_TEXT_FIELD;
- } else if (isRerankOn) {
- // user has to provide a field to rerank on
- finalRerankField = rerankOn;
- } else {
- throw RequestException.Code.MISSING_RERANK_ON.get();
+ // the user set rerankOn, so it replaces the default field of the sort
+ if (!StringUtil.isNullOrBlank(rerankOnOption)) {
+ return PathMatchLocator.forPath(rerankOnOption);
}
-
- return PathMatchLocator.forPath(finalRerankField);
+ // a $lexical sort reranks on the $lexical field by default
+ if (sort instanceof FindAndRerankSort.LexicalLeg) {
+ return PathMatchLocator.forPath(LEXICAL_CONTENT_FIELD);
+ }
+ // a sort with vectorize text, e.g. $vectorize or $hybrid, reranks on the $vectorize field by
+ // default
+ if (isVectorizeSort(sort)) {
+ return PathMatchLocator.forPath(VECTOR_EMBEDDING_TEXT_FIELD);
+ }
+ // other sorts, e.g. $vector or a field sort, have no default field, so rerankOn is required
+ throw RequestException.Code.MISSING_RERANK_ON.get();
}
private static void throwIfNoLexicalIndex(CollectionSchemaObject schemaObject) {
@@ -322,7 +390,10 @@ private static String vectorizeText(FindAndRerankSort sort) {
return switch (sort) {
case FindAndRerankSort.HybridText hybridText -> hybridText.text();
case FindAndRerankSort.HybridObject hybridObject -> hybridObject.vectorize();
- case FindAndRerankSort.SingleLeg ignored -> null;
+ case FindAndRerankSort.VectorLeg(VectorizeSortExpression(var text)) -> text;
+ case FindAndRerankSort.VectorLeg(VectorSortExpression ignored) -> null;
+ case FindAndRerankSort.LexicalLeg ignored -> null;
+ case FindAndRerankSort.FilterLeg ignored -> null;
};
}
@@ -333,25 +404,40 @@ private static String lexicalText(FindAndRerankSort sort) {
return switch (sort) {
case FindAndRerankSort.HybridText hybridText -> hybridText.text();
case FindAndRerankSort.HybridObject hybridObject -> hybridObject.lexical();
- case FindAndRerankSort.SingleLeg ignored -> null;
+ case FindAndRerankSort.LexicalLeg(LexicalSortExpression(var text)) -> text;
+ case FindAndRerankSort.VectorLeg ignored -> null;
+ case FindAndRerankSort.FilterLeg ignored -> null;
};
}
- /** The vector from the $hybrid object, or null. */
+ /** The vector from the $hybrid object or from the $vector sort, or null. */
private static float[] vector(FindAndRerankSort sort) {
- return sort instanceof FindAndRerankSort.HybridObject hybridObject
- ? hybridObject.vector()
- : null;
+ return switch (sort) {
+ case FindAndRerankSort.HybridText ignored -> null;
+ case FindAndRerankSort.HybridObject hybridObject -> hybridObject.vector();
+ case FindAndRerankSort.VectorLeg(VectorSortExpression(var vector)) -> vector;
+ case FindAndRerankSort.VectorLeg(VectorizeSortExpression ignored) -> null;
+ case FindAndRerankSort.LexicalLeg ignored -> null;
+ case FindAndRerankSort.FilterLeg ignored -> null;
+ };
}
private static boolean isLexicalSort(FindAndRerankSort sort) {
return lexicalText(sort) != null;
}
- /** The $hybrid object has $lexical text, so the collection must have a lexical index. */
+ /**
+ * The $hybrid object has $lexical text, or the sort is $lexical, so the collection must have a
+ * lexical index.
+ */
private static boolean isExplicitLexicalSort(FindAndRerankSort sort) {
- return sort instanceof FindAndRerankSort.HybridObject hybridObject
- && hybridObject.lexical() != null;
+ return switch (sort) {
+ case FindAndRerankSort.HybridText ignored -> false;
+ case FindAndRerankSort.HybridObject hybridObject -> hybridObject.lexical() != null;
+ case FindAndRerankSort.LexicalLeg ignored -> true;
+ case FindAndRerankSort.VectorLeg ignored -> false;
+ case FindAndRerankSort.FilterLeg ignored -> false;
+ };
}
private static boolean isVectorizeSort(FindAndRerankSort sort) {
diff --git a/src/main/resources/errors.yaml b/src/main/resources/errors.yaml
index d3541cd1d2..0114739d4b 100644
--- a/src/main/resources/errors.yaml
+++ b/src/main/resources/errors.yaml
@@ -299,6 +299,8 @@ request-errors:
The passage text can be specified using either:
* `$hybrid` field in the sort clause, in which case documents are ranked using the value of `$vectorize` e.g. `{"$hybrid": "query text"}`.
* `$vectorize` field in the sort clause, when using different sorting for vectorize and lexical, e.g. `{"$hybrid": {"$vectorize": "query text"}}`.
+ * `$vectorize` field as the only field in the sort clause, in which case documents are ranked using the value of `$vectorize`, e.g. `{"$vectorize": "query text"}`.
+ * `$lexical` field as the only field in the sort clause, in which case documents are ranked using the value of `$lexical`, e.g. `{"$lexical": "query text"}`.
* `rerankOn` field in the options clause, e.g. `{"rerankOn": "my_passage_field"}`.
When specified the `rerankOn` option takes priority. In all cases the passage text must be a non blank text value.
@@ -317,6 +319,8 @@ request-errors:
The query can be specified using either:
* `$hybrid` field in the sort clause, e.g. `{"$hybrid": "query text"}`.
* `$vectorize` field in the sort clause, when using different sorting for vectorize and lexical, e.g. `{"$hybrid": {"$vectorize": "query text"}}`.
+ * `$vectorize` field as the only field in the sort clause, e.g. `{"$vectorize": "query text"}`.
+ * `$lexical` field as the only field in the sort clause, e.g. `{"$lexical": "query text"}`.
* `rerankQuery` field in the options clause, e.g. `{"rerankQuery": "query text"}`.
When specified the `rerankQuery` option takes priority. In all cases the query text must be a non blank text value.
@@ -2364,13 +2368,13 @@ request-errors:
- scope: SORT
code: UNSUPPORTED_FIND_AND_RERANK_SORT
- title: Hybrid sort required by findAndRerank
+ title: Hybrid, vector or lexical sort required by findAndRerank
body: |-
- The command attempted to run findAndRerank without a `$hybrid` sort.
+ The command attempted to run findAndRerank with a sort by document fields, or without a sort.
- The findAndRerank command finds the documents to rerank with a `$hybrid` sort, e.g. `{"$hybrid": "query text"}` or `{"$hybrid": {"$vectorize": "query text", "$lexical": "query text"}}`. Sorting by only one of `$vectorize`, `$vector` or `$lexical`, sorting by document fields, and reranking the documents matched by the filter alone are not supported.
+ The findAndRerank command finds the documents to rerank with a `$hybrid` sort, e.g. `{"$hybrid": "query text"}`, or with a sort by only one of `$vectorize`, `$vector` or `$lexical`, e.g. `{"$vectorize": "query text"}`. Sorting by document fields, and reranking the documents matched by the filter alone are not supported.
- Resend the command with a `$hybrid` sort.
+ Resend the command with a `$hybrid`, `$vectorize`, `$vector` or `$lexical` sort.
- scope: SORT
code: UNSUPPORTED_SORT_FOR_TABLE_DELETE_COMMAND
diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionIntegrationTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionIntegrationTest.java
index 43c7a12bed..a108d3b333 100644
--- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionIntegrationTest.java
+++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionIntegrationTest.java
@@ -12,10 +12,14 @@
import io.stargate.sgv2.jsonapi.exception.SchemaException;
import io.stargate.sgv2.jsonapi.exception.SortException;
import io.stargate.sgv2.jsonapi.testresource.DseTestResource;
+import java.util.stream.Stream;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
/**
* Integration tests for the {@link
@@ -327,6 +331,16 @@ void failOnSortWithNoVectorOrVectorize() {
.body("$", responseIsError())
.body(
"errors[0].errorCode", is(SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.name()));
+
+ // field sort
+ findAndRerankWithSort(
+ collectionName,
+ """
+ {"age": -1}
+ """)
+ .body("$", responseIsError())
+ .body(
+ "errors[0].errorCode", is(SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.name()));
}
/** Each limit option is for one kind of sort, it is rejected with the other kind. */
@@ -400,12 +414,144 @@ void failOnRerankCandidateLimitOutsideBounds() {
"errors[0].message",
containsString("Command field 'rerankCandidateLimit' value 101 not valid"))
.body("errors[0].message", containsString("must be between 1 and 100 (inclusive)"));
+ }
+
+ /**
+ * A sort without $hybrid needs the same collection support as the same sort in $hybrid. A
+ * $lexical sort without $hybrid always needs a lexical index.
+ */
+ @ParameterizedTest(name = "{0}")
+ @MethodSource("sortsWithoutHybridTheCollectionCannotRun")
+ void failOnSortWithoutHybridTheCollectionCannotRun(
+ String collectionName,
+ String collectionSpec,
+ String sort,
+ String errorCode,
+ String errorMessageContains) {
+ var command =
+ """
+ {"findAndRerank": {
+ "sort": %s,
+ "options": {"rerankQuery": "hello", "rerankOn": "content"}
+ }}
+ """
+ .formatted(sort);
+ errorOnNotEnabled(collectionName, collectionSpec, errorCode, errorMessageContains, command);
+ }
+
+ static Stream sortsWithoutHybridTheCollectionCannotRun() {
+ return Stream.of(
+ Arguments.of(
+ "vector_sort_vector_not_enabled",
+ """
+ {
+ "name" : "%s",
+ "options": {}
+ }
+ """,
+ """
+ {"$vector": [0.1, 0.2, 0.3]}
+ """,
+ SortException.Code.UNSUPPORTED_VECTOR_SORT_FOR_COLLECTION.name(),
+ "The collection %s.%s does not have vectors enabled."),
+ Arguments.of(
+ "vectorize_sort_vectorize_not_enabled",
+ """
+ {
+ "name" : "%s",
+ "options": {
+ "vector": {
+ "metric": "cosine",
+ "dimension": 1024
+ }
+ }
+ }
+ """,
+ """
+ {"$vectorize": "hello"}
+ """,
+ SortException.Code.UNSUPPORTED_VECTORIZE_SORT_FOR_COLLECTION.name(),
+ "The collection %s.%s does not have vectorize enabled."),
+ Arguments.of(
+ "lexical_sort_lexical_not_enabled",
+ """
+ {
+ "name" : "%s",
+ "options": {
+ "vector": {
+ "metric": "cosine",
+ "dimension": 1024,
+ "service": {
+ "provider": "openai",
+ "modelName": "text-embedding-3-small"
+ }
+ },
+ "lexical": {
+ "enabled": false
+ }
+ }
+ }
+ """,
+ """
+ {"$lexical": "hello"}
+ """,
+ SchemaException.Code.LEXICAL_NOT_ENABLED_FOR_COLLECTION.name(),
+ "The collection without a lexical index: %s.%s."));
+ }
- // a valid limit passes its checks, then the sort is rejected until GH #2602 and GH #2603
- findAndRerankWithSort(collectionName, sort, "\"rerankCandidateLimit\": 50")
+ /**
+ * A $vector sort without $hybrid has no text to rerank with and no field to rerank on, so the
+ * command must have the rerankQuery and rerankOn options.
+ */
+ @Test
+ void failOnVectorSortWithoutRerankOptions() {
+ var collectionName = "find_rerank_vector_sort_no_options";
+ createCollectionWithCleanup(
+ collectionName,
+ """
+ {
+ "name" : "%s",
+ "options": {
+ "vector": {
+ "metric": "cosine",
+ "dimension": 3
+ },
+ "rerank": {
+ "enabled": true
+ }
+ }
+ }
+ """);
+
+ var command =
+ """
+ {"findAndRerank": {
+ "sort": {"$vector": [0.1, 0.2, 0.3]},
+ "options": %s
+ }}
+ """;
+
+ // no rerankQuery
+ givenHeadersPostJsonThen(
+ keyspaceName,
+ collectionName,
+ command.formatted(
+ """
+ {"rerankOn": "content"}
+ """))
.body("$", responseIsError())
- .body(
- "errors[0].errorCode", is(SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT.name()));
+ .body("errors[0].errorCode", is(RequestException.Code.MISSING_RERANK_QUERY_TEXT.name()));
+
+ // no rerankOn
+ givenHeadersPostJsonThen(
+ keyspaceName,
+ collectionName,
+ command.formatted(
+ """
+ {"rerankQuery": "hello"}
+ """))
+ .body("$", responseIsError())
+ .body("errors[0].errorCode", is(RequestException.Code.MISSING_RERANK_ON.name()));
}
/**
diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionSuccessIntegrationTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionSuccessIntegrationTest.java
index 0d5c1ff380..1e6b9c4070 100644
--- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionSuccessIntegrationTest.java
+++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/FindAndRerankCollectionSuccessIntegrationTest.java
@@ -24,6 +24,8 @@
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.DisabledIfSystemProperty;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
/** Successful collection reranking through the production Nvidia HTTP client and task pipeline. */
@QuarkusIntegrationTest
@@ -283,6 +285,157 @@ void allSixtyCandidatesReachRerankerAcrossBatches() {
.isEqualTo(10));
}
+ @Test
+ void vectorizeSortWithoutHybridSuppliesDefaultQueryAndPassages() {
+ insertDocuments(
+ collectionName,
+ List.of(
+ Map.of("_id", "low", "$vectorize", "score:1 low passage"),
+ Map.of("_id", "high", "$vectorize", "score:5 high passage"),
+ Map.of("_id", "middle", "$vectorize", "score:3 middle passage")));
+
+ findAndRerank(
+ collectionName,
+ Map.of(
+ "sort", Map.of("$vectorize", "default search query"),
+ "options", Map.of("includeScores", true, "includeSortVector", true)))
+ .body("data.documents._id", contains("high", "middle", "low"))
+ .body("status.documentResponses.scores.'$rerank'", contains(5.0f, 3.0f, 1.0f))
+ .body("status.documentResponses.scores.'$vectorRank'", everyItem(notNullValue()))
+ .body("status.documentResponses.scores.'$bm25Rank'", everyItem(nullValue()))
+ .body("status.sortVector", contains(0.25f, 0.25f, 0.25f, 0.25f, 0.25f))
+ .hasNoField("data.nextPageState");
+
+ assertThat(requestedPassages())
+ .containsExactlyInAnyOrder(
+ "score:1 low passage", "score:5 high passage", "score:3 middle passage");
+ assertRequestsUseQuery("default search query");
+ reranker.verify(1, postRequestedFor(urlEqualTo(RerankingTestResource.PATH)));
+ }
+
+ /** The $vector sort is an array of numbers, or the same vector as a $binary vector. */
+ @ParameterizedTest(name = "binary={0}")
+ @ValueSource(booleans = {false, true})
+ void vectorSortWithoutHybridUsesRerankOptions(boolean binary) {
+ insertDocuments(
+ collectionName,
+ List.of(
+ Map.of("_id", "low", "$vector", VECTOR, "content", "score:1 low passage"),
+ Map.of("_id", "high", "$vector", VECTOR, "content", "score:5 high passage")));
+ Object vector =
+ binary
+ ? Map.of(
+ "$binary",
+ generateBase64EncodedBinaryVector(new float[] {0.25f, 0.25f, 0.25f, 0.25f, 0.25f}))
+ : VECTOR;
+
+ findAndRerank(
+ collectionName,
+ Map.of(
+ "sort", Map.of("$vector", vector),
+ "options",
+ Map.of(
+ "rerankQuery",
+ "explicit reranking query",
+ "rerankOn",
+ "content",
+ "includeSortVector",
+ true)))
+ .body("data.documents._id", contains("high", "low"))
+ .body("status.sortVector", contains(0.25f, 0.25f, 0.25f, 0.25f, 0.25f));
+
+ assertThat(requestedPassages())
+ .containsExactlyInAnyOrder("score:1 low passage", "score:5 high passage");
+ assertRequestsUseQuery("explicit reranking query");
+ }
+
+ @Test
+ @DisabledIfSystemProperty(named = TEST_PROP_LEXICAL_DISABLED, matches = "true")
+ void lexicalSortWithoutHybridSuppliesDefaultQueryAndPassages() {
+ var lexicalCollection = collectionName + "_lexical";
+ createRerankingCollection(lexicalCollection, true, true);
+ try {
+ insertDocuments(
+ lexicalCollection,
+ List.of(
+ Map.of("_id", "low", "$lexical", "score:1 cheese low"),
+ Map.of("_id", "high", "$lexical", "score:5 cheese high"),
+ Map.of("_id", "middle", "$lexical", "score:3 cheese middle"),
+ // the lexical read does not find it, so it is not reranked
+ Map.of("_id", "other", "$lexical", "score:9 butter")));
+
+ findAndRerank(
+ lexicalCollection,
+ Map.of(
+ "sort", Map.of("$lexical", "cheese"),
+ "options", Map.of("includeScores", true, "includeSortVector", true)))
+ .body("data.documents._id", contains("high", "middle", "low"))
+ .body("status.documentResponses.scores.'$rerank'", contains(5.0f, 3.0f, 1.0f))
+ .body("status.documentResponses.scores.'$vectorRank'", everyItem(nullValue()))
+ .body("status.documentResponses.scores.'$bm25Rank'", everyItem(notNullValue()))
+ .body("status.sortVector", nullValue());
+
+ assertThat(requestedPassages())
+ .containsExactlyInAnyOrder(
+ "score:1 cheese low", "score:5 cheese high", "score:3 cheese middle");
+ assertRequestsUseQuery("cheese");
+ } finally {
+ deleteCollection(lexicalCollection);
+ }
+ }
+
+ /**
+ * A sort without $hybrid reads the default of 50 documents, or rerankCandidateLimit documents.
+ * The best reranking candidate is beyond the first 50 documents in vector order.
+ */
+ @Test
+ void sortWithoutHybridReadsRerankCandidateLimitDocuments() {
+ var documents =
+ IntStream.range(0, 60)
+ .mapToObj(
+ index ->
+ Map.of(
+ "_id", "candidate" + index,
+ "$vector", List.of((double) index + 1, 0.0, 0.0, 0.0, 0.0),
+ "content", "score:" + index + " unique passage " + index))
+ .toList();
+ insertDocuments(collectionName, documents);
+ var sort = Map.of("$vector", List.of(1.0, 0.0, 0.0, 0.0, 0.0));
+
+ findAndRerank(
+ collectionName,
+ Map.of(
+ "sort",
+ sort,
+ "options",
+ Map.of("rerankQuery", "query", "rerankOn", "content", "limit", 1)))
+ .body("data.documents._id", contains("candidate49"));
+ assertThat(requestedPassages())
+ .containsExactlyInAnyOrderElementsOf(
+ documents.subList(0, 50).stream().map(doc -> (String) doc.get("content")).toList());
+
+ reranker.resetRequests();
+ findAndRerank(
+ collectionName,
+ Map.of(
+ "sort",
+ sort,
+ "options",
+ Map.of(
+ "rerankCandidateLimit",
+ 60,
+ "rerankQuery",
+ "query",
+ "rerankOn",
+ "content",
+ "limit",
+ 1)))
+ .body("data.documents._id", contains("candidate59"));
+ assertThat(requestedPassages())
+ .containsExactlyInAnyOrderElementsOf(
+ documents.stream().map(doc -> (String) doc.get("content")).toList());
+ }
+
private void createRerankingCollection(
String name, boolean rerankEnabled, boolean lexicalEnabled) {
var options = new HashMap();
diff --git a/src/test/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQueryTests.java b/src/test/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQueryTests.java
index 62fbe5c461..319444eef4 100644
--- a/src/test/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQueryTests.java
+++ b/src/test/java/io/stargate/sgv2/jsonapi/service/operation/reranking/RerankingQueryTests.java
@@ -11,11 +11,12 @@ public class RerankingQueryTests {
private static final String VECTORIZE_QUERY = "vetorize-query-" + System.currentTimeMillis();
private static final String OPTIONS_QUERY = "options-query-" + System.currentTimeMillis();
+ private static final String LEXICAL_QUERY = "lexical-query-" + System.currentTimeMillis();
@Test
public void createFromVectorize() {
- var query = RerankingQuery.create(null, VECTORIZE_QUERY);
+ var query = RerankingQuery.forVectorizeSort(null, VECTORIZE_QUERY);
assertThat(query.query()).as("vectorize query used as rerank query").isEqualTo(VECTORIZE_QUERY);
assertThat(query.source()).as("source is vectorize").isEqualTo(RerankingQuery.Source.VECTORIZE);
@@ -25,13 +26,13 @@ public void createFromVectorize() {
@Test
public void createFromOptions() {
- var query = RerankingQuery.create(OPTIONS_QUERY, VECTORIZE_QUERY);
+ var query = RerankingQuery.forVectorizeSort(OPTIONS_QUERY, VECTORIZE_QUERY);
assertThat(query.query())
.as("use the options.rerankQuery when both vectorize and options.rerankQuery are present")
.isEqualTo(OPTIONS_QUERY);
assertThat(query.source()).as("source is options").isEqualTo(RerankingQuery.Source.OPTIONS);
- var query2 = RerankingQuery.create(OPTIONS_QUERY, null);
+ var query2 = RerankingQuery.forVectorizeSort(OPTIONS_QUERY, null);
assertThat(query2.query())
.as("use the options.rerankQuery when no vectorize query is present")
.isEqualTo(OPTIONS_QUERY);
@@ -40,6 +41,27 @@ public void createFromOptions() {
assertMissingQueryText("error when blank options.rerankQuery", "", null);
}
+ @Test
+ public void createFromLexical() {
+
+ var query = RerankingQuery.forLexicalSort(null, LEXICAL_QUERY);
+ assertThat(query.query()).as("lexical text used as rerank query").isEqualTo(LEXICAL_QUERY);
+ assertThat(query.source()).as("source is lexical").isEqualTo(RerankingQuery.Source.LEXICAL);
+
+ var query2 = RerankingQuery.forLexicalSort(" ", LEXICAL_QUERY);
+ assertThat(query2.query())
+ .as("lexical text used as rerank query when options.rerankQuery is blank")
+ .isEqualTo(LEXICAL_QUERY);
+ assertThat(query2.source()).as("source is lexical").isEqualTo(RerankingQuery.Source.LEXICAL);
+
+ var query3 = RerankingQuery.forLexicalSort(OPTIONS_QUERY, LEXICAL_QUERY);
+ assertThat(query3.query())
+ .as(
+ "use the options.rerankQuery when both lexical text and options.rerankQuery are present")
+ .isEqualTo(OPTIONS_QUERY);
+ assertThat(query3.source()).as("source is options").isEqualTo(RerankingQuery.Source.OPTIONS);
+ }
+
@Test
public void createMissingQuery() {
@@ -50,7 +72,7 @@ private void assertMissingQueryText(String context, String rerankQuery, String v
var ex =
assertThrowsExactly(
RequestException.class,
- () -> RerankingQuery.create(rerankQuery, vectorizeText),
+ () -> RerankingQuery.forVectorizeSort(rerankQuery, vectorizeText),
context);
assertThat(ex.code)
@@ -60,7 +82,7 @@ private void assertMissingQueryText(String context, String rerankQuery, String v
@Test
public void testToString() {
- var query = RerankingQuery.create(null, VECTORIZE_QUERY);
+ var query = RerankingQuery.forVectorizeSort(null, VECTORIZE_QUERY);
assertThat(query.toString())
.as("toString is correct")
.isEqualTo("RerankingQuery{query=" + VECTORIZE_QUERY + ", source=VECTORIZE}");
diff --git a/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilderTest.java b/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilderTest.java
index b75cafcdeb..55a63d4f45 100644
--- a/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilderTest.java
+++ b/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilderTest.java
@@ -97,7 +97,7 @@ class FindAndRerankOperationBuilderTest {
DocumentProjector.defaultProjector(),
10);
- /** The builder only reads the filter and the hybridLimits of the command. */
+ /** The builder only reads the filter, the sort and the hybridLimits of the command. */
private static final String EMPTY_COMMAND =
"""
{"findAndRerank": {}}
@@ -213,7 +213,7 @@ static Stream plansAndReads() {
"vectorize, then the vector and lexical legs",
plan(VECTORIZE_STEP, vectorizedLeg(50), lexicalLeg(25)),
List.of(vectorRead(VECTORIZED, 50), lexicalRead(25))),
- // the planner does not make this plan yet, a single $lexical sort will (GH #2602)
+ // the plan of a $lexical sort without $hybrid
Arguments.of("lexical leg", plan(null, lexicalLeg(25)), List.of(lexicalRead(25))));
}
@@ -300,7 +300,8 @@ void keepsExplicitHybridLimitsAtMaximumPageSizeOnCommandContext() throws Excepti
var command =
command(
"""
- {"findAndRerank": {"options": {"hybridLimits": {"$vector": 100, "$lexical": 25}}}}
+ {"findAndRerank": {"sort": {"$hybrid": "cheese"},
+ "options": {"hybridLimits": {"$vector": 100, "$lexical": 25}}}}
""");
build(commandContext, command, plan(null, vectorLeg(100), lexicalLeg(25)));
@@ -310,6 +311,50 @@ void keepsExplicitHybridLimitsAtMaximumPageSizeOnCommandContext() throws Excepti
assertThat(commandContext.getHybridLimits().lexicalLimit()).isEqualTo(25);
}
+ /**
+ * A sort without $hybrid has no hybridLimits, so both limits on the command context are the read
+ * limit of its one leg. The read limits are not the hybridLimits default, so the test fails if
+ * the builder copies the default.
+ */
+ @ParameterizedTest(name = "{0}")
+ @MethodSource("plansOfSortsWithoutHybrid")
+ void setsReadLimitOfOneLegAsHybridLimitsOnCommandContext(
+ String description, String sort, FindAndRerankPlan plan, int readLimit) throws Exception {
+ var commandContext = commandContext();
+ var commandJson =
+ """
+ {"findAndRerank": {"sort": %s}}
+ """
+ .formatted(sort);
+
+ build(commandContext, command(commandJson), plan);
+
+ assertThat(commandContext.getHybridLimits().vectorLimit())
+ .as("%s: vector limit", description)
+ .isEqualTo(readLimit);
+ assertThat(commandContext.getHybridLimits().lexicalLimit())
+ .as("%s: lexical limit", description)
+ .isEqualTo(readLimit);
+ }
+
+ static Stream plansOfSortsWithoutHybrid() {
+ return Stream.of(
+ Arguments.of(
+ "$vector sort",
+ """
+ {"$vector": [0.1, 0.2, 0.3]}
+ """,
+ plan(null, vectorLeg(80)),
+ 80),
+ Arguments.of(
+ "$lexical sort",
+ """
+ {"$lexical": "cows"}
+ """,
+ plan(null, lexicalLeg(30)),
+ 30));
+ }
+
// ===========================================================================================
// Helpers / no more tests below
// ===========================================================================================
diff --git a/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlannerTest.java b/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlannerTest.java
index c53af3d494..88f9e5054d 100644
--- a/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlannerTest.java
+++ b/src/test/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankPlannerTest.java
@@ -2,6 +2,7 @@
import static io.stargate.sgv2.jsonapi.TestConstants.rerankingModelConfig;
import static io.stargate.sgv2.jsonapi.TestConstants.rerankingProvidersConfig;
+import static io.stargate.sgv2.jsonapi.config.constants.DocumentConstants.Fields.LEXICAL_CONTENT_FIELD;
import static io.stargate.sgv2.jsonapi.config.constants.DocumentConstants.Fields.VECTOR_EMBEDDING_TEXT_FIELD;
import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.jupiter.api.Assertions.assertThrowsExactly;
@@ -35,7 +36,6 @@
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;
-import org.junit.jupiter.params.provider.ValueSource;
/**
* Tests for {@link FindAndRerankPlanner}: the legs it plans for each kind of sort, and the error
@@ -65,6 +65,12 @@ class FindAndRerankPlannerTest {
private static final int DEFAULT_READ_LIMIT = RerankingConstants.HybridSearchLimits.DEFAULT;
+ /**
+ * The default rerankCandidateLimit in the config of the cases. It is not the hybridLimits
+ * default, so a case fails if a sort without $hybrid reads with the hybridLimits default.
+ */
+ private static final int DEFAULT_CANDIDATE_LIMIT = 40;
+
// The lines of the errors that name the collection, formatted with the keyspace and collection
private static final String NO_VECTOR_LINE =
"The collection %s.%s does not have vectors enabled.";
@@ -257,7 +263,43 @@ static Stream legCases() {
""",
Collection.VECTOR_LEXICAL,
null,
- List.of(vectorLeg(DEFAULT_READ_LIMIT), lexicalLeg("cows", DEFAULT_READ_LIMIT))));
+ List.of(vectorLeg(DEFAULT_READ_LIMIT), lexicalLeg("cows", DEFAULT_READ_LIMIT))),
+ new LegCase(
+ "sort without $hybrid: $vectorize",
+ """
+ {"$vectorize": "cheese"}
+ """,
+ RERANK_OPTIONS,
+ Collection.VECTORIZE_NO_LEXICAL,
+ "cheese",
+ List.of(vectorizedLeg(DEFAULT_CANDIDATE_LIMIT))),
+ new LegCase(
+ "sort without $hybrid: $vector",
+ """
+ {"$vector": [0.1, 0.2, 0.3]}
+ """,
+ RERANK_OPTIONS,
+ Collection.VECTOR_LEXICAL,
+ null,
+ List.of(vectorLeg(DEFAULT_CANDIDATE_LIMIT))),
+ new LegCase(
+ "sort without $hybrid: $lexical",
+ """
+ {"$lexical": "cows"}
+ """,
+ RERANK_OPTIONS,
+ Collection.VECTORIZE_LEXICAL,
+ null,
+ List.of(lexicalLeg("cows", DEFAULT_CANDIDATE_LIMIT))),
+ new LegCase(
+ "sort without $hybrid: $lexical, collection without vector",
+ """
+ {"$lexical": "cows"}
+ """,
+ RERANK_OPTIONS,
+ Collection.LEXICAL_NO_VECTOR,
+ null,
+ List.of(lexicalLeg("cows", DEFAULT_CANDIDATE_LIMIT))));
}
// ===========================================================================================
@@ -360,65 +402,63 @@ static Stream sortErrorCases() {
}
/**
- * Until GH #2602 and GH #2603, a sort without $hybrid parses but cannot be planned. The error
- * must not tell the user they sent no sort. The collection is not checked for a sort that is
- * rejected, so the error is the same on a collection that cannot run the sort.
+ * Until GH #2603, a sort that needs the filter leg parses but cannot be planned. The error must
+ * not tell the user they sent no sort. A valid rerankCandidateLimit passes its checks, then the
+ * command fails for the sort.
*/
@ParameterizedTest(name = "{0}")
- @MethodSource("singleLegSorts")
- void rejectsSingleLegSort(String description, String sort, Collection collection)
+ @MethodSource("filterLegSorts")
+ void rejectsFilterLegSort(String description, String sort, String options, Collection collection)
throws Exception {
var ex =
assertPlanFails(
description,
- command(sort, RERANK_OPTIONS),
+ command(sort, options),
collection,
SortException.class,
SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT);
assertThat(ex)
.hasMessageContaining(
- "The command attempted to run findAndRerank without a `$hybrid` sort.");
+ "The command attempted to run findAndRerank with a sort by document fields, or without a sort.");
}
- static Stream singleLegSorts() {
+ static Stream filterLegSorts() {
+ var fieldSort =
+ """
+ {"age": -1}
+ """;
return Stream.of(
+ Arguments.of("field sort", fieldSort, RERANK_OPTIONS, Collection.VECTORIZE_LEXICAL),
Arguments.of(
- "vector leg, $vectorize",
+ "two field sorts",
"""
- {"$vectorize": "cheese"}
+ {"age": -1, "name": 1}
""",
+ RERANK_OPTIONS,
Collection.VECTORIZE_LEXICAL),
Arguments.of(
- "vector leg, $vector",
- """
- {"$vector": [0.1, 0.2, 0.3]}
- """,
- Collection.VECTORIZE_LEXICAL),
+ "field sort, collection without vector",
+ fieldSort,
+ RERANK_OPTIONS,
+ Collection.LEXICAL_NO_VECTOR),
Arguments.of(
- "lexical leg",
- """
- {"$lexical": "cows"}
- """,
+ "field sort and a valid rerankCandidateLimit",
+ fieldSort,
+ rerankCandidateLimitOptions("50"),
Collection.VECTORIZE_LEXICAL),
Arguments.of(
- "filter leg",
- """
- {"age": -1}
- """,
+ "no sort and a valid rerankCandidateLimit",
+ null,
+ rerankCandidateLimitOptions("50"),
Collection.VECTORIZE_LEXICAL),
Arguments.of(
- "vector leg, collection without vector",
- """
- {"$vector": [0.1, 0.2, 0.3]}
- """,
- Collection.LEXICAL_NO_VECTOR),
- Arguments.of(
- "lexical leg, collection without lexical index",
+ "sort empty and a valid rerankCandidateLimit",
"""
- {"$lexical": "cows"}
+ {}
""",
- Collection.VECTORIZE_NO_LEXICAL));
+ rerankCandidateLimitOptions("50"),
+ Collection.VECTORIZE_LEXICAL));
}
// ===========================================================================================
@@ -499,6 +539,42 @@ static Stream collectionSupportErrorCases() {
Collection.VECTORIZE_NO_LEXICAL,
SchemaException.class,
SchemaException.Code.LEXICAL_NOT_ENABLED_FOR_COLLECTION,
+ NO_LEXICAL_INDEX_LINE),
+ Arguments.of(
+ "sort without $hybrid: $vectorize, collection without vectorize",
+ """
+ {"$vectorize": "cheese"}
+ """,
+ Collection.VECTOR_LEXICAL,
+ SortException.class,
+ SortException.Code.UNSUPPORTED_VECTORIZE_SORT_FOR_COLLECTION,
+ NO_VECTORIZE_LINE),
+ Arguments.of(
+ "sort without $hybrid: $vectorize, collection without vector",
+ """
+ {"$vectorize": "cheese"}
+ """,
+ Collection.LEXICAL_NO_VECTOR,
+ SortException.class,
+ SortException.Code.UNSUPPORTED_VECTOR_SORT_FOR_COLLECTION,
+ NO_VECTOR_LINE),
+ Arguments.of(
+ "sort without $hybrid: $vector, collection without vector",
+ """
+ {"$vector": [0.1, 0.2, 0.3]}
+ """,
+ Collection.LEXICAL_NO_VECTOR,
+ SortException.class,
+ SortException.Code.UNSUPPORTED_VECTOR_SORT_FOR_COLLECTION,
+ NO_VECTOR_LINE),
+ Arguments.of(
+ "sort without $hybrid: $lexical, collection without a lexical index",
+ """
+ {"$lexical": "cows"}
+ """,
+ Collection.VECTORIZE_NO_LEXICAL,
+ SchemaException.class,
+ SchemaException.Code.LEXICAL_NOT_ENABLED_FOR_COLLECTION,
NO_LEXICAL_INDEX_LINE));
}
@@ -625,6 +701,64 @@ static Stream optionErrorCases() {
ProjectionException.Code.UNSUPPORTED_PROJECTION_PARAM));
}
+ /**
+ * A $vector sort and a field sort have no text to rerank with and no field to rerank on, so the
+ * command must set rerankQuery and rerankOn. The options are checked before the field sort is
+ * rejected.
+ */
+ @ParameterizedTest(name = "{0}")
+ @MethodSource("sortWithoutRerankDefaultsCases")
+ void rejectsSortWithoutRerankDefaultsWhenOptionIsMissing(
+ String description, String sort, String options, RequestException.Code code)
+ throws Exception {
+ assertPlanFails(
+ description,
+ command(sort, options),
+ Collection.VECTORIZE_LEXICAL,
+ RequestException.class,
+ code);
+ }
+
+ static Stream sortWithoutRerankDefaultsCases() {
+ var vectorSort =
+ """
+ {"$vector": [0.1, 0.2, 0.3]}
+ """;
+ var fieldSort =
+ """
+ {"age": -1}
+ """;
+ var noRerankQuery =
+ """
+ {"rerankOn": "body"}
+ """;
+ var noRerankOn =
+ """
+ {"rerankQuery": "q"}
+ """;
+ return Stream.of(
+ Arguments.of(
+ "$vector sort, no rerankQuery",
+ vectorSort,
+ noRerankQuery,
+ RequestException.Code.MISSING_RERANK_QUERY_TEXT),
+ Arguments.of(
+ "$vector sort, no rerankOn",
+ vectorSort,
+ noRerankOn,
+ RequestException.Code.MISSING_RERANK_ON),
+ Arguments.of(
+ "field sort, no rerankQuery",
+ fieldSort,
+ noRerankQuery,
+ RequestException.Code.MISSING_RERANK_QUERY_TEXT),
+ Arguments.of(
+ "field sort, no rerankOn",
+ fieldSort,
+ noRerankOn,
+ RequestException.Code.MISSING_RERANK_ON));
+ }
+
/** hybridLimits outside the bounds in the config, the error names the field and the value. */
@ParameterizedTest(name = "{0}")
@MethodSource("hybridLimitsErrorCases")
@@ -811,52 +945,46 @@ static Stream rerankCandidateLimitErrorCases() {
}
/**
- * A rerankCandidateLimit inside the bounds passes its checks. Until GH #2602 and GH #2603 a
- * single leg sort cannot be planned, so the command then fails for the sort.
+ * A rerankCandidateLimit inside the bounds is the read limit of the one leg of a sort without
+ * $hybrid. When the option is not set the leg reads the default from the config.
*/
@ParameterizedTest(name = "{0}")
@MethodSource("validRerankCandidateLimitCases")
- void rejectsSingleLegSortAfterValidRerankCandidateLimit(
- String description, String sort, String limit) throws Exception {
- assertPlanFails(
- description,
- command(sort, rerankCandidateLimitOptions(limit)),
- Collection.VECTORIZE_LEXICAL,
- SortException.class,
- SortException.Code.UNSUPPORTED_FIND_AND_RERANK_SORT);
+ void usesRerankCandidateLimitAsReadLimitOfSortWithoutHybrid(
+ String description, String sort, String limit, FindAndRerankPlan.RerankLeg leg)
+ throws Exception {
+ var plan =
+ FindAndRerankPlanner.plan(
+ command(sort, rerankCandidateLimitOptions(limit)),
+ commandContext(Collection.VECTORIZE_LEXICAL));
+
+ assertThat(plan.legs()).as(description).containsExactly(leg);
}
static Stream validRerankCandidateLimitCases() {
return Stream.of(
- Arguments.of("at the min of the bounds", SINGLE_LEG_SORT, "1"),
- Arguments.of("inside the bounds", SINGLE_LEG_SORT, "50"),
- Arguments.of("at the max of the bounds", SINGLE_LEG_SORT, "100"),
- Arguments.of("null, the option is not set", SINGLE_LEG_SORT, "null"),
+ Arguments.of("at the min of the bounds", SINGLE_LEG_SORT, "1", vectorizedLeg(1)),
+ Arguments.of("inside the bounds", SINGLE_LEG_SORT, "50", vectorizedLeg(50)),
+ Arguments.of("at the max of the bounds", SINGLE_LEG_SORT, "100", vectorizedLeg(100)),
+ Arguments.of(
+ "null, the option is not set",
+ SINGLE_LEG_SORT,
+ "null",
+ vectorizedLeg(DEFAULT_CANDIDATE_LIMIT)),
Arguments.of(
"$vector sort",
"""
{"$vector": [0.1, 0.2, 0.3]}
""",
- "50"),
+ "50",
+ vectorLeg(50)),
Arguments.of(
"$lexical sort",
"""
{"$lexical": "cows"}
""",
- "50"),
- Arguments.of(
- "field sort",
- """
- {"age": -1}
- """,
- "50"),
- Arguments.of("no sort", null, "50"),
- Arguments.of(
- "sort empty",
- """
- {}
- """,
- "50"));
+ "50",
+ lexicalLeg("cows", 50)));
}
@Test
@@ -878,6 +1006,107 @@ void usesVectorizeTextWhenRerankOptionsAreBlank() throws Exception {
assertThat(plan.rerankStep().passageLocator().path()).isEqualTo(VECTOR_EMBEDDING_TEXT_FIELD);
}
+ /**
+ * The rerank query and the field to rerank on for a sort without $hybrid: the rerankQuery and
+ * rerankOn options when they are not blank, otherwise the text and the field of the sort.
+ */
+ @ParameterizedTest(name = "{0}")
+ @MethodSource("sortWithoutHybridRerankCases")
+ void usesRerankOptionsOrSortTextForSortWithoutHybrid(
+ String description,
+ String sort,
+ String options,
+ Collection collection,
+ String query,
+ RerankingQuery.Source source,
+ String rerankField)
+ throws Exception {
+ var rerankStep =
+ FindAndRerankPlanner.plan(command(sort, options), commandContext(collection)).rerankStep();
+
+ assertThat(rerankStep.rerankingQuery().query()).as("%s: query", description).isEqualTo(query);
+ assertThat(rerankStep.rerankingQuery().source())
+ .as("%s: source of the query", description)
+ .isEqualTo(source);
+ assertThat(rerankStep.passageLocator().path())
+ .as("%s: field to rerank on", description)
+ .isEqualTo(rerankField);
+ }
+
+ static Stream sortWithoutHybridRerankCases() {
+ var vectorizeSort =
+ """
+ {"$vectorize": "cheese"}
+ """;
+ var lexicalSort =
+ """
+ {"$lexical": "cows"}
+ """;
+ var blankOptions =
+ """
+ {"rerankQuery": " ", "rerankOn": " "}
+ """;
+ return Stream.of(
+ Arguments.of(
+ "$vectorize, no options",
+ vectorizeSort,
+ null,
+ Collection.VECTORIZE_NO_LEXICAL,
+ "cheese",
+ RerankingQuery.Source.VECTORIZE,
+ VECTOR_EMBEDDING_TEXT_FIELD),
+ Arguments.of(
+ "$vectorize, blank options",
+ vectorizeSort,
+ blankOptions,
+ Collection.VECTORIZE_NO_LEXICAL,
+ "cheese",
+ RerankingQuery.Source.VECTORIZE,
+ VECTOR_EMBEDDING_TEXT_FIELD),
+ Arguments.of(
+ "$vectorize, options",
+ vectorizeSort,
+ RERANK_OPTIONS,
+ Collection.VECTORIZE_NO_LEXICAL,
+ "q",
+ RerankingQuery.Source.OPTIONS,
+ "body"),
+ Arguments.of(
+ "$lexical, no options",
+ lexicalSort,
+ null,
+ Collection.VECTORIZE_LEXICAL,
+ "cows",
+ RerankingQuery.Source.LEXICAL,
+ LEXICAL_CONTENT_FIELD),
+ Arguments.of(
+ "$lexical, blank options",
+ lexicalSort,
+ blankOptions,
+ Collection.VECTORIZE_LEXICAL,
+ "cows",
+ RerankingQuery.Source.LEXICAL,
+ LEXICAL_CONTENT_FIELD),
+ Arguments.of(
+ "$lexical, options",
+ lexicalSort,
+ RERANK_OPTIONS,
+ Collection.VECTORIZE_LEXICAL,
+ "q",
+ RerankingQuery.Source.OPTIONS,
+ "body"),
+ Arguments.of(
+ "$vector, options",
+ """
+ {"$vector": [0.1, 0.2, 0.3]}
+ """,
+ RERANK_OPTIONS,
+ Collection.VECTOR_LEXICAL,
+ "q",
+ RerankingQuery.Source.OPTIONS,
+ "body"));
+ }
+
// ===========================================================================================
// Error order
// ===========================================================================================
@@ -904,28 +1133,15 @@ void reportsMissingRerankQueryBeforeHybridSortWithNoValue() throws Exception {
}
/**
- * A single leg sort is rejected after the options are checked, the same as a $hybrid sort is
- * planned after them. These commands have no rerank query, they fail for the rerank query. This
- * is also true for $vectorize: the text of a single leg sort is not used as the rerank query.
+ * The same error order for a command with no sort and no options, see GH #2057: no sort needs the
+ * filter leg, which is rejected after the options are checked. The command fails for the rerank
+ * query.
*/
- @ParameterizedTest
- @ValueSource(
- strings = {
- """
- {"$lexical": "cows"}
- """,
- """
- {"$vectorize": "cheese"}
- """
- })
- void reportsMissingRerankQueryBeforeSingleLegSort(String sort) throws Exception {
+ @Test
+ void reportsMissingRerankQueryBeforeNoSort() throws Exception {
assertPlanFails(
- "no rerank query and a single leg sort",
- command(
- sort,
- """
- {"rerankOn": "body"}
- """),
+ "no sort and no options",
+ command(null, null),
Collection.VECTORIZE_LEXICAL,
RequestException.class,
RequestException.Code.MISSING_RERANK_QUERY_TEXT);
@@ -1000,6 +1216,34 @@ void plansVectorWithOptions() throws Exception {
assertThat(plan.includeSortVector()).isTrue();
}
+ /** A $lexical sort runs on a collection without vector and has nothing to vectorize. */
+ @Test
+ void plansLexicalWithDefaults() throws Exception {
+ var plan =
+ FindAndRerankPlanner.plan(
+ command(
+ """
+ {"$lexical": " cows "}
+ """,
+ null),
+ commandContext(Collection.LEXICAL_NO_VECTOR));
+
+ assertThat(plan.vectorizeStep()).isNull();
+ assertThat(plan.legs()).containsExactly(lexicalLeg("cows", DEFAULT_CANDIDATE_LIMIT));
+
+ var rerankStep = plan.rerankStep();
+ assertThat(rerankStep.rerankServiceDef())
+ .isEqualTo(
+ new CollectionRerankDef.RerankServiceDef(
+ "nvidia", TestConstants.RERANK_MODEL, null, null));
+ assertThat(rerankStep.rerankingQuery().query()).isEqualTo("cows");
+ assertThat(rerankStep.rerankingQuery().source()).isEqualTo(RerankingQuery.Source.LEXICAL);
+ assertThat(rerankStep.passageLocator().path()).isEqualTo(LEXICAL_CONTENT_FIELD);
+ assertThat(rerankStep.limit()).isEqualTo(OperationsConfig.DEFAULT_FIND_AND_RERANK_LIMIT);
+ assertThat(plan.includeScores()).isFalse();
+ assertThat(plan.includeSortVector()).isFalse();
+ }
+
// ===========================================================================================
// Helpers / no more tests below
// ===========================================================================================
@@ -1068,8 +1312,9 @@ private CommandContext commandContext(Collection collect
}
/**
- * The config the planner reads, with the default bounds of hybridLimits and rerankCandidateLimit,
- * and the default limit.
+ * The config the planner reads: the default bounds of hybridLimits, the default bounds of
+ * rerankCandidateLimit with {@link #DEFAULT_CANDIDATE_LIMIT} as the default, and the default
+ * limit.
*/
private static CommandConfig commandConfig() {
var hybridLimitBounds =
@@ -1084,7 +1329,7 @@ private static CommandConfig commandConfig() {
.thenReturn(
new IntConfigWithBounds(
RerankingConstants.RerankCandidateLimits.MIN,
- RerankingConstants.RerankCandidateLimits.DEFAULT,
+ DEFAULT_CANDIDATE_LIMIT,
RerankingConstants.RerankCandidateLimits.MAX));
when(operationsConfig.defaultFindAndRerankLimit())
.thenReturn(OperationsConfig.DEFAULT_FIND_AND_RERANK_LIMIT);