CSHARP-5646: Implement vector similarity match expressions by ajcvickers · Pull Request #1907 · mongodb/mongo-csharp-driver

ajcvickers · 2026-03-10T13:28:40Z

This commit introduces support for MongoDB similarity functions ($similarityDotProduct, $similarityCosine, and $similarityEuclidean) in LINQ3 queries.

Summary of Changes

New Public API: Added SimilarityFunctions static class with DotProduct, Cosine, and Euclidean methods supporting IEnumerable<T> and ReadOnlyMemory<T>.
LINQ Translation: Implemented translation of these methods to their respective MQL aggregation operators.
AST Support: Added AstSimilarityFunctionExpression and associated AstNaryOperator values to represent these functions in the MongoDB Abstract Syntax Tree.
Serializer Deduction: Updated SerializerFinderVisitMethodCall to handle return type (double) for these new functions.

codeowners-service-app · 2026-03-10T13:32:25Z

Assigned jordan-smith721 for team dbx-csharp-dotnet because adelinowona is out of office.
Assigned damieng for team dbx-csharp-dotnet because adelinowona is out of office.

Copilot

Pull request overview

Adds LINQ3 support for MongoDB vector similarity aggregation expressions by introducing a new SimilarityFunctions public API and translating it into the corresponding $similarity* MQL operators, including AST + serializer support and an appropriate server feature gate.

Changes:

Introduces MongoDB.Driver.Linq.SimilarityFunctions (DotProduct/Cosine/Euclidean) for use in LINQ queries.
Implements LINQ3 translation + AST rendering for $similarityDotProduct, $similarityCosine, and $similarityEuclidean.
Adds integration tests covering translation and execution for multiple vector container types (arrays/lists/collections/ReadOnlyMemory).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/MongoDB.Driver.Tests/Linq/Linq3Implementation/Translators/ExpressionToAggregationExpressionTranslators/MethodTranslators/SimilarityMethodToAggregationExpressionTranslatorTests.cs	New integration tests validating translation/output for similarity functions across vector shapes and element types.
src/MongoDB.Driver/Linq/SimilarityFunctions.cs	New public LINQ API surface for similarity functions (throws on local evaluation).
src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToAggregationExpressionTranslators/MethodTranslators/SimilarityFunctionsMethodToAggregationExpressionTranslator.cs	New method translator mapping SimilarityFunctions calls to AST similarity expressions.
src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToAggregationExpressionTranslators/MethodCallExpressionToAggregationExpressionTranslator.cs	Routes DotProduct/Cosine/Euclidean method calls to the new translator.
src/MongoDB.Driver/Linq/Linq3Implementation/SerializerFinders/SerializerFinderVisitMethodCall.cs	Deduces numeric return serializer for SimilarityFunctions calls.
src/MongoDB.Driver/Linq/Linq3Implementation/Reflection/SimilarityFunctionsMethod.cs	Registers SimilarityFunctions overloads for method identification in translation/serializer deduction.
src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Visitors/AstNodeVisitor.cs	Adds visitor support for the new similarity AST expression node.
src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Expressions/AstSimilarityFunctionExpression.cs	New AST node that renders similarity operators with `{ vectors: [...], score: ... }`.
src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Expressions/AstNaryOperator.cs	Adds operator enum values + rendering for `$similarity*` operators.
src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Expressions/AstExpression.cs	Adds factory method for creating similarity AST expressions.
src/MongoDB.Driver/Linq/Linq3Implementation/Ast/AstNodeType.cs	Adds `SimilarityFunctionExpression` node type.
src/MongoDB.Driver/Core/Misc/Feature.cs	Adds `Feature.SimilarityFunctions` gated at `WireVersion.Server82`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

...nTranslators/MethodTranslators/SimilarityFunctionsMethodToAggregationExpressionTranslator.cs

...ssionTranslators/MethodTranslators/SimilarityMethodToAggregationExpressionTranslatorTests.cs

...slators/MethodTranslators/SimilarityFunctionsMethodToAggregationExpressionTranslatorTests.cs

sanych-sun · 2026-03-10T22:35:18Z

src/MongoDB.Driver/Linq/SimilarityFunctions.cs

+/// C# to Mongo Query Language (MQL) for execution in the MongoDB database. Calling the method directly is
+/// not supported.
+/// </summary>
+public static class SimilarityFunctions


We usually put such methods into Mql static class. It might be not too bad idea to group methods by the functionality, but also it will be more discoverable if it was under the Mql class. May be something like:

Mql.VectorSimilarity.DotProduct<>()

I considered this option, but decided functional grouping into a different class was fine because of the existence of MongoDBMath, which seems like has less justification for a new type than here. Is there something different about MongoDBMath, or was that a mistake?

I think MongoDBMath pre-dated Mql.

sanych-sun · 2026-03-10T22:37:20Z

src/MongoDB.Driver/Linq/SimilarityFunctions.cs

+        => Throw<TElement>(nameof(Euclidean));
+
+    private static double Throw<TElement>(string methodName)
+        => throw new InvalidOperationException(


Similar methods in Mql class throws NotSupportedException. I think we should be consistent here and throw the same exception.

Technically, we could choose to implement this. But I'm fine with changing it.

sanych-sun · 2026-03-10T22:54:11Z

src/MongoDB.Driver/Linq/Linq3Implementation/Ast/Expressions/AstNaryOperator.cs

        BitXor,
        Concat,
        ConcatArrays,
+        Cosine,


Do we really need this new enum values? Somehow I was under impression that AstNaryOperator enum works together with AstNaryExpression class, but if we have a specialized class, we probably do not need to have this enum values.

This makes sense. Have made updates.

sanych-sun

LGTM + minor comment

sanych-sun · 2026-03-16T16:25:31Z

src/MongoDB.Driver/Mql.cs

+        /// <param name="normalizeScore">Whether to normalize the result for use as a vector search score.</param>
+        /// <typeparam name="TElement">The vector element type</typeparam>
+        /// <returns>The dot-product measure between the two vectors.</returns>
+        /// <exception cref="NotSupportedException">if executed.</exception>


Minor: exception here seems to be a little misleading. Let's remove it or explain it a little more:
"NotSupportedException if executed outside of LINQ expression."

What does, "outside the LINQ expression" mean? What kind of execution can happen that is not "outside the LINQ expression?" If the LINQ expression is translated, then it isn't executed. The only thing I can think of is compiling and then executing the LINQ expression, but that will still throw, and it's not really "outside" anyway.

How about, "if used for anything other than translating to MQL?"

This commit introduces support for MongoDB similarity functions (`$similarityDotProduct`, `$similarityCosine`, and `$similarityEuclidean`) in LINQ3 queries. #### Summary of Changes - **New Public API**: Added `SimilarityFunctions` static class with `DotProduct`, `Cosine`, and `Euclidean` methods supporting `IEnumerable<T>` and `ReadOnlyMemory<T>`. - **LINQ Translation**: Implemented translation of these methods to their respective MQL aggregation operators. - **AST Support**: Added `AstSimilarityFunctionExpression` and associated `AstNaryOperator` values to represent these functions in the MongoDB Abstract Syntax Tree. - **Serializer Deduction**: Updated `SerializerFinderVisitMethodCall` to handle return type (double) for these new functions.

ajcvickers requested a review from a team as a code owner March 10, 2026 13:28

ajcvickers requested review from adelinowona and Copilot March 10, 2026 13:28

ajcvickers added the feature Adds new user-facing functionality. label Mar 10, 2026

Copilot started reviewing on behalf of ajcvickers March 10, 2026 13:29 View session

codeowners-service-app bot requested a review from jordan-smith721 March 10, 2026 13:32

Copilot AI reviewed Mar 10, 2026

View reviewed changes

ajcvickers force-pushed the CSHARP-5646 branch from 0859053 to 8718d1f Compare March 10, 2026 14:17

jordan-smith721 removed their request for review March 10, 2026 14:59

codeowners-service-app bot requested a review from damieng March 10, 2026 15:02

sanych-sun requested changes Mar 10, 2026

View reviewed changes

ajcvickers force-pushed the CSHARP-5646 branch from 81abdea to 703719a Compare March 12, 2026 11:30

ajcvickers requested a review from sanych-sun March 12, 2026 11:34

sanych-sun approved these changes Mar 16, 2026

View reviewed changes

adelinowona approved these changes Mar 16, 2026

View reviewed changes

ajcvickers added 4 commits March 17, 2026 09:24

Addressing review feedback

27b33ae

Moved methods to MQL class.

c6c8172

Message.

ececf21

ajcvickers force-pushed the CSHARP-5646 branch from 703719a to ececf21 Compare March 17, 2026 09:29

Conversation

ajcvickers commented Mar 10, 2026

Summary of Changes

Uh oh!

codeowners-service-app bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sanych-sun left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ajcvickers Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codeowners-service-app bot commented Mar 10, 2026 •

edited

Loading

ajcvickers Mar 17, 2026 •

edited

Loading