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);