CSHARP-5763: Auto-embedding for vector search

src/MongoDB.Driver/CreateAutoEmbeddingVectorSearchIndexModel.cs

@@ -0,0 +1,97 @@
+/* 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;
+
+namespace MongoDB.Driver;
+
+/// <summary>
+/// Defines a vector index model for an auto-embedding vector index using strongly-typed C# APIs.
+/// </summary>
+public sealed class CreateAutoEmbeddingVectorSearchIndexModel<TDocument> : CreateVectorSearchIndexModelBase<TDocument>
+{
+    /// <summary>
+    /// The name of the embedding model to use, such as "voyage-4", "voyage-4-large", etc.
+    /// </summary>
+    public string AutoEmbeddingModelName { get; }
+
+    /// <summary>
+    /// Indicates the type of data that will be embedded for an auto-embedding index.
+    /// </summary>
+    public VectorEmbeddingModality Modality { get; init; } = VectorEmbeddingModality.Text;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> for a vector index
+    /// that will automatically create embeddings from a given field in the document. The embedding model to use must
+    /// be passed to this constructor.
+    /// </summary>
+    /// <param name="name">The index name.</param>
+    /// <param name="field">The field containing the vectors to index.</param>
+    /// <param name="embeddingModelName">The name of the embedding model to use, such as "voyage-4", "voyage-4-large", etc.</param>
+    /// <param name="filterFields">Fields that may be used as filters in the vector query.</param>
+    public CreateAutoEmbeddingVectorSearchIndexModel(
+        FieldDefinition<TDocument> field,
+        string name,
+        string embeddingModelName,
+        params FieldDefinition<TDocument>[] filterFields)
+        : base(field, name, filterFields)
+    {
+        AutoEmbeddingModelName = embeddingModelName;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> for a vector index
+    /// that will automatically create embeddings from a given field in the document. The embedding model to use must
+    /// be passed to this 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="embeddingModelName">The name of the embedding model to use, such as "voyage-4", "voyage-4-large", etc.</param>
+    /// <param name="filterFields">Expressions pointing to fields that may be used as filters in the vector query.</param>
+    public CreateAutoEmbeddingVectorSearchIndexModel(
+        Expression<Func<TDocument, object>> field,
+        string name,
+        string embeddingModelName,
+        params Expression<Func<TDocument, object>>[] filterFields)
+        : this(
+            new ExpressionFieldDefinition<TDocument>(field),
+            name,
+            embeddingModelName,
+            filterFields?
+                .Select(f => (FieldDefinition<TDocument>)new ExpressionFieldDefinition<TDocument>(f))
+                .ToArray())
+    {
+    }
+
+    /// <inheritdoc/>
+    internal override BsonDocument Render(RenderArgs<TDocument> renderArgs)
+    {
+        var vectorField = new BsonDocument
+        {
+            { "type", "autoEmbed" },
+            { "path", Field.Render(renderArgs).FieldName },
+            { "modality", Modality.ToString().ToLowerInvariant() },
+            { "model", AutoEmbeddingModelName },
+        };
+
+        var fieldDocuments = new List<BsonDocument> { vectorField };
+        RenderFilterFields(renderArgs, fieldDocuments);
+        return new BsonDocument { { "fields", new BsonArray(fieldDocuments) } };
+    }
+}

src/MongoDB.Driver/CreateVectorSearchIndexModel.cs

@@ -22,15 +22,10 @@
 namespace MongoDB.Driver;
 
 /// <summary>
-/// Defines a vector index model using strongly-typed C# APIs.
+/// Defines a vector index model for pre-embedded vector indexes using strongly-typed C# APIs.
 /// </summary>
-public sealed class CreateVectorSearchIndexModel<TDocument> : CreateSearchIndexModel
+public sealed class CreateVectorSearchIndexModel<TDocument> : CreateVectorSearchIndexModelBase<TDocument>
 {
-    /// <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>
@@ -41,11 +36,6 @@ public sealed class CreateVectorSearchIndexModel<TDocument> : CreateSearchIndexM
     /// </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>
@@ -57,13 +47,15 @@ public sealed class CreateVectorSearchIndexModel<TDocument> : CreateSearchIndexM
     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.
+    /// 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>
-    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> class, passing the
-    /// required options for <see cref="VectorSimilarity"/> and the number of vector dimensions to the constructor.
+    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> class for a vector
+    /// index where the vector embeddings are created manually. The required options for <see cref="VectorSimilarity"/>
+    /// and the number of vector dimensions are passed to the constructor.
     /// </summary>
     /// <param name="name">The index name.</param>
     /// <param name="field">The field containing the vectors to index.</param>
@@ -76,17 +68,16 @@ public CreateVectorSearchIndexModel(
         VectorSimilarity similarity,
         int dimensions,
         params FieldDefinition<TDocument>[] filterFields)
-        : base(name, SearchIndexType.VectorSearch)
+        : base(field, name, filterFields)
     {
-        Field = field;
         Similarity = similarity;
         Dimensions = dimensions;
-        FilterFields = filterFields?.ToList() ?? [];
     }
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> class, passing the
-    /// required options for <see cref="VectorSimilarity"/> and the number of vector dimensions to the constructor.
+    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> class for a vector
+    /// index where the vector embeddings are created manually. The required options for <see cref="VectorSimilarity"/>
+    /// and the number of vector dimensions are passed 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>
@@ -110,56 +101,34 @@ public CreateVectorSearchIndexModel(
     {
     }
 
-    /// <summary>
-    /// Renders the index model to a <see cref="BsonDocument"/>.
-    /// </summary>
-    /// <param name="renderArgs">The render arguments.</param>
-    /// <returns>A <see cref="BsonDocument" />.</returns>
-    public BsonDocument Render(RenderArgs<TDocument> renderArgs)
+    /// <inheritdoc/>
+    internal override BsonDocument Render(RenderArgs<TDocument> renderArgs)
     {
         var similarityValue = Similarity == VectorSimilarity.DotProduct
             ? "dotProduct" // Because neither "DotProduct" or "dotproduct" are allowed.
             : Similarity.ToString().ToLowerInvariant();
 
         var vectorField = new BsonDocument
         {
-            { "type", BsonString.Create("vector") },
+            { "type", "vector" },
             { "path", Field.Render(renderArgs).FieldName },
-            { "numDimensions", BsonInt32.Create(Dimensions) },
-            { "similarity", BsonString.Create(similarityValue) },
+            { "numDimensions", Dimensions },
+            { "similarity", similarityValue },
         };
 
-        if (Quantization.HasValue)
-        {
-            vectorField.Add("quantization", BsonString.Create(Quantization.ToString()?.ToLower()));
-        }
+        vectorField.Add("quantization", Quantization.ToString()?.ToLowerInvariant(), Quantization.HasValue);
 
         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
+            vectorField.Add("hnswOptions",
+                new BsonDocument
                 {
-                    { "type", BsonString.Create("filter") },
-                    { "path", BsonString.Create(filterPath.Render(renderArgs).FieldName) }
-                };
-
-                fieldDocuments.Add(fieldDocument);
-            }
+                    { "maxEdges", HnswMaxEdges ?? 16 }, { "numEdgeCandidates", HnswNumEdgeCandidates ?? 100 }
+                });
         }
 
+        var fieldDocuments = new List<BsonDocument> { vectorField };
+        RenderFilterFields(renderArgs, fieldDocuments);
         return new BsonDocument { { "fields", new BsonArray(fieldDocuments) } };
     }
 }

src/MongoDB.Driver/CreateVectorSearchIndexModelBase.cs

@@ -0,0 +1,82 @@
+/* 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.Collections.Generic;
+using System.Linq;
+using MongoDB.Bson;
+
+namespace MongoDB.Driver;
+
+/// <summary>
+/// Defines common parts of a vector index model using strongly-typed C# APIs.
+/// </summary>
+public abstract class CreateVectorSearchIndexModelBase<TDocument> : CreateSearchIndexModel
+{
+    /// <summary>
+    /// The field containing the vectors to index.
+    /// </summary>
+    public FieldDefinition<TDocument> Field { get; }
+
+    /// <summary>
+    /// Fields that may be used as filters in the vector query.
+    /// </summary>
+    public IReadOnlyList<FieldDefinition<TDocument>> FilterFields { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CreateVectorSearchIndexModel{TDocument}"/> class for a vector
+    /// index where the vector embeddings are created manually. The required options for <see cref="VectorSimilarity"/>
+    /// and the number of vector dimensions are passed to the constructor.
+    /// </summary>
+    /// <param name="name">The index name.</param>
+    /// <param name="field">The field containing the vectors to index.</param>
+    /// <param name="filterFields">Fields that may be used as filters in the vector query.</param>
+    protected CreateVectorSearchIndexModelBase(
+        FieldDefinition<TDocument> field,
+        string name,
+        params FieldDefinition<TDocument>[] filterFields)
+        : base(name, SearchIndexType.VectorSearch)
+    {
+        Field = field;
+        FilterFields = filterFields?.ToList() ?? [];
+    }
+
+    /// <summary>
+    /// Renders the index model to a <see cref="BsonDocument"/>.
+    /// </summary>
+    /// <param name="renderArgs">The render arguments.</param>
+    /// <returns>A <see cref="BsonDocument" />.</returns>
+    internal abstract BsonDocument Render(RenderArgs<TDocument> renderArgs);
+
+    /// <summary>
+    /// Called by subclasses to render the filters for the index fields section.
+    /// </summary>
+    /// <param name="renderArgs">The render args.</param>
+    /// <param name="fields">The list into which fields should be added.</param>
+    private protected void RenderFilterFields(RenderArgs<TDocument> renderArgs, List<BsonDocument> fields)
+    {
+        if (FilterFields != null)
+        {
+            foreach (var filterPath in FilterFields)
+            {
+                var fieldDocument = new BsonDocument
+                {
+                    { "type", "filter" }, { "path", filterPath.Render(renderArgs).FieldName }
+                };
+
+                fields.Add(fieldDocument);
+            }
+        }
+    }
+}

src/MongoDB.Driver/MongoCollectionImpl.cs

@@ -1752,7 +1752,7 @@ private CreateSearchIndexesOperation CreateCreateIndexesOperation(
                         => new CreateSearchIndexRequest(
                             model.Name,
                             model.Type,
-                            model is CreateVectorSearchIndexModel<TDocument> createVectorSearchIndexModel
+                            model is CreateVectorSearchIndexModelBase<TDocument> createVectorSearchIndexModel
                                 ? createVectorSearchIndexModel.Render(renderArgs)
                                 : model.Definition)),
                     _collection._messageEncoderSettings);

src/MongoDB.Driver/PipelineStageDefinitionBuilder.cs

@@ -2167,9 +2167,9 @@ public static PipelineStageDefinition<TInput, TInput> VectorSearch<TInput>(
                 args =>
                 {
                     ClientSideProjectionHelper.ThrowIfClientSideProjection(args.DocumentSerializer, operatorName);
+
                     var vectorSearchOperator = new BsonDocument
                     {
-                        { "queryVector", queryVector.Vector },
                         { "path", field.Render(args).FieldName },
                         { "limit", limit },
                         { "numCandidates", options?.NumberOfCandidates ?? limit * 10, options?.Exact != true },
@@ -2178,6 +2178,16 @@ public static PipelineStageDefinition<TInput, TInput> VectorSearch<TInput>(
                         { "exact", true, options?.Exact == true }
                     };
 
+                    if (queryVector.Vector is BsonString bsonString)
+                    {
+                        vectorSearchOperator["query"] = new BsonDocument { { "text", bsonString } };
+                        vectorSearchOperator.Add("model", options?.AutoEmbeddingModelName, options?.AutoEmbeddingModelName != null);
+                    }
+                    else
+                    {
+                        vectorSearchOperator["queryVector"] = queryVector.Vector;
+                    }
+
                     var document = new BsonDocument(operatorName, vectorSearchOperator);
                     return new RenderedPipelineStageDefinition<TInput>(operatorName, document, args.DocumentSerializer);
                 });

src/MongoDB.Driver/QueryVector.cs

@@ -40,6 +40,18 @@ private QueryVector(BsonArray array)
             Vector = array;
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="QueryVector"/> class with un-vectorized text for use with
+        /// an auto-embedding vector index, which will create the actual vector from this text.
+        /// </summary>
+        /// <param name="text">The text to search for.</param>
+        public QueryVector(string text)
+        {
+            Ensure.IsNotNull(text, nameof(text));
+
+            Vector = text;
+        }
+
         /// <summary>
         /// Initializes a new instance of the <see cref="QueryVector"/> class.
         /// </summary>
@@ -79,6 +91,15 @@ public QueryVector(ReadOnlyMemory<int> readOnlyMemory) :
         {
         }
 
+        /// <summary>
+        /// Performs an implicit conversion from <see cref="string"/> to <see cref="QueryVector"/>.
+        /// </summary>
+        /// <param name="text">The query text, for use with an auto-embedding index.</param>
+        /// <returns>
+        /// The result of the conversion.
+        /// </returns>
+        public static implicit operator QueryVector(string text) => new(text);
+
         /// <summary>
         /// Performs an implicit conversion from <see cref="double"/>[] to <see cref="QueryVector"/>.
         /// </summary>