Support $vectorSearch against nested embeddings and arrays of embeddings by rozza · Pull Request #2026 · mongodb/mongo-java-driver

rozza · 2026-07-28T08:12:46Z

Also some @Beta annotations clean ups

@Sealed

… of embeddings Add query-time $vectorSearch options for nested (embedded) and arrays-of embeddings: - VectorSearchOptions.parentFilter(Bson): parent/root-level filter for a nested search (the existing filter(Bson) targets the leaf/embedded docs). - VectorSearchOptions.nestedOptions(VectorSearchNestedOptions): the nestedOptions sub-document. - VectorSearchNestedOptions: an extensible @Sealed options type with a typed scoreMode(VectorSearchScoreMode) helper and an option(String, Object) escape hatch, so future server fields are additive. - VectorSearchScoreMode enum (avg/max) for embedded score aggregation. Follows the existing self-rendering immutable options-builder pattern; no path introspection. Index-time nesting needs no new API (SearchIndexModel accepts a raw Bson definition).

@Sealed

The Java VectorSearchOptions, ApproximateVectorSearchOptions and ExactVectorSearchOptions interfaces are stable (@Sealed, not @beta), but their Scala type aliases still carried @beta(Reason.SERVER) left over from when the feature was in beta. Drop the stale annotations so the Scala surface matches the Java classes.

Adding a public Java type/enum under a wrapped package requires a matching Scala wrapper (enforced by ApiAliasAndCompanionSpec): a type alias with stability annotations kept in sync with the Java class, a companion object re-exposing enum constants, and factory objects following each package's convention.

Copilot

Pull request overview

Adds support for $vectorSearch against nested embeddings and arrays of embeddings by introducing new Java model types (VectorSearchNestedOptions, VectorSearchScoreMode) and exposing them through the Scala driver’s mirrored API surface. Also aligns a few stability annotations (@Beta) with their Java counterparts and updates the Scala mirroring enforcement.

Changes:

Add parentFilter and nestedOptions support to VectorSearchOptions, including BSON serialization and unit tests.
Introduce VectorSearchNestedOptions and VectorSearchScoreMode in driver-core, and mirror them in driver-scala (type aliases + companion objects).
Clean up/realign @Beta usage and strengthen Scala mirror enforcement to include enums.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
driver-scala/src/test/scala-2/org/mongodb/scala/ApiAliasAndCompanionSpec.scala	Updates mirror test to include enums when comparing Java vs Scala API surfaces.
driver-scala/src/main/scala/org/mongodb/scala/model/search/VectorSearchScoreMode.scala	Scala companion object re-exposing Java enum constants for term-scope access.
driver-scala/src/main/scala/org/mongodb/scala/model/search/VectorSearchNestedOptions.scala	Scala companion object exposing Java factory method for nested options.
driver-scala/src/main/scala/org/mongodb/scala/model/search/package.scala	Removes stale `@Beta` on vector search option aliases; adds new aliases for nested options + score mode.
driver-scala/AGENTS.md	Documents/enforces Scala mirroring rules and `@Beta` sync expectations.
driver-core/src/test/unit/com/mongodb/client/model/search/VectorSearchOptionsTest.java	Adds unit tests covering `parentFilter` and `nestedOptions` BSON output and null checks.
driver-core/src/test/unit/com/mongodb/client/model/search/VectorSearchNestedOptionsTest.java	Adds unit tests for nested options BSON output, last-write-wins, and immutability behavior.
driver-core/src/main/com/mongodb/client/model/search/VectorSearchScoreMode.java	New public enum defining server string values for score aggregation.
driver-core/src/main/com/mongodb/client/model/search/VectorSearchOptions.java	Adds `parentFilter` and `nestedOptions` APIs with documentation.
driver-core/src/main/com/mongodb/client/model/search/VectorSearchNestedOptions.java	New public options interface with builder methods and static factory.
driver-core/src/main/com/mongodb/client/model/search/VectorSearchNestedConstructibleBson.java	Implements BSON-building for nested options (scoreMode/option).
driver-core/src/main/com/mongodb/client/model/search/VectorSearchConstructibleBson.java	Implements new `parentFilter` / `nestedOptions` methods in the existing constructible options.
driver-core/src/main/com/mongodb/client/model/search/SearchOptions.java	Removes method-level `@Beta({CLIENT, SERVER})` to reflect updated stability semantics.
driver-core/src/main/com/mongodb/client/model/Aggregates.java	Expands `$vectorSearch` Javadoc to describe nested search behavior and the new options.

Comments suppressed due to low confidence (1)

driver-core/src/main/com/mongodb/client/model/Aggregates.java:961

These Javadoc links rely on imports that are otherwise unused in this file. If you remove the unused imports, update the links to use fully-qualified type names so Javadoc generation can still resolve them.

     * {@link VectorSearchOptions#nestedOptions(VectorSearchNestedOptions)} (e.g.
     * {@link VectorSearchNestedOptions#scoreMode(VectorSearchScoreMode)}) to control score aggregation.</p>

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Avoids scanning com.mongodb.client.model.search twice when collecting both Object and Enum subtypes.

rozza · 2026-07-28T10:44:48Z

Added JAVA-6263 - for tracking integration tests.

rozza · 2026-07-29T08:08:37Z

     * @param option The counting option.
     * @return A new {@link SearchOptions}.
     */
-    @Beta({Reason.CLIENT, Reason.SERVER})


Note the whole SearchOptions file is annotated @Beta(Reason.CLIENT)

rozza · 2026-07-29T08:16:48Z

+    }
+
+    @Test
+    void vectorSearchNestedOptionsIsUnmodifiable() {


I'm not 100% sold on the value of this test and the one below - but both SearchOptionsTest and FuzzySearchOptionsTest have the same tests.

rozza · 2026-07-29T08:23:33Z

   * @since 4.11
   */
  @Sealed
-  @Beta(Array(Reason.SERVER))


Keeping Scala types inline with the Java package. I also added a rule to AGENTS.md

So the test class maps directly to the VectorSearchOptions interface it covers, matching the rest of the package.

rozza · 2026-07-29T08:38:48Z

+import static org.junit.jupiter.api.Assertions.assertThrows;

-final class BinaryVectorSearchOptionsTest {
+final class VectorSearchOptionsTest {


Opted to rename so to follow the existing convention of <Name>Test

rozza added 4 commits July 23, 2026 16:33

Remove stale @beta annotation in search options

d70ab35

rozza requested a review from a team as a code owner July 28, 2026 08:12

rozza requested review from Copilot, strogiyotec and vbabanin and removed request for vbabanin July 28, 2026 08:12

Copilot started reviewing on behalf of rozza July 28, 2026 08:13 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/client/model/Aggregates.java

Comment thread driver-scala/src/test/scala-2/org/mongodb/scala/ApiAliasAndCompanionSpec.scala Outdated

Reuse a single Reflections instance in search mirror test

60190f5

Avoids scanning com.mongodb.client.model.search twice when collecting both Object and Enum subtypes.

rozza commented Jul 29, 2026

View reviewed changes

rozza added 2 commits July 29, 2026 09:25

Test last-write-wins for parentFilter and nestedOptions

9756cb0

Merge BinaryVectorSearchOptionsTest into VectorSearchOptionsTest

31784da

So the test class maps directly to the VectorSearchOptions interface it covers, matching the rest of the package.

rozza commented Jul 29, 2026

View reviewed changes

rozza added 2 commits July 29, 2026 09:40

Merge branch 'main' into JAVA-5987

b87b717

Merge branch 'main' into JAVA-5987

2bbe312

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support $vectorSearch against nested embeddings and arrays of embeddings - #2026

Support $vectorSearch against nested embeddings and arrays of embeddings#2026
rozza wants to merge 9 commits into
mongodb:mainfrom
rozza:JAVA-5987

rozza commented Jul 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

rozza commented Jul 28, 2026

Uh oh!

rozza Jul 29, 2026

Uh oh!

rozza Jul 29, 2026

Uh oh!

rozza Jul 29, 2026

Uh oh!

rozza Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

rozza commented Jul 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

rozza commented Jul 28, 2026

Uh oh!

rozza Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

rozza Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

rozza Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

rozza Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants