CSHARP-5717: Typed builders for Atlas indexes

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
+    {
+    }
+}

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; }
     }
 }

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,
+    }
+}

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,
+    }
+}