CSHARP-6017: Support LINQ LeftJoin for joins and includes

[damieng]

Adds support for left outer join semantics in the LINQ3 provider, translating to a $project → $lookup → $unwind → $project aggregation pipeline.

Motivation

• We need left-join semantics for include and join in our EF Core Provider
• .NET 10 adds Queryable.LeftJoin to the BCL which we'll want to translate
• MongoQueryable.LeftJoin is also added so users on earlier runtimes can use the same API

Public API

// IMongoCollection overload (convenience)
orders.AsQueryable()
    .LeftJoin(customers, o => o.CustomerId, c => c.Id, (o, c) => new { o, c })

// IQueryable overload (also handles Queryable.LeftJoin on .NET 10+)
orders.AsQueryable()
    .LeftJoin(customers.AsQueryable(), o => o.CustomerId, c => c.Id, (o, c) => new { o, c })

// Typed result (navigation-property style)
orders.AsQueryable()
    .LeftJoin(customers, o => o.CustomerId, c => c.Id,
        (o, c) => new LeftJoinResult<Order, Customer> { Outer = o, Inner = c })

LeftJoinResult<TOuter, TInner> is an immutable struct (matching the LookupResult convention) whose Inner is null when no matching document exists.

Translation

{ $project: { _outer: "$$ROOT", _id: 0 } }
{ $lookup:  { from: "customers", localField: "_outer.CustomerId", foreignField: "_id", as: "_inner" } }
{ $unwind:  { path: "$_inner", preserveNullAndEmptyArrays: true } }
{ $project: { ... result selector ... } }

preserveNullAndEmptyArrays: true on the $unwind is the single line that distinguishes a left join from an inner join. Outer documents with no matching inner survive with _inner: null.

Notes

• Chaining — multiple LeftJoin calls compose naturally; each re-wraps the current pipeline output in _outer so subsequent localField paths resolve correctly.
• Fan-out — multiple inner matches produce multiple result rows (same as SQL left join / $unwind semantics).
• Collision detection — throws ExpressionNotSupportedException if the outer document type has a BSON element already named _outer or _inner.
• Server version — uses the simple localField/foreignField $lookup form, which requires MongoDB 3.2+. The driver already targets 3.6+, so no additional version guard is needed.

[adelinowona]

The doc comment says Inner is "null when no matching inner document exists," but TInner is unconstrained. For a value-type inner (e.g. LeftJoinResult<Order, int>) a no-match row deserializes the missing _inner to default(TInner) (0), not null — so "no match" and a real zero become indistinguishable. Either qualify the comment or steer TInner toward reference/nullable types.

[damieng]

Oleks says we shouldn't be introducing NRTs at this point so I guess we'll handle this when we do that.

[adelinowona]

Minor: this ternary can collapse — AstStage.Unwind already defaults preserveNullAndEmptyArrays to null, so AstStage.Unwind("_inner", preserveNullAndEmptyArrays: isLeftJoin ? true : (bool?)null) does the same thing without duplicating the "_inner" literal.

[damieng]

Done.

[Copilot]

Pull request overview

Adds LINQ3 support for left outer join semantics via a new LeftJoin API and corresponding pipeline translation (wrapping the outer document, performing $lookup, and $unwind with preserveNullAndEmptyArrays: true). This extends join/include scenarios (including upcoming .NET Queryable.LeftJoin) and introduces a LeftJoinResult<TOuter, TInner> helper result type.

Changes:

• Introduces MongoQueryable.LeftJoin overloads and LeftJoinResult<TOuter, TInner>.
• Extends LINQ3 pipeline translation to recognize and translate LeftJoin, including chained joins.
• Adds integration/smoke tests covering translation shape, chaining, reserved-name collisions, and round-tripping.

Reviewed changes

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

Show a summary per file

File	Description
tests/SmokeTests/MongoDB.Driver.SmokeTests.Sdk/LeftJoinTests.cs	Net10 smoke test validating basic left-join behavior against a live server.
tests/MongoDB.Driver.Tests/Linq/Linq3Implementation/Jira/CSharpLeftJoinTests.cs	LINQ3 integration tests for translation stages, chaining, collision checks, and serialization round-trips.
src/MongoDB.Driver/Linq/MongoQueryable.cs	Adds public LeftJoin extension methods for IMongoCollection and IQueryable inner sources.
src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators/JoinMethodToPipelineTranslator.cs	Implements $lookup + $unwind(preserveNullAndEmptyArrays:true) translation and handles filtered inner queryables.
src/MongoDB.Driver/Linq/Linq3Implementation/Translators/ExpressionToPipelineTranslators/ExpressionToPipelineTranslator.cs	Routes LeftJoin method calls to the join translator.
src/MongoDB.Driver/Linq/Linq3Implementation/SerializerFinders/SerializerFinderVisitMethodCall.cs	Adds serializer deduction support for LeftJoin.
src/MongoDB.Driver/Linq/Linq3Implementation/Reflection/QueryableMethod.cs	Adds reflection handle for BCL Queryable.LeftJoin (when available).
src/MongoDB.Driver/Linq/Linq3Implementation/Reflection/MongoQueryableMethod.cs	Adds reflection handle for MongoQueryable.LeftJoin.
src/MongoDB.Driver/Linq/LeftJoinResult.cs	New LeftJoinResult<TOuter, TInner> result struct with nullable Inner.
CSHARP-6017-review-findings.md	Adds a review-findings document (currently out of sync with the implementation in this PR).

---

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

[sanych-sun]

Thank you for adding this tests. Looks really good. The only thing - we might want to merge these test cases into existing EnumerableTests, where other tests for Quaryable lives.

[sanych-sun]

Thank you for moving the file here. Please remove CSharp from the name, and name it QueryableLeftJoingTests instead.

[sanych-sun]

Should we put some data into the collection?

[sanych-sun]

Please check if TranslationContext.GetUltimateSource should be used here instead.