DOCSP-48120: elemmatch method overload

Author: rustagir

source/fundamentals/builders.txt

@@ -99,6 +99,8 @@ to a LINQ query:
    var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial");
    var query = collection.AsQueryable().Where(f => filter.Inject());
 
+.. _csharp-builders-array-operators:
+
 Array Operators
 ~~~~~~~~~~~~~~~
 
@@ -126,6 +128,24 @@ criteria. The following example returns documents that contain the value
    var builder = Builders<Flower>.Filter;
    var filter = builder.ElemMatch(f => f.Season, s => s == "Summer");
 
+.. tip:: ElemMatch() Overload
+
+   The ``ElemMatch()`` method has an overload to accept a single filter
+   parameter. This functionality supports performing queries that
+   include nested ``$elemMatch`` statements.
+
+   The following code demonstrates how to construct a nested
+   ``$elemMatch`` query that uses both implementations of the
+   ``ElemMatch()`` method:
+
+   .. code-block:: csharp
+
+      // ElemMatch() with only filter parameter
+      var arrayFilter = Builders<MyEntry[]>.Filter.ElemMatch(<filter>);
+
+      // ElemMatch() with field name and filter parameters
+      var filter = Builders<MyClass>.Filter.ElemMatch(<array field name>, arrayFilter);
+
 To learn more about array operators, see the :manual:`Array Query Operators
 </reference/operator/query-array/>` guide in the {+mdb-server+} manual.
 
@@ -491,4 +511,5 @@ guide, see the following API Documentation:
 - `SortDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinitionBuilder-1.html>`__
 - `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__
 - `IndexKeysDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IndexKeysDefinitionBuilder-1.html>`__
-- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__
+- `PipelineDefinitionBuilder
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__

source/whats-new.txt

@@ -46,6 +46,11 @@ The 3.3 driver release includes the following new features:
   ``create`` events in the ``ChangeStreamDocument`` class. To learn more
   about change streams, see the :ref:`csharp-change-streams` guide.
 
+- Supports nested ``$elemMatch`` queries by providing an overload of the
+  ``ElemMatch()`` method that takes only a filter parameter. To learn
+  more, see the :ref:`csharp-builders-array-operators` section of the
+  Builders guide.
+
 .. _csharp-version-3.2:
 
 What's New in 3.2
@@ -426,4 +431,5 @@ The 2.22 driver release includes the following new features:
 - Reduced memory allocation when using encryption.
 - Added logging messages for server discovery and monitoring (SDAM) events. For more
   information on these events, see the
-  `MongoDB SDAM Logging and Monitoring specification. <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst#log-messages>`__
+  `MongoDB SDAM Logging and Monitoring specification.
+  <https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.rst#log-messages>`__