Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCSP-43911 - Implicit Client-Side Projection #242

Merged
merged 8 commits into from
Oct 3, 2024
Merged
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions source/whats-new.txt
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,76 @@ The 3.0 driver release includes the following new features:
`TimeOnly Struct. <https://learn.microsoft.com/en-us/dotnet/api/system.timeonly?view=net-6.0>`__
API reference page on MSDN.

- Adds support for client-side projection when using the ``Find()`` method,
the ``Select()`` method, or the ``Project()`` aggregation stage.
In previous versions of the driver, you could perform client-side
projection only after calling the ``ToEnumerable()`` or ``AsEnumerable()`` method, and
only within the ``Select()`` method.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In previous versions of the driver behavior depended on which LINQ provider you were using:

  • LINQ2: implicit client-side projections in Find, Project and Select
  • LINQ3: explicit client-side projections only

In the 3.0 version of the driver implicit client-side projections are supported but only if EnableClientSideProjections == true

By "explicit client-side projections" I mean calling ToEnumerable() or AsEnumerable() to specify where the client-side part of the query starts.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I reworded this section. Is it accurate to say that v3.0 supports implicit client-side projection when using the LINQ3 provider, so long as that setting is true?


Select a tab below to see how to enable and use client-side projection for the
corresponding method.

.. tabs::

.. tab:: Find() Method
:tabid: find-method

.. code-block:: csharp

// Enable client-side projection
var findOptions = new FindOptions;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

var findOptions = new FindOptions();

missing parenthesis

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm looking forward to IT renewing my Rider license so I can write these samples in an IDE...

findOptions.TranslationOptions = new ExpressionTranslationOptions
{
EnableClientSideProjections = true
};

var find = collection
.Find(doc => doc.Id == 1, findOptions);
.Project(doc => new { R = MyFunction(doc.Name) });

.. tab:: Select() Method
:tabid: select-method

.. code-block:: csharp

// Enable client-side projection
var translationOptions = new ExpressionTranslationOptions
{
EnableClientSideProjections = true
};

var queryable = collection
.AsQueryable(translationOptions)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is subtle but the actual argument to AsQueryable is an AggregateOptions value, not an ExpressionTranslationOptions value.

We might want to be explicit about that.

AsQueryable(translationOptions) does work but only because there is an implicit conversion from ExpressionTranslationOptions to AggregateOptions, and I'm not sure we're going to keep that implicit conversion.

.Where(doc => doc.Id == 1)
.Select(doc => new { R = MyFunction(doc.Name) });

.. tab:: Project() Method
:tabid: project-method

.. code-block:: csharp

// Enable client-side projection
var aggregateOptions = new AggregateOptions;
aggregateOptions.TranslationOptions = new ExpressionTranslationOptions
{
EnableClientSideProjections = true
};

var aggregate = collection
.Aggregate(pipeline, aggregateOptions)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some of your tests call Aggregate() with no arguments, but I couldn't find that method overload and wasn't sure whether it accepted an options argument--hence the pipeline argument.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The correct syntax is:

collection.Aggregate(aggregateOptions)

There is no overload that takes a pipeline.

Aggregate is an extension method:

public static IAggregateFluent<TDocument> Aggregate<TDocument>(this IMongoCollection<TDocument> collection, AggregateOptions options = null)

and the options argument is optional so:

collection.Aggregate()

is the same as:

collection.Aggregate(options: null)

Copy link
Collaborator Author

@mongoKart mongoKart Oct 3, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.Project(doc => new { R = MyFunction(doc.Name) });

.. tip:: MongoClientSettings

To enable client-side projection for all queries on a client, set the
``TranslationOptions`` property of the ``MongoClientSettings`` object to ``true``.

To learn more about using the aggregation pipeline with the {+driver-short+}, see
:ref:`csharp-aggregation`.

For more information about this release, see the :github:`v3.0 release notes
</mongodb/mongo-csharp-driver/releases/tag/v3.0.0>`.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link will be broken until actual release.


.. _csharp-version-2.28:

What's New in 2.28
Expand Down
Loading