JAVA-5988

[strogiyotec]

JAVA-5988

[rozza]

Its looking good, add some unit tests to AggregatesTest, so that the shape of the produced Bson is as expected. So there is some test coverage for now.

Also don't forget to add the license headers to the new files!

[strogiyotec]

Its looking good, add some unit tests to AggregatesTest, so that the shape of the produced Bson is as expected. So there is some test coverage for now.

Also don't forget to add the license headers to the new files!

hey @rozza thanks for your feedback

1. I added license headers
2. added a unit test
3. fixed a few minor things to make checkstyle to pass

[vbabanin]

Not sure if this was considered already, but I wanted to propose we consider an alternative: model the auto-embedding query as a typed object instead of accepting raw Bson.

Why raw Bson is tricky here
Using raw Bson for the query is “stringly-typed”:

• typos / wrong types / wrong structure compile and fail at runtime .
• it’s not very discoverable (users would have to read the docs to learn the required document shape).

//What goes in `???`? User must read documentation.  IDE provides no help.
vectorSearch(path, ???, index, limit, options)

Also, adding model as a separate parameter feels easy to mix up since model and index are both String.

This matches existing patterns in the driver
The alternative proposed below follows patterns already in the driver's API:

• Static factory creates a variant:

public interface SearchPath extends Bson {
    static FieldSearchPath fieldPath(final String path) {
        return new SearchConstructibleBson(new BsonDocument(SEARCH_PATH_VALUE_KEY, new BsonString(path)));
    }

• Optional fluent config (e.g., FieldSearchPath.multi(...))

public interface FieldSearchPath extends SearchPath {
    FieldSearchPath multi(String analyzerName);  // optional
}

// usage:
fieldPath("plot") 
fieldPath("plot").multi("english")     // with optional analyzer

The equivalent here would be:
VectorSearchQuery.textQuery("...") (factory).model("...") (optional fluent config)

API surface:

a typed query abstraction:

 @Beta(Reason.SERVER)
 public interface VectorSearchQuery extends Bson {
     static TextVectorSearchQuery textQuery(final String text) {
         return new TextVectorSearchQueryImpl(notNull("text", text), null);
     }
 }

 @Beta(Reason.SERVER)
 public interface TextVectorSearchQuery extends VectorSearchQuery {
     TextVectorSearchQuery model(String modelName);
 }

Implementation remains package-private and immutable: (expandable)

final class TextVectorSearchQueryImpl implements TextVectorSearchQuery {
    private final String text;
    private final @Nullable String model;

    TextVectorSearchQueryImpl(String text, @Nullable String model) { ... }

    @Override public TextVectorSearchQuery model(String modelName) {
        return new TextVectorSearchQueryImpl(text, notNull("modelName", modelName));
    }

    @Override public @Nullable String getModel() { return model; }

    @Override public <TDocument> BsonDocument toBsonDocument(Class<TDocument> dc, CodecRegistry cr) {
        return new Document("text", text).toBsonDocument(dc, cr);
    }
}

Then Aggregate methods becomes:

@Beta(Reason.SERVER)
public static Bson vectorSearch(
    FieldSearchPath path,
    VectorSearchQuery query,
    String index,
    long limit,
    VectorSearchOptions options
) { ... }

The usage of the API is type safe:

vectorSearch(fieldPath("plot"),
    textQuery("movies about cars").model("voyage-4-large"),
    "my_index",
    10,
    options
)

API Evolution Support (future modalities):

This approach can evolve without changing the Aggregates.vectorSearch(...) signature by adding new factories and subtypes later (e.g. imageQuery(...), audioQuery(...)) with modality-specific options.

• add VectorSearchQuery.imageQuery(...) returning ImageVectorSearchQuery
• add image-specific fluent methods on that subtype (resolution(...), etc.)

VectorSearchQuery (interface factory)
  - textQuery(String) -> TextVectorSearchQuery
  - (future) imageQuery(BsonBinary) -> ImageVectorSearchQuery
  - (future) audioQuery(BsonBinary) -> AudioVectorSearchQuery

TextVectorSearchQuery (current)
  - model(String)

ImageVectorSearchQuery (future)
  - model(String)
  - resolution(int, int)

AudioVectorSearchQuery (future)
  - model(String)
  - sampleRate(int)

This keeps the stage discoverable, compile-time safe, and provides a potential path for future query modalities. What do you think?

P.S : the server may ship modalities incrementally (e.g., text could reach GA first, with image/audio staying Beta).

[strogiyotec]

I updated the PR to include fluent builders thanks Slav really good feedback

[vbabanin]

Could it also be used in Enterprise Edition?

[strogiyotec]

only in community edition right now, but I believe in the future it will be extended to atlas too

[strogiyotec]

for now I added this specific Text interface because with plain Vector we won't have an access to get model without casting

[vbabanin]

I see why TextVectorSearchQuery is used in the signature today as it’s the only way to access getModel() without a cast. However, I think using VectorSearchQuery as parameter helps discoverability. We could keep VectorSearchQuery as the parameter type and casting to AbstractVectorSearchQuery inside the stage builder.

If users see this signature:

public static Bson vectorSearch(
    FieldSearchPath path,
    TextVectorSearchQuery query,
    String index, ...)

a natural question is: “How do I create a TextVectorSearchQuery?” If they type TextVectorSearchQuery in the IDE to look for clues (method factories in this case), none will show up (since the factory lives on VectorSearchQuery). Using VectorSearchQuery keeps construction discoverable via VectorSearchQuery.textQuery(...).

Internally, getModel() could be accessed via the internal abstract base, similar to the approach used in the Client Bulk Write internal models:
AbstractClientDeleteModel.java#L23-L39

Suggested change: commit

[vbabanin]

[nit]

Suggested change

	* If not specified, the model configured in the vector search index definition will be used.
	* If not specified, the model configured in the vector {@link SearchIndexModel} definition will be used.

Note: requires an import.

[vbabanin]

I see why TextVectorSearchQuery is used in the signature today as it’s the only way to access getModel() without a cast. However, I think using VectorSearchQuery as parameter helps discoverability. We could keep VectorSearchQuery as the parameter type and casting to AbstractVectorSearchQuery inside the stage builder.

If users see this signature:

public static Bson vectorSearch(
    FieldSearchPath path,
    TextVectorSearchQuery query,
    String index, ...)

a natural question is: “How do I create a TextVectorSearchQuery?” If they type TextVectorSearchQuery in the IDE to look for clues (method factories in this case), none will show up (since the factory lives on VectorSearchQuery). Using VectorSearchQuery keeps construction discoverable via VectorSearchQuery.textQuery(...).

Internally, getModel() could be accessed via the internal abstract base, similar to the approach used in the Client Bulk Write internal models:
AbstractClientDeleteModel.java#L23-L39

Suggested change: commit

[vbabanin]

Approved, given functional tests aren’t currently run in CI; we should enable them in a follow-up PR under JAVA-6059.

@rozza is out, concerns should be addressed