Metrics flags decide user intent #2598

Current behavior

• While parsing the sort, the code records which features the request used (HYBRID, LEXICAL, VECTOR, ...). These flags exist for metrics tags.
• The builder also uses the LEXICAL flag to make a behavior decision ([FindAndRerankOperationBuilder.java#L484-L486](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java

  Lines 484 to 486 in 02d0423

  	private boolean isExplicitLexicalSort() {
  	return command.sortClause().commandFeatures().contains(CommandFeature.LEXICAL);
  	}

  ), used at [#L199](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java

  Line 199 in 02d0423

  if (isLexicalSort() && isExplicitLexicalSort()) {

  ) and [#L352](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/service/resolver/FindAndRerankOperationBuilder.java

  Line 352 in 02d0423

  if (isExplicitLexicalSort()) {

  )). When the collection has no lexical index:
  • flag set: the user asked for lexical explicitly, so it's an error;
  • no flag: lexical came from $hybrid: "text", so it's skipped silently.
• {} and {"$hybrid": ""} parse to the same values. Only the HYBRID metrics flag tells them apart ([FindAndRerankSortClauseDeserializer.java#L88-L95](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/sort/FindAndRerankSortClauseDeserializer.java

  Lines 88 to 95 in 02d0423

  	case TextNode textNode -> {
  	// using the same text for vectorize and for lexical, no vector
  	var normalizedText = normalizedText(textNode.asText().trim());
  	// NOTE: commandFeatures flags are used to determine user intent, changing
  	// impacts FindAndRerankOperationBuilder
  	yield new FindAndRerankSort(
  	normalizedText, normalizedText, null, CommandFeatures.of(CommandFeature.HYBRID));
  	}

  ) vs [FindAndRerankSort.java#L34-L35](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/sort/FindAndRerankSort.java

  Lines 34 to 35 in 02d0423

  	public static final FindAndRerankSort NO_ARG_SORT =
  	new FindAndRerankSort(null, null, null, CommandFeatures.EMPTY);

  )).
• {} uses a shared constant, NO_ARG_SORT, whose feature set is shared and mutable ([CommandFeatures.java#L17-L18](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/metrics/CommandFeatures.java

  Lines 17 to 18 in 02d0423

  	public static final CommandFeatures EMPTY =
  	new CommandFeatures(EnumSet.noneOf(CommandFeature.class));

  ), [#L54-L57](

  data-api/src/main/java/io/stargate/sgv2/jsonapi/metrics/CommandFeatures.java

  Lines 54 to 57 in 02d0423

  	public void addFeature(CommandFeature commandFeature) {
  	Objects.requireNonNull(commandFeature, "CommandFeature cannot be null");
  	commandFeatures.add(commandFeature);
  	}

  )). Adding a flag to it would leak into every later request.

Why fix it

• The new {"$lexical": "..."} parsing must remember to set the LEXICAL flag, which is easy to miss because it looks metrics-only. If it doesn't, a collection without a lexical index silently returns empty results instead of an error.
• Anyone changing metrics tags could change behavior by accident.
• {} is about to become the filter leg, while {"$hybrid": ""} must stay an error. The two must be told apart reliably, not by a metrics flag.