Add BinaryVector and VectorSearchQuery vectorSearch overloads to Scala driver (#1986)

rozza · vbabanin · web-flow · commit f3bbdb2701b8 · 2026-05-28T17:03:05.000+01:00
* Add BinaryVector and VectorSearchQuery vectorSearch overloads to Scala driver The Scala Aggregates wrapper only exposed the `Iterable[Double]` overload of vectorSearch. This adds the `BinaryVector` (since 5.3) and `VectorSearchQuery` auto-embedding (since 5.7) overloads. Changes the existing overload's parameter from `Iterable[java.lang.Double]` to `Iterable[Double]` to resolve Scala type inference ambiguity when multiple overloads are present. Also fixes scaladoc warnings for unresolvable cross-module Java type links. JAVA-5699 --------- Co-authored-by: Viacheslav Babanin <frest0512@gmail.com>
diff --git a/driver-scala/src/main/scala/org/mongodb/scala/model/Aggregates.scala b/driver-scala/src/main/scala/org/mongodb/scala/model/Aggregates.scala
@@ -18,7 +18,8 @@ package org.mongodb.scala.model
 
 import com.mongodb.annotations.{ Beta, Reason }
 import com.mongodb.client.model.fill.FillOutputField
-import com.mongodb.client.model.search.FieldSearchPath
+import com.mongodb.client.model.search.{ FieldSearchPath, VectorSearchQuery }
+import org.bson.BinaryVector
 
 import scala.collection.JavaConverters._
 import com.mongodb.client.model.{ Aggregates => JAggregates }
@@ -740,12 +741,71 @@ object Aggregates {
    */
   def vectorSearch(
       path: FieldSearchPath,
-      queryVector: Iterable[java.lang.Double],
+      queryVector: Iterable[Double],
       index: String,
       limit: Long,
       options: VectorSearchOptions
   ): Bson =
-    JAggregates.vectorSearch(path, queryVector.asJava, index, limit, options)
+    JAggregates.vectorSearch(
+      path,
+      queryVector.asInstanceOf[Iterable[java.lang.Double]].asJava,
+      index,
+      limit,
+      options
+    )
+
+  /**
+   * Creates a `\$vectorSearch` pipeline stage supported by MongoDB Atlas.
+   * You may use the `\$meta: "vectorSearchScore"` expression, e.g., via [[Projections.metaVectorSearchScore]],
+   * to extract the relevance score assigned to each found document.
+   *
+   * @param path The field to be searched.
+   * @param queryVector The `BinaryVector` query vector. The number of dimensions must match that of the `index`.
+   * @param index The name of the index to use.
+   * @param limit The limit on the number of documents produced by the pipeline stage.
+   * @param options Optional `\$vectorSearch` pipeline stage fields.
+   * @return The `\$vectorSearch` pipeline stage.
+   * @see [[https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ \$vectorSearch]]
+   * @note Requires MongoDB 6.0.10 or greater
+   * @since 5.8
+   */
+  def vectorSearch(
+      path: FieldSearchPath,
+      queryVector: BinaryVector,
+      index: String,
+      limit: Long,
+      options: VectorSearchOptions
+  ): Bson =
+    JAggregates.vectorSearch(path, queryVector, index, limit, options)
+
+  /**
+   * Creates a `\$vectorSearch` pipeline stage supported by MongoDB Atlas with automated embedding.
+   * You may use the `\$meta: "vectorSearchScore"` expression, e.g., via [[Projections.metaVectorSearchScore]],
+   * to extract the relevance score assigned to each found document.
+   *
+   * This overload is used for auto-embedding in Atlas. The server will automatically generate embeddings
+   * for the query using the model specified in the index definition or via
+   * `TextVectorSearchQuery.model`.
+   *
+   * @param path The field to be searched.
+   * @param query The query specification, typically created via `VectorSearchQuery.textQuery`.
+   * @param index The name of the index to use.
+   * @param limit The limit on the number of documents produced by the pipeline stage.
+   * @param options Optional `\$vectorSearch` pipeline stage fields.
+   * @return The `\$vectorSearch` pipeline stage.
+   * @see [[https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ \$vectorSearch]]
+   * @note Requires MongoDB 6.0.10 or greater
+   * @since 5.8
+   */
+  @Beta(Array(Reason.SERVER))
+  def vectorSearch(
+      path: FieldSearchPath,
+      query: VectorSearchQuery,
+      index: String,
+      limit: Long,
+      options: VectorSearchOptions
+  ): Bson =
+    JAggregates.vectorSearch(path, query, index, limit, options)
 
   /**
    * Creates a `\$rerank` pipeline stage supported by MongoDB Atlas.
diff --git a/driver-scala/src/main/scala/org/mongodb/scala/model/package.scala b/driver-scala/src/main/scala/org/mongodb/scala/model/package.scala
@@ -536,7 +536,7 @@ package object model {
      * Creates a vector field definition for a vector search index.
      *
      * @param path the field path in the document
-     * @return a new [[com.mongodb.client.model.VectorSearchIndexFields.VectorField]]
+     * @return a new `VectorSearchIndexFields.VectorField`
      */
     def vectorField(path: String): com.mongodb.client.model.VectorSearchIndexFields.VectorField =
       com.mongodb.client.model.VectorSearchIndexFields.vectorField(path)
@@ -545,7 +545,7 @@ package object model {
      * Creates a filter field definition for a vector search index.
      *
      * @param path the field path in the document
-     * @return a new [[com.mongodb.client.model.VectorSearchIndexFields.FilterField]]
+     * @return a new `VectorSearchIndexFields.FilterField`
      */
     def filterField(path: String): com.mongodb.client.model.VectorSearchIndexFields.FilterField =
       com.mongodb.client.model.VectorSearchIndexFields.filterField(path)
@@ -554,7 +554,7 @@ package object model {
      * Creates an auto-embed field definition for a vector search index.
      *
      * @param path the field path in the document containing the content to embed
-     * @return a new [[com.mongodb.client.model.VectorSearchIndexFields.AutoEmbedField]]
+     * @return a new `VectorSearchIndexFields.AutoEmbedField`
      */
     def autoEmbedField(path: String): com.mongodb.client.model.VectorSearchIndexFields.AutoEmbedField =
       com.mongodb.client.model.VectorSearchIndexFields.autoEmbedField(path)
diff --git a/driver-scala/src/test/scala/org/mongodb/scala/model/AggregatesSpec.scala b/driver-scala/src/test/scala/org/mongodb/scala/model/AggregatesSpec.scala
@@ -37,7 +37,10 @@ import org.mongodb.scala.model.geojson.{ Point, Position }
 import org.mongodb.scala.model.search.SearchCount.total
 import org.mongodb.scala.model.search.SearchFacet.stringFacet
 import org.mongodb.scala.model.search.SearchHighlight.paths
+import com.mongodb.client.model.{ Aggregates => JAggregates }
 import com.mongodb.client.model.RerankQuery
+import com.mongodb.client.model.search.VectorSearchQuery
+import org.bson.BinaryVector
 import org.mongodb.scala.model.search.SearchCollector
 import org.mongodb.scala.model.search.SearchOperator.exists
 import org.mongodb.scala.model.search.SearchOptions.searchOptions
@@ -817,6 +820,50 @@ class AggregatesSpec extends BaseSpec {
     )
   }
 
+  it should "render $vectorSearch with BinaryVector" in {
+    toBson(
+      Aggregates.vectorSearch(
+        fieldPath("fieldName"),
+        BinaryVector.int8Vector(Array[Byte](0, 1, 2, 3, 4)),
+        "indexName",
+        1,
+        approximateVectorSearchOptions(2)
+      )
+    ) should equal(
+      toBson(
+        JAggregates.vectorSearch(
+          fieldPath("fieldName"),
+          BinaryVector.int8Vector(Array[Byte](0, 1, 2, 3, 4)),
+          "indexName",
+          1,
+          approximateVectorSearchOptions(2)
+        )
+      )
+    )
+  }
+
+  it should "render $vectorSearch with VectorSearchQuery" in {
+    toBson(
+      Aggregates.vectorSearch(
+        fieldPath("fieldName"),
+        VectorSearchQuery.textQuery("sample text"),
+        "indexName",
+        1,
+        approximateVectorSearchOptions(2)
+      )
+    ) should equal(
+      toBson(
+        JAggregates.vectorSearch(
+          fieldPath("fieldName"),
+          VectorSearchQuery.textQuery("sample text"),
+          "indexName",
+          1,
+          approximateVectorSearchOptions(2)
+        )
+      )
+    )
+  }
+
   it should "render $rerank with single path" in {
     toBson(
       Aggregates.rerank(
