CSHARP-5717: Introduce basic vector enum types

ajcvickers · ajcvickers · commit 5c2e17e20767 · 2025-09-05T16:13:13.000+01:00
As discussed with Boris, these are used for index building in EF Core. There isn't any strongly typed API for vector indexes in the driver yet, but, when there is, then these enums will be used there as well as being used by EF.
diff --git a/src/MongoDB.Driver/CreateAtlasVectorIndexModel.cs b/src/MongoDB.Driver/CreateAtlasVectorIndexModel.cs
@@ -0,0 +1,216 @@
+/* Copyright 2010-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.
+ */
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Linq.Expressions;
+using MongoDB.Bson;
+using MongoDB.Bson.Serialization;
+
+namespace MongoDB.Driver
+{
+    /// <summary>
+    /// Defines an Atlas vector search index model using strongly-typed C# APIs.
+    /// </summary>
+    public class CreateAtlasVectorIndexModel<TDocument> : CreateSearchIndexModel
+    {
+        private readonly RenderArgs<TDocument> _renderArgs
+            = new(BsonSerializer.LookupSerializer<TDocument>(), BsonSerializer.SerializerRegistry);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class, passing the required
+        /// options for <see cref="VectorSimilarity"/> and number of vector dimensions to the constructor.
+        /// </summary>
+        /// <param name="name">The index name.</param>
+        /// <param name="field">The field containing the vectors to index.</param>
+        /// <param name="similarity">The <see cref="VectorSimilarity"/> to use to search for top K-nearest neighbors.</param>
+        /// <param name="dimensions">Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.</param>
+        /// <param name="filterFields">Fields that may be used as filters in the vector query.</param>
+        public CreateAtlasVectorIndexModel(
+            FieldDefinition<TDocument> field,
+            string name,
+            VectorSimilarity similarity,
+            int dimensions,
+            params FieldDefinition<TDocument>[] filterFields)
+            : base(name, SearchIndexType.VectorSearch)
+        {
+            Field = field;
+            Similarity = similarity;
+            Dimensions = dimensions;
+            FilterFields = filterFields?.ToList() ?? [];
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class, passing the required
+        /// options for <see cref="VectorSimilarity"/> and number of vector dimensions to the constructor.
+        /// </summary>
+        /// <param name="name">The index name.</param>
+        /// <param name="field">An expression pointing to the field containing the vectors to index.</param>
+        /// <param name="similarity">The <see cref="VectorSimilarity"/> to use to search for top K-nearest neighbors.</param>
+        /// <param name="dimensions">Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.</param>
+        /// <param name="filterFields">Expressions pointing to fields that may be used as filters in the vector query.</param>
+        public CreateAtlasVectorIndexModel(
+            Expression<Func<TDocument, object>> field,
+            string name,
+            VectorSimilarity similarity,
+            int dimensions,
+            params Expression<Func<TDocument, object>>[] filterFields)
+            : this(
+                new ExpressionFieldDefinition<TDocument>(field),
+                name,
+                similarity,
+                dimensions,
+                filterFields?.Select(f => (FieldDefinition<TDocument>)new ExpressionFieldDefinition<TDocument>(f)).ToArray())
+        {
+            Similarity = similarity;
+            Dimensions = dimensions;
+        }
+
+        /// <summary>
+        /// The field containing the vectors to index.
+        /// </summary>
+        public FieldDefinition<TDocument> Field { get; }
+
+        /// <summary>
+        /// The <see cref="VectorSimilarity"/> to use to search for top K-nearest neighbors.
+        /// </summary>
+        public VectorSimilarity Similarity { get; }
+
+        /// <summary>
+        /// Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.
+        /// </summary>
+        public int Dimensions { get; }
+
+        /// <summary>
+        /// Fields that may be used as filters in the vector query.
+        /// </summary>
+        public IReadOnlyList<FieldDefinition<TDocument>> FilterFields { get; }
+
+        /// <summary>
+        /// Type of automatic vector quantization for your vectors.
+        /// </summary>
+        public VectorQuantization? Quantization { get; init; }
+
+        /// <summary>
+        /// Maximum number of edges (or connections) that a node can have in the Hierarchical Navigable Small Worlds graph.
+        /// </summary>
+        public int? HnswMaxEdges { get; init; }
+
+        /// <summary>
+        /// Analogous to numCandidates at query-time, this parameter controls the maximum number of nodes to evaluate to find the closest neighbors to connect to a new node.
+        /// </summary>
+        public int? HnswNumEdgeCandidates { get; init; }
+
+        // /// <summary>Paths to properties that may be used as filters on the entity type or its nested types.</summary>
+        // public IReadOnlyList<string> FilterPaths { get; init; }
+
+        /// <inheritdoc/>
+        public override SearchIndexType? Type
+            => SearchIndexType.VectorSearch;
+
+        /// <inheritdoc/>
+        public override BsonDocument Definition
+        {
+            get
+            {
+                if (base.Definition != null)
+                {
+                    return base.Definition;
+                }
+
+                var similarityValue = Similarity == VectorSimilarity.DotProduct
+                    ? "dotProduct" // Because neither "DotProduct" or "dotproduct" are allowed.
+                    : Similarity.ToString().ToLowerInvariant();
+
+                var vectorField = new BsonDocument
+                {
+                    { "type", BsonString.Create("vector") },
+                    { "path", Field.Render(_renderArgs).FieldName },
+                    { "numDimensions", BsonInt32.Create(Dimensions) },
+                    { "similarity", BsonString.Create(similarityValue) },
+                };
+
+                if (Quantization.HasValue)
+                {
+                    vectorField.Add("quantization", BsonString.Create(Quantization.ToString()?.ToLower()));
+                }
+
+                if (HnswMaxEdges != null || HnswNumEdgeCandidates != null)
+                {
+                    var hnswDocument = new BsonDocument
+                    {
+                        { "maxEdges", BsonInt32.Create(HnswMaxEdges ?? 16) },
+                        { "numEdgeCandidates", BsonInt32.Create(HnswNumEdgeCandidates ?? 100) }
+                    };
+                    vectorField.Add("hnswOptions", hnswDocument);
+                }
+
+                var fieldDocuments = new List<BsonDocument> { vectorField };
+
+                if (FilterFields != null)
+                {
+                    foreach (var filterPath in FilterFields)
+                    {
+                        var fieldDocument = new BsonDocument
+                        {
+                            { "type", BsonString.Create("filter") },
+                            { "path", BsonString.Create(filterPath.Render(_renderArgs).FieldName) }
+                        };
+
+                        fieldDocuments.Add(fieldDocument);
+                    }
+                }
+
+                base.Definition = new BsonDocument { { "fields", BsonArray.Create(fieldDocuments) } };
+
+                return base.Definition;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Defines an Atlas vector search index model using strongly-typed C# APIs.
+    /// </summary>
+    public class CreateAtlasVectorIndexModel : CreateAtlasVectorIndexModel<BsonDocument>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class, passing the required
+        /// options for <see cref="VectorSimilarity"/> and number of vector dimensions to the constructor.
+        /// </summary>
+        /// <param name="name">The index name.</param>
+        /// <param name="field">The field containing the vectors to index.</param>
+        /// <param name="similarity">The <see cref="VectorSimilarity"/> to use to search for top K-nearest neighbors.</param>
+        /// <param name="dimensions">Number of vector dimensions that Atlas Vector Search enforces at index-time and query-time.</param>
+        /// <param name="filterFields">Fields that may be used as filters in the vector query.</param>
+        public CreateAtlasVectorIndexModel(
+            FieldDefinition<BsonDocument> field,
+            string name,
+            VectorSimilarity similarity,
+            int dimensions,
+            params FieldDefinition<BsonDocument>[] filterFields)
+            : base(field, name, similarity, dimensions, filterFields)
+        {
+        }
+    }
+
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    public class CreateAtlasSearchIndexModel
+    {
+    }
+}
diff --git a/src/MongoDB.Driver/CreateSearchIndexModel.cs b/src/MongoDB.Driver/CreateSearchIndexModel.cs
@@ -18,40 +18,66 @@
 namespace MongoDB.Driver
 {
     /// <summary>
-    /// Model for creating a search index.
+    /// Defines an Atlas vector search index model using a <see cref="BsonDocument"/> and acts as a base class
+    /// for different types of Atlas index models, including <see cref="CreateAtlasVectorIndexModel"/>
+    /// and <see cref="CreateAtlasSearchIndexModel"/> for strongly-typed Atlas models.
+    /// definition.
     /// </summary>
-    public sealed class CreateSearchIndexModel
+    public class CreateSearchIndexModel
     {
-        /// <summary>Gets the index name.</summary>
-        /// <value>The index name.</value>
-        public string Name { get; }
-
-        /// <summary>Gets the index type.</summary>
-        /// <value>The index type.</value>
-        public SearchIndexType? Type { get; }
-
-        /// <summary>Gets the index definition.</summary>
-        /// <value>The definition.</value>
-        public BsonDocument Definition { get; }
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class, passing the index
+        /// model as a <see cref="BsonDocument"/>.
+        /// </summary>
+        /// <remarks>
+        /// Consider using <see cref="CreateAtlasVectorIndexModel"/> or <see cref="CreateAtlasSearchIndexModel"/> to
+        /// build Atlas indexes without specifying the BSON directly.
+        /// </remarks>
+        /// <param name="name">The name.</param>
+        /// <param name="definition">The index definition.</param>
+        public CreateSearchIndexModel(string name, BsonDocument definition)
+            : this(name, null, definition)
+        {
+        }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class.
+        /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class, passing the index
+        /// model as a <see cref="BsonDocument"/>.
         /// </summary>
+        /// <remarks>
+        /// Consider using <see cref="CreateAtlasVectorIndexModel"/> or <see cref="CreateAtlasSearchIndexModel"/> to
+        /// build Atlas indexes without specifying the BSON directly.
+        /// </remarks>
         /// <param name="name">The name.</param>
-        /// <param name="definition">The definition.</param>
-        public CreateSearchIndexModel(string name, BsonDocument definition) : this(name, null, definition) { }
+        /// <param name="type">The type.</param>
+        /// <param name="definition">The index definition.</param>
+        public CreateSearchIndexModel(string name, SearchIndexType? type, BsonDocument definition)
+            : this(name, type)
+        {
+            Definition = definition;
+        }
 
         /// <summary>
         /// Initializes a new instance of the <see cref="CreateSearchIndexModel"/> class.
         /// </summary>
         /// <param name="name">The name.</param>
         /// <param name="type">The type.</param>
-        /// <param name="definition">The definition.</param>
-        public CreateSearchIndexModel(string name, SearchIndexType? type, BsonDocument definition)
+        protected CreateSearchIndexModel(string name, SearchIndexType? type)
         {
             Name = name;
             Type = type;
-            Definition = definition;
         }
+
+        /// <summary>Gets the index name.</summary>
+        /// <value>The index name.</value>
+        public virtual string Name { get; }
+
+        /// <summary>Gets the index type.</summary>
+        /// <value>The index type.</value>
+        public virtual SearchIndexType? Type { get; }
+
+        /// <summary>Gets the index definition.</summary>
+        /// <value>The definition.</value>
+        public virtual BsonDocument Definition { get; protected set; }
     }
 }
diff --git a/src/MongoDB.Driver/VectorQuantization.cs b/src/MongoDB.Driver/VectorQuantization.cs
@@ -0,0 +1,43 @@
+/* Copyright 2010-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.
+ */
+
+namespace MongoDB.Driver
+{
+    /// <summary>
+    /// Type of automatic vector quantization for your vectors. Use this setting only if your embeddings are float
+    /// or double vectors. See <see href="https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-quantization/">
+    /// Vector Quantization</see> for more information.
+    /// </summary>
+    public enum VectorQuantization
+    {
+        /// <summary>
+        /// Indicates no automatic quantization for the vector embeddings. Use this setting if you have pre-quantized
+        /// vectors for ingestion. If omitted, this is the default value.
+        /// </summary>
+        None,
+
+        /// <summary>
+        /// Indicates scalar quantization, which transforms values to 1 byte integers.
+        /// </summary>
+        Scalar,
+
+        /// <summary>
+        /// Indicates binary quantization, which transforms values to a single bit.
+        /// To use this value, numDimensions must be a multiple of 8.
+        /// If precision is critical, select <see cref="None"/> or <see cref="Scalar"/> instead of <see cref="Binary"/>.
+        /// </summary>
+        Binary,
+    }
+}
diff --git a/src/MongoDB.Driver/VectorSimilarity.cs b/src/MongoDB.Driver/VectorSimilarity.cs
@@ -0,0 +1,40 @@
+/* Copyright 2010-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.
+ */
+
+namespace MongoDB.Driver
+{
+    /// <summary>
+    /// Vector similarity function to use to search for top K-nearest neighbors.
+    /// See <see href="https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-type/">How to Index Fields for
+    /// Vector Search</see> for more information.
+    /// </summary>
+    public enum VectorSimilarity
+    {
+        /// <summary>
+        /// Measures the distance between ends of vectors.
+        /// </summary>
+        Euclidean,
+
+        /// <summary>
+        /// Measures similarity based on the angle between vectors.
+        /// </summary>
+        Cosine,
+
+        /// <summary>
+        /// mMasures similarity like cosine, but takes into account the magnitude of the vector.
+        /// </summary>
+        DotProduct,
+    }
+}
diff --git a/tests/MongoDB.Driver.Tests/Search/AtlasSearchIndexManagmentTests.cs b/tests/MongoDB.Driver.Tests/Search/AtlasSearchIndexManagmentTests.cs
