Add typed builder API for vector search index definitions

* Introduced SearchIndexDefinition sealed interface with factory methods,
* VectorSearchIndexFields (vectorField, filterField, autoEmbedField builders),
* HnswSearchIndexOptions for HNSW-specific parameters, and
* VectorSearchIndexDefinition as the concrete implementation. Updates
* Updated SearchIndexModel javadoc to reference the new builders.

JAVA-6112

Author: rozza

driver-core/src/main/com/mongodb/client/model/HnswSearchIndexOptions.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mongodb.client.model;
+
+import com.mongodb.lang.Nullable;
+import org.bson.BsonDocument;
+import org.bson.BsonInt32;
+import org.bson.codecs.configuration.CodecRegistry;
+import org.bson.conversions.Bson;
+
+/**
+ * Options for the HNSW (Hierarchical Navigable Small World) indexing method in a vector search index.
+ *
+ * <p>This class provides a fluent builder for specifying HNSW-specific parameters when creating
+ * a vector search index with {@code indexingMethod("hnsw")}.</p>
+ *
+ * <p>Since {@link VectorSearchIndexFields.VectorField#hnswOptions(Bson)} accepts any {@link Bson},
+ * a raw {@link org.bson.Document} may also be passed directly for forward compatibility.</p>
+ *
+ * <pre>{@code
+ *    vectorField("embedding")
+ *        .indexingMethod("hnsw")
+ *        .hnswOptions(new HnswSearchIndexOptions().maxEdges(16).numEdgeCandidates(200))
+ * }</pre>
+ *
+ * @see VectorSearchIndexFields.VectorField#hnswOptions(Bson)
+ * @since 5.8
+ */
+public final class HnswSearchIndexOptions implements Bson {
+    @Nullable
+    private Integer maxEdges;
+    @Nullable
+    private Integer numEdgeCandidates;
+
+    /**
+     * Creates a new instance with default settings.
+     *
+     * @since 5.8
+     */
+    public HnswSearchIndexOptions() {
+    }
+
+    /**
+     * Sets the maximum number of connected neighbors for each node in the HNSW graph.
+     *
+     * @param maxEdges the maximum number of edges (connected neighbors)
+     * @return this
+     * @since 5.8
+     */
+    public HnswSearchIndexOptions maxEdges(final int maxEdges) {
+        this.maxEdges = maxEdges;
+        return this;
+    }
+
+    /**
+     * Sets the number of nearest neighbor candidates to consider when building the HNSW graph.
+     *
+     * @param numEdgeCandidates the number of nearest neighbor candidates
+     * @return this
+     * @since 5.8
+     */
+    public HnswSearchIndexOptions numEdgeCandidates(final int numEdgeCandidates) {
+        this.numEdgeCandidates = numEdgeCandidates;
+        return this;
+    }
+
+    @Override
+    public <TDocument> BsonDocument toBsonDocument(final Class<TDocument> documentClass, final CodecRegistry codecRegistry) {
+        BsonDocument doc = new BsonDocument();
+        if (maxEdges != null) {
+            doc.append("maxEdges", new BsonInt32(maxEdges));
+        }
+        if (numEdgeCandidates != null) {
+            doc.append("numEdgeCandidates", new BsonInt32(numEdgeCandidates));
+        }
+        return doc;
+    }
+
+    @Override
+    public String toString() {
+        return "HnswSearchIndexOptions{"
+                + "maxEdges=" + maxEdges
+                + ", numEdgeCandidates=" + numEdgeCandidates
+                + '}';
+    }
+}

driver-core/src/main/com/mongodb/client/model/SearchIndexDefinition.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mongodb.client.model;
+
+import com.mongodb.annotations.Sealed;
+import org.bson.conversions.Bson;
+
+import java.util.List;
+
+import static com.mongodb.assertions.Assertions.notNull;
+import static java.util.Arrays.asList;
+
+/**
+ * A definition for an Atlas Search index.
+ *
+ * <p>This interface provides factory methods for creating search index definitions
+ * that can be passed to {@link SearchIndexModel}.</p>
+ *
+ * @see SearchIndexModel
+ * @see VectorSearchIndexDefinition
+ * @since 5.8
+ */
+@Sealed
+public interface SearchIndexDefinition extends Bson {
+
+    /**
+     * Creates a vector search index definition with the specified fields.
+     *
+     * <p>The resulting definition produces a document of the form {@code {"fields": [...]}},
+     * suitable for use with {@link SearchIndexType#vectorSearch()}.</p>
+     *
+     * @param fields the fields for the vector search index. Each field should be created using
+     *               {@link VectorSearchIndexFields} factory methods, or may be a raw {@link Bson} document.
+     * @return a new {@link VectorSearchIndexDefinition}
+     * @see VectorSearchIndexFields#vectorField(String)
+     * @see VectorSearchIndexFields#filterField(String)
+     * @see VectorSearchIndexFields#autoEmbedField(String)
+     * @since 5.8
+     */
+    static VectorSearchIndexDefinition vectorSearch(final Bson... fields) {
+        notNull("fields", fields);
+        return vectorSearch(asList(fields));
+    }
+
+    /**
+     * Creates a vector search index definition with the specified fields.
+     *
+     * <p>The resulting definition produces a document of the form {@code {"fields": [...]}},
+     * suitable for use with {@link SearchIndexType#vectorSearch()}.</p>
+     *
+     * @param fields the fields for the vector search index. Each field should be created using
+     *               {@link VectorSearchIndexFields} factory methods, or may be a raw {@link Bson} document.
+     * @return a new {@link VectorSearchIndexDefinition}
+     * @see VectorSearchIndexFields#vectorField(String)
+     * @see VectorSearchIndexFields#filterField(String)
+     * @see VectorSearchIndexFields#autoEmbedField(String)
+     * @since 5.8
+     */
+    static VectorSearchIndexDefinition vectorSearch(final List<? extends Bson> fields) {
+        notNull("fields", fields);
+        return new VectorSearchIndexDefinition(fields);
+    }
+}

driver-core/src/main/com/mongodb/client/model/SearchIndexModel.java

@@ -24,6 +24,12 @@
 /**
  * A model describing the creation of a single Atlas Search index.
  *
+ * <p>The {@code definition} parameter accepts any {@link org.bson.conversions.Bson} instance.
+ * For vector search indexes, use the builders provided by {@link SearchIndexDefinition#vectorSearch(Bson...)}
+ * and {@link VectorSearchIndexFields} to construct the definition.</p>
+ *
+ * @see SearchIndexDefinition
+ * @see VectorSearchIndexFields
  * @since 4.11
  * @mongodb.server.release 6.0
  */
@@ -42,6 +48,7 @@ public final class SearchIndexModel {
      * will be used to create the search index.</p>
      *
      * @param definition the search index mapping definition.
+     * @see SearchIndexDefinition#vectorSearch(Bson...)
      */
     public SearchIndexModel(final Bson definition) {
         this(null, definition, null);
@@ -52,6 +59,7 @@ public SearchIndexModel(final Bson definition) {
      *
      * @param name       the search index name.
      * @param definition the search index mapping definition.
+     * @see SearchIndexDefinition#vectorSearch(Bson...)
      */
     public SearchIndexModel(final String name, final Bson definition) {
         this(name, definition, null);
@@ -63,6 +71,7 @@ public SearchIndexModel(final String name, final Bson definition) {
      * @param name       the search index name.
      * @param definition the search index mapping definition.
      * @param type       the search index type.
+     * @see SearchIndexDefinition#vectorSearch(Bson...)
      * @since 5.2
      */
     public SearchIndexModel(@Nullable final String name, final Bson definition, @Nullable final SearchIndexType type) {

driver-core/src/main/com/mongodb/client/model/VectorSearchIndexDefinition.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mongodb.client.model;
+
+import org.bson.BsonArray;
+import org.bson.BsonDocument;
+import org.bson.codecs.configuration.CodecRegistry;
+import org.bson.conversions.Bson;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * A vector search index definition, producing a document of the form {@code {"fields": [...]}}.
+ *
+ * <p>Instances are created via {@link SearchIndexDefinition#vectorSearch(Bson...)}.</p>
+ *
+ * @see SearchIndexDefinition
+ * @see SearchIndexType#vectorSearch()
+ * @since 5.8
+ */
+public final class VectorSearchIndexDefinition implements SearchIndexDefinition {
+    private final List<? extends Bson> fields;
+
+    VectorSearchIndexDefinition(final List<? extends Bson> fields) {
+        this.fields = new ArrayList<>(fields);
+    }
+
+    @Override
+    public <TDocument> BsonDocument toBsonDocument(final Class<TDocument> documentClass, final CodecRegistry codecRegistry) {
+        BsonArray fieldArray = new BsonArray();
+        for (Bson field : fields) {
+            fieldArray.add(field.toBsonDocument(documentClass, codecRegistry));
+        }
+        return new BsonDocument("fields", fieldArray);
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        VectorSearchIndexDefinition that = (VectorSearchIndexDefinition) o;
+        return Objects.equals(fields, that.fields);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(fields);
+    }
+
+    @Override
+    public String toString() {
+        return "VectorSearchIndexDefinition{"
+                + "fields=" + fields
+                + '}';
+    }
+}