diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index c159bb04..73c5ffcc 100644 --- a/source/fundamentals/linq.txt +++ b/source/fundamentals/linq.txt @@ -135,17 +135,17 @@ You can print the results of the preceding example as follows: var results = query.ToCursor(); - Supported Aggregation Stages ---------------------------- -You can use LINQ to create an :ref:`aggregation pipeline `. +You can use LINQ to create an :manual:`aggregation pipeline `. The {+driver-short+} automatically translates each LINQ statement into the corresponding aggregation pipeline stages. In this section you can learn which aggregation pipeline stages are supported. -To learn more about the aggregation pipeline stages, see the -:ref:`aggregation-pipeline-operator-reference` page in the server manual. +To learn more about the aggregation pipeline stages, see +:manual:`Aggregation Stages ` +in the {+mdb-server+} manual. $project ~~~~~~~~ @@ -519,7 +519,7 @@ The ``$group`` aggregation stage separates documents into groups according to the criteria you specify. Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate an ``$group`` stage using LINQ: +to generate a ``$group`` stage using LINQ: .. tabs:: @@ -570,7 +570,7 @@ The ``$sort`` aggregation stage returns the results of your query in the order that you specify. Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate an ``$sort`` stage using LINQ: +to generate a ``$sort`` stage using LINQ: .. tabs:: @@ -793,6 +793,16 @@ in the Atlas manual. For more examples about running Atlas Vector Search queries {+driver-short+}, see :atlas:`Run Vector Search Queries ` in the Atlas manual and select :guilabel:`C#` from the language dropdown. +Aggregation Operators +--------------------- + +You can use :manual:`aggregation pipeline operators +` in your aggregation stages to modify +documents and perform calculations. + +The following sections describe aggregation operators that you can +implement by using LINQ methods. + Bitwise Operators ~~~~~~~~~~~~~~~~~ @@ -967,6 +977,42 @@ The result contains the following values: 0 1 +.. _csharp-linq-convert: + +$convert +~~~~~~~~ + +The ``$convert`` operator converts a value to a specified type. You can +use this operator to perform type conversions in stages such as +``$project``, ``$addFields``, and ``$set``. + +In the driver, you can use the ``Mql.Convert()`` method to +convert a value from one type to a different specified type. To learn +more about conversion behavior and permitted conversions, see the +:manual:`$convert reference ` +in the {+mdb-server+} manual. + +The ``Convert()`` method takes the following parameters: + +- Value to convert. +- ``ConvertOptions`` instance that specifies the type to convert to + and options. Some conversions require you to specify certain options, but + you can also set options to handle errors or null values. + +The following code performs the following actions by using LINQ methods: + +- Converts the ``RestaurantId`` string values to ``int`` values in a + ``Select()`` projection +- Sets the returned value to ``-1`` if an error occurs during conversion +- Sets the returned value to ``0`` if the input value is ``null`` or missing + +.. code-block:: csharp + + var query = queryableCollection + .Select(r => Mql.Convert(r.RestaurantId, new ConvertOptions { OnError = -1, OnNull = 0 })); + +The driver stores the converted values under the original field name in +the output documents. Unsupported Aggregation Stages ------------------------------ @@ -984,7 +1030,8 @@ the :ref:`` section. Supported Methods ----------------- -The following are some methods supported by the {+driver-long+} implementation of LINQ: +The following table describes some methods supported by the +{+driver-long+} implementation of LINQ: .. list-table:: :header-rows: 1 @@ -1005,6 +1052,9 @@ The following are some methods supported by the {+driver-long+} implementation o * - ``LongCount`` - Returns an ``Int64`` that represents the number of documents that match the specified criteria + * - ``Convert`` + - Converts a value from one type to a different specified type + * - ``DateFromString`` - Converts a ``string`` to a ``DateTime`` object diff --git a/source/whats-new.txt b/source/whats-new.txt index be7d0549..db8d5b14 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -20,6 +20,7 @@ What's New Learn what's new in: +* :ref:`Version 3.4 ` * :ref:`Version 3.3 ` * :ref:`Version 3.2 ` * :ref:`Version 3.1 ` @@ -41,6 +42,17 @@ In accordance with the `MongoDB Software Lifecycle Schedules version of {+driver-short+} will raise the minimum {+mdb-server+} version from 4.0 to 4.2. {+driver-short+} will no longer support {+mdb-server+} 4.0. +.. _csharp-version-3.4: + +What's New in 3.4 +----------------- + +The 3.4 driver release includes the following new features: + +- Adds the ``Mql.Convert()`` LINQ method to convert between types when + performing aggregations. To learn more, see the + :ref:`csharp-linq-convert` section of the LINQ guide. + .. _csharp-version-3.3: What's New in 3.3