Community

Markus Wildgruber

Managing Director/Cloud Architect, sevantage software GmbH

As shown in my last article on the [basics of running aggregation pipelines with the MongoDB C# driver](https://www.mongodb.com/developer/languages/csharp/mongodb-aggregation-basics-csharp/), there are plenty of ways to set up and run aggregation pipelines from a .NET application. 
The MongoDB C# driver brings a powerful LINQ driver that simplifies building aggregation pipelines for developers who are experienced with C# and less with MongoDB. 

For experienced developers, or when you have complex aggregation pipelines, you will likely use MongoDB Compass or another tool to set up, test, and fine-tune an aggregation pipeline
that you want to run from a C# application later on. Using this easy workflow, you can use all aggregation pipeline stages and build the pipeline on a realistic dataset before including it in code. 
Also, for experienced MongoDB developers, it might be easier to read the aggregation pipeline in JSON form instead of C# statements. 

This tutorial focusses on an approach that enables experienced MongoDB developers to use pipelines from MongoDB Compass and include them in C# code. 
This approach complements the basic methods shown in my last tutorial and can be used for complex scenarios. 

The samples that are used throughout this article are based on the movies collection in the samples_mflix database. 
We will use the following Data Transfer Object (DTO) classes: 

```csharp
[BsonIgnoreExtraElements]
[BsonNoId]
public class Movie
{
    [BsonElement("title")]
    public required string Title { get; set; }

    [BsonElement("year")]
    public required int Year { get; set; }

    [BsonElement("cast")]
    public List<string> Cast { get; set; } = new();

    [BsonElement("imdb")]
    public Imdb Imdb { get; set; } = new();
}

[BsonIgnoreExtraElements]
public class Imdb
{
    [BsonElement("rating")]
    public double Rating { get; set; }
}

public class RatingByYear
{
    [BsonId]
    public int Year { get; set; }

    [BsonElement("rating")]
    public double AvgRating { get; set; }
}
```

## Parsing aggregation pipelines from JSON

When setting up an aggregation pipeline in MongoDB Compass, you can retrieve the JSON for your pipeline by switching to the **Text** view:
![Use the "Text" button to switch to JSON view of the aggregation pipeline for easier copying][1]

This shows the complete pipeline so that you can easily copy the JSON to the clipboard. 
As a first step, you can include the JSON in a C# multiline string. In our case, we use the aggregation from the last article 
for demonstration purposes:

```csharp
var pipelineStr = """
    [
      {
        $match: {
          cast: "Robert De Niro"
        }
      },
      {
        $group: {
          _id: "$year",
          rating: { $avg: "$imdb.rating" }
        }
      },
      {
        $sort: {
          rating: -1
        }
      }
    ]
    """;

PipelineDefinition<Movie, RatingByYear> pipeline = BsonSerializer.Deserialize<BsonArray>(pipelineStr)
    .Select(x => x.AsBsonDocument)
    .ToArray();

var result = await (await movies.AggregateAsync<RatingByYear>(pipeline)).ToListAsync();
```
The above code deserializes the pipeline from the multiline string and converts it to an array of `BsonDocument` objects. 
There is an implicit conversion operator that allows converting the array to a `PipelineDefinition<Movie, RatingByYear>` object. 
This pipeline definition can then be supplied as a variable to the `AggregateAsync` method that runs the aggregation and returns the result. 

Instead of including the pipeline as a string in your C# code, you can also read it from a file that you deploy with your application, or embed a JSON file as a resource in your application:

![Set build action to "Embedded resource" to include JSON file as a resource][2]

This provides a better separation between the C# code and the pipelines. You can access the resource like this: 

```csharp
// Be sure to use the correct resource name, the schema is as follows: 
// <PROJECT ROOT NAMESPACE>.<Folders>.<FileName>
// If the resource name is invalid, null is returned 
using var stream = typeof(Program).Assembly.GetManifestResourceStream("MyNamespace.Pipelines.RatingByYear.json");
using var reader = new StreamReader(stream!);
var pipelineStr = await reader.ReadToEndAsync();

PipelineDefinition<Movie, RatingByYear> pipeline = BsonSerializer.Deserialize<BsonArray>(pipelineStr)
    .Select(x => x.AsBsonDocument)
    .ToArray();

var result = await (await movies.AggregateAsync(pipeline)).ToListAsync();
```

## Using variables with aggregation pipelines

Having a static pipeline is a good start, but what if you want to make adjustments when running the aggregation pipeline? 
In our example, we might be interested in querying other members of the cast and only return a configurable number of years with the top ratings. 

```JSON
[
  {
    "$match": {
      "$expr": {
        "$in": [
          "$$castMember",
          {
            "$ifNull": [
              "$cast",
              []
            ]
          }
        ]
      }
    }
  },
  {
    "$group": {
      "_id": "$year",
      "rating": { "$avg": "$imdb.rating" }
    }
  },
  {
    "$setWindowFields": {
      "sortBy": { "rating": -1 },
      "output": {
        "docNo": {
          "$documentNumber": {}
        }
      }
    }
  },
  {
    "$match": {
      "$expr": {
        "$lte": [ "$docNo", "$$topN" ]
      }
    }
  },
  {
    "$unset": "docNo"
  }
]
```
The above pipeline has been adjusted to use the variables `$$castMember` and `$$topN`. 
We will have a closer look on these adjustments in the following section. For now, we focus on running the pipeline in C#. 
To provide values for the variables, an `AggregationOptions` object is used, as shown below: 

```csharp
using var stream = typeof(Program).Assembly.GetManifestResourceStream("MyNamespace.Pipelines.RatingByYearParameterized.json");
using var reader = new StreamReader(stream!);
var pipelineStr = await reader.ReadToEndAsync();

PipelineDefinition<Movie, RatingByYear> pipeline = BsonSerializer.Deserialize<BsonArray>(pipelineStr)
    .Select(x => x.AsBsonDocument)
    .ToArray();

var options = new AggregateOptions()
{
    Let = new BsonDocument()
    {
        { "castMember", "Al Pacino" },
        { "topN", 10 },
    }
};

var result = await (await movies.AggregateAsync(pipeline, options)).ToListAsync();
```

## Adjusting the pipeline for the use of variables

As you have seen, the pipeline has been adjusted to use the variables. This is necessary because not all stages use the variable values as expected. 
For instance, the first `$match` stage does not evaluate a variable when using the standard `$match` syntax: 

```JSON
{
  $match: {
    cast: "$$castMember"
  }
},
```

As the condition as such is valid for MongoDB, this does not raise an error but leads to an empty result set as there is no movie with a cast member that goes by the unusual name _$$castMember_. 
Using [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr/) in the condition asserts that the variables are replaced with their values when performing the comparison:

```JSON
{
  "$match": {
    "$expr": {
      "$in": [
        "$$castMember",
        {
          "$ifNull": [
            "$cast",
            []
          ]
        }
      ]
    }
  }
},
```

In addition, the expression syntax handles null values differently, so we need to add an [`$ifNull`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/ifNull/) expression that asserts that missing or null values are replaced with an empty array. 

In most cases, however, MongoDB raises an error when the variable cannot be used. In our sample, the pipeline cannot use the [`$limit` stage](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/) because this stage expects a static value for the maximum number of documents that should be returned. 
Hence we have to replace the simple `$limit` stage with a combination of: 

- `$setWindowFields` that sorts the documents and adds a property `docNo` for the number of the document.
- `$match` that keeps only the number of documents specified in the variable (also with an `$expr` condition). 
- `$unset` to remove the `docNo` property as we do not need it in our result set.

```JSON
{
  "$setWindowFields": {
    "sortBy": { "rating": -1 },
    "output": {
      "docNo": {
        "$documentNumber": {}
      }
    }
  }
},
{
  "$match": {
    "$expr": {
      "$lte": [ "$docNo", "$$topN" ]
    }
  }
},
{
  "$unset": "docNo"
}
```

When testing your pipeline, be aware that you also need to look for unexpected and especially empty result sets when introducing variables in a pipeline. 

## Summary

This tutorial outlined several ways to handle complex aggregation pipelines in C# while still keeping the original MongoDB pipeline definition available. You can use the latest and greatest MongoDB aggregation pipeline stages in their original form. Also, for developers who are experienced with MongoDB, the JSON format of the pipeline might be easier to read. 
When applying changes to the pipeline later on, you can test and analyze the exact pipeline in MongoDB Compass or the MongoDB shell. 

What is your favorite method to tackle challenging aggregation pipelines with the MongoDB C# driver? Let us know in the [MongoDB Developer Community Forums](https://www.mongodb.com/community/forums/)!

  [1]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt9fe0bd83adb54a93/67374db4910ead22da59315a/Text_View.png
  [2]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blta4c24bae3d7df8b9/67374e2c85819411800dfd23/Complex-Pipelines-Embedded-Resource.png

Learn how to enable developers to use complex aggregation pipelines from C# in their MongoDB application with this article from guest author Markus.

Handling Complex Aggregation Pipelines With C#

While basic CRUD statements like find, insert, update, and delete can take you a long way when building your application, sooner or later, users will want to look at data in different forms. As an example, if you have lots of data in a time series collection, calculating key performance indicators helps users derive meaningful conclusions from the data, e.g.: 

- What was the average value for the sensor yesterday?
- What was the range of values in the last month?
- How many readings were received in the last hour?

This is where [aggregation operations](https://www.mongodb.com/docs/manual/aggregation/) come in and help to transform and summarize data so that they present the information in a way that is easy to grasp and answers questions without having to look at the individual values. For instance, aggregations can be used to calculate KPIs, to group data, in paging operations, and many other scenarios. 

This tutorial puts its focus on how to use aggregations with the MongoDB C# driver; if you want to learn about aggregation operations in depth, please have a look at the excellent e-book [Practical MongoDB Aggregations](https://www.practical-mongodb-aggregations.com/). 

You can run aggregations on the fly when querying your data. In fact, when using the MongoDB C# driver, you might run aggregations without even noticing as the driver often uses aggregations under the hood instead of plain find commands. 
 
Especially for complex operations, it is common practice to run aggregations in the background and store the data in a collection beforehand. This can be achieved by terminating the pipeline with a `$merge` or `$out` stage that writes the aggregation result into a collection. 

This pattern is called [on-demand materialized views](https://www.mongodb.com/docs/manual/core/materialized-views/). The complex pipeline is run seldom whereas the more common read requests do not put too much load on the server. The data in the on-demand materialized view can be updated periodically or in reaction to data changes. 

When setting up an aggregation pipeline, MongoDB Compass is a good starting point. You can open the collection in your development cluster and put together an aggregation pipeline in the graphical user interface. While the graphical user interface offers more guidance, there also is a text-based aggregation pipeline editor that can be used by more experienced developers. 

## Samples used in this tutorial

This tutorial shows several ways you can run aggregations from C# code. The samples use the `sample_mflix` database so that you can easily try out the code on your own MongoDB Atlas cluster. Please see the [Get Started](https://www.mongodb.com/docs/atlas/getting-started/) section in the MongoDB Atlas documentation on how to [deploy up a free cluster](https://www.mongodb.com/docs/atlas/tutorial/deploy-free-tier-cluster/) and [load the sample dataset](https://www.mongodb.com/docs/atlas/sample-data/). 

The sample database contains the `movies` collection with a document structure similar to this: 

```JSON
{
  "_id": ObjectId("573a139af29313caabcef0ad"),
  "imdb": {
    "rating": 8.2,
    "votes": 297933,
    "id": 112641
  },
  "year": 1995,
  "title": "Casino",
  "cast": [
    "Robert De Niro",
    "Sharon Stone",
    "Joe Pesci",
    "James Woods"
  ]
}
```

In our example, we want to filter by an actor, group by the year, and order the documents by the average rating of the movies of the year. This can be achieved by using the following aggregation pipeline: 

```JSON
[
  {
    $match: {
      cast: "Robert De Niro"
    }
  },
  {
    $group: {
      _id: "$year",
      rating: { $avg: "$imdb.rating" }
    }
  },
  {
    $sort: {
      rating: -1
    }
  }
]
```

When running the pipeline in MongoDB Compass, we receive the following result: 

```JSON
[
  {
    "_id": 1974,
    "rating": 9.1
  },
  {
    "_id": 1980,
    "rating": 8.3
  },
  {
    "_id": 1995,
    "rating": 8.25
  },
  {
    "_id": 1990,
    "rating": 8.25
  },
// ...
]
```

To support the aggregation, we create the following POCOs in C#: 

```CSharp
[BsonIgnoreExtraElements]
[BsonNoId]
public class Movie
{
    [BsonElement("title")]
    public required string Title { get; set; }

    [BsonElement("year")]
    public required int Year { get; set; }

    [BsonElement("cast")]
    public List<string> Cast { get; set; } = new();

    [BsonElement("imdb")]
    public Imdb Imdb { get; set; } = new();
}

[BsonIgnoreExtraElements]
public class Imdb
{
    [BsonElement("rating")]
    public double Rating { get; set; }
}

public class RatingByYear
{
    public int Year { get; set; }

    public double AvgRating { get; set; }
}
```

## Aggregation Methods for IMongoCollection<T>

The basic and most powerful way to run an aggregation pipeline in C# is to use the `AggregateAsync` method of `IMongoCollection<T>`. This method takes a pipeline definition as its most important input parameter and returns a cursor. For our sample, we could depict the aggregation pipeline like this: 

```CSharp
var pipeline = new EmptyPipelineDefinition<Movie>()
    .Match(x => x.Cast.Contains("Robert De Niro"))
    .Group(
        x => x.Year, 
        x => new RatingByYear() 
        { 
            Year = x.Key, 
            AvgRating = x.Average(y => y.Imdb.Rating)
        })
    .Sort(Builders<RatingByYear>.Sort.Descending(x => x.AvgRating));
var result = await (await movies.AggregateAsync(pipeline)).ToListAsync();
```

First, we define the pipeline and add the necessary stages to the pipeline. As you can see in the code above, you use lambda expressions or the `Builder<T>` that you might know from putting together CRUD statements. 
After running the aggregation, we use `ToListAsync` to store the aggregation result in a list. 

For our sample, the basic stages `$match`, `$group`, and `$sort` are sufficient, but there is a wide variety of methods that you can use to set up complex aggregation pipelines. If there is no explicit method for a specific pipeline stage, you can use the `AppendStage` method to append a stage that is defined as `BsonDocument`. We will have a closer look at this method in a follow-up to this tutorial. 

## Fluent interface 

The previous sample made use of a fluent interface when defining the aggregation pipeline. In addition to `AggregateAsync`, `IMongoCollection<T>` also offers an `Aggregate` method that is the starting point for the fluent aggregation interface: 

```CSharp
var result = await movies
    .Aggregate()
    .Match(x => x.Cast.Contains("Robert De Niro"))
    .Group(
        x => x.Year,
        x => new RatingByYear()
        {
            Year = x.Key,
            AvgRating = x.Average(y => y.Imdb.Rating)
        })
    .Sort(Builders<RatingByYear>.Sort.Descending(x => x.AvgRating))
    .ToListAsync();
```

This shortens the code above by some lines but basically offers the same functionality as defining the pipeline manually. 

## Using LINQ 

The MongoDB C# driver offers a powerful LINQ provider that is able to transform LINQ statements into a MongoDB aggregation pipeline. This way, developers can use LINQ statements in their code as they are used to; an aggregation pipeline is created under the hood and executed against the database when the results are enumerated: 

```CSharp
var result = movies
    .AsQueryable()
    .Where(x => x.Cast.Contains("Robert De Niro"))
    .GroupBy(x => x.Year)
    .Select(x => new RatingByYear()
    {
        Year = x.Key,
        AvgRating = x.Average(y => y.Imdb.Rating)
    })
    .OrderByDescending(x => x.AvgRating)
    .ToList();
```
 Or alternatively in query syntax: 

 ```CSharp
 var result = (from m in movies.AsQueryable()
              where m.Cast.Contains("Robert De Niro")
              group m by m.Year into grp
              select new RatingByYear()
              {
                  Year = grp.Key,
                  AvgRating = grp.Average(y => y.Imdb.Rating)
              }
              into x
              orderby x.AvgRating descending
              select x)
              .ToList();
```

While there is still a chance that a specific LINQ query cannot be transformed into an aggregation pipeline, these cases have become very rare with LINQ provider v3 and often can be solved by restructuring the LINQ statement. For other cases, the provider is maintained by MongoDB and extended regularly if there is something missing to support a LINQ query. 

## Comparison of the methods

As you can see, it is very easy to set up and run aggregation pipelines with the MongoDB C# driver. In fact, there are a variety of ways to achieve this goal. Which method is the best to use in your project? 

LINQ is widely used in C# projects and is a query technique that developers learn very early on their journey with C#. Using the LINQ-based approach enables developers to benefit from the power of aggregation pipelines without deep MongoDB knowledge. 

Of course, this abstraction also means less control over the aggregation pipelines; especially in complex scenarios, using the methods of `IMongoCollection<T>` offers the flexibility to put the pipeline together so that it fits the purpose perfectly. 

Which method do you use and prefer? Let us know in the [MongoDB Developer Community Forums](https://www.mongodb.com/community/forums/)!

Join MongoDB Community Contributor Markus to learn all about the basics of Aggregation Pipelines in C# with MongoDB

MongoDB C# Aggregation Pipeline Basics

> Starting out with MongoDB and C#? These tips will help you get your class maps right from the beginning to support your desired schema.

When starting my first projects with MongoDB and C# several years ago, what captivated me the most was how easy it was to store plain old CLR objects (POCOs) in a collection without having to create a static relational structure first and maintaining it painfully over the course of development.  

Though MongoDB and C# have their own set of data types and naming conventions, the [MongoDB C# Driver](https://www.mongodb.com/docs/drivers/csharp/current/#mongodb-c--driver) connects the two in a very seamless manner. At the center of this, [class maps](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/class-mapping/) are used to describe the details of the mapping.  

This post shows how to fine-tune the mapping in key areas and offers solutions to common scenarios.

## Automatic mapping

Even if you don't define a class map explicitly, the driver will create one as soon as the class is used for a collection. In this case, the properties of the POCO are mapped to elements in the BSON document based on the name. The driver also tries to match the property type to the BSON type of the element in MongoDB.

Though automatic mapping of a class will make sure that POCOs can be stored in a collection easily, tweaking the mapping is rewarded by better memory efficiency and enhanced query performance. Also, if you are working with existing data, customizing the mapping allows POCOs to follow C# and .NET naming conventions without changing the schema of the data in the collection.

## Declarative vs. imperative mapping

Adjusting the class map can be as easy as adding attributes to the declaration of a POCO (declarative mapping). These attributes are used by the driver when the class map is auto-mapped. This happens when the class is first used to access data in a collection:

```csharp
public class BlogPost
{
  // ...
  [BsonElement("title")]
  public string Title { get; set; } = string.Empty;
  // ...
}
```

The above sample shows how the `BsonElement` attribute is used to adjust the name of the `Title` property in a document in MongoDB:

```BSON
{
  // ...
  "title": "Blog post title",
  // ...
}
```

However, there are scenarios when declarative mapping is not applicable: If you cannot change the POCOs because they are defined in a third-party libary or if you want to separate your POCOs from MongoDB-related code parts, there also is the option to define the class maps imperatively by calling methods in code:

```csharp
BsonClassMap.RegisterClassMap<BlogPost>(cm =>
{
  cm.AutoMap();
  cm.MapMember(x => x.Title).SetElementName("title");
});
```

The code above first performs the auto-mapping and then includes the `Title` property in the mapping as an element named `title` in BSON, thus overriding the auto-mapping for the specific property.

One thing to keep in mind is that the class map needs to be registered before the driver starts the automatic mapping process for a class. It is a good idea to include it in the bootstrapping process of the application.

This post will use declarative mapping for better readability but all of the adjustments can also be made using imperative mapping, as well. You can find an imperative class map that contains all the samples at the end of the post. 
## Adjusting property names

Whether you are working with existing data or want to name properties differently in BSON for other reasons, you can use the `BsonElement("specificElementName")` attribute introduced above. This is especially handy if you only want to change the name of a limited set of properties.  

If you want to change the naming scheme in a widespread fashion, you can use a convention that is applied when auto-mapping the classes. The driver offers a number of conventions out-of-the-box (see the namespace [MongoDB.Bson.Serialization.Conventions](https://mongodb.github.io/mongo-csharp-driver/2.22/html/N_MongoDB_Bson_Serialization_Conventions.htm)) and offers the flexibility to create custom ones if those are not sufficient.  

An example is to name the POCO properties according to C# naming guidelines in Pascal case in C#, but name the elements in camel case in BSON by adding the [CamelCaseElementNameConvention](https://mongodb.github.io/mongo-csharp-driver/2.22/html/T_MongoDB_Bson_Serialization_Conventions_CamelCaseElementNameConvention.htm): 

```csharp
var pack = new ConventionPack();
pack.Add(new CamelCaseElementNameConvention());
ConventionRegistry.Register(
  "Camel Case Convention",
  pack, 
  t => true);
```

Please note the predicate in the last parameter. This can be used to fine-tune whether the convention is applied to a type or not. In our sample, it is applied to all classes.   
The above code needs to be run before auto-mapping takes place. You can still apply a `BsonElement` attribute here and there if you want to overwrite some of the names.

## Using ObjectIds as identifiers

MongoDB uses [ObjectIds](https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-objectid) as identifiers for documents by default for the “_id” field. This is a data type that is unique to a very high probability and needs 12 bytes of memory. If you are working with existing data, you will encounter ObjectIds for sure. Also, when setting up new documents, ObjectIds are the preferred choice for identifiers. In comparison to GUIDs (UUIDs), they require less storage space and are ordered so that identifiers that are created later receive higher values.

In C#, properties can use `ObjectId` as their type. However, using `string` as the property type in C# simplifies the handling of the identifiers and increases interoperability with other frameworks that are not specific to MongoDB (e.g. OData).  

In contrast, MongoDB should serialize the identifiers with the specific BSON type ObjectId to reduce storage size. In addition, performing a binary comparison on ObjectIds is much safer than comparing strings as you do not have to take letter casing, etc. into account.

```csharp
public class BlogPost
{
  [BsonRepresentation(BsonType.ObjectId)]
  public string Id { get; set; } = ObjectId.GenerateNewId().ToString();
  // ...
  [BsonRepresentation(BsonType.ObjectId)]
  public ICollection<string> TopComments { get; set; } = new List<string>();
}
```

By applying the `BsonRepresentation` attribute, the `Id` property is serialized as an `ObjectId` in BSON. Also, the array of identifiers in `TopComments` also uses ObjectIds as their data type for the array elements: 

```BSON
{ 
  "_id" : ObjectId("6569b12c6240d94108a10d20"), 
  // ...
  "TopComments" : [
    ObjectId("6569b12c6240d94108a10d21"), 
    ObjectId("6569b12c6240d94108a10d22")
  ] 
}
```
## Serializing GUIDs in a consistent way

While `ObjectId` is the default type of identifier for MongoDB, GUIDs or UUIDs are a data type that is used for identifying objects in a variety of programming languages. In order to store and query them efficiently, using a binary format instead of strings is also preferred. 

In the past, GUIDs/UUIDs have been stored as BSON type binary of subtype 3; drivers for different programming environments serialized the value differently. Hence, reading GUIDs with the C# driver that had been serialized with a Java driver did not yield the same value. To fix this, the new binary subtype 4 was introduced by MongoDB. GUIDs/UUIDs are then serialized in the same way across drivers and languages. 

To provide the flexibility to both handle existing values and new values on a property level, the MongoDB C# Driver introduced a new way of handling GUIDs. This is referred to as `GuidRepresentationMode.V3`. For backward compatibility, when using Version 2.x of the MongoDB C# Driver, the GuidRepresentationMode is V2 by default (resulting in binary subtype 3). This is set to change with MongoDB C# Driver version 3. It is a good idea to opt into using V3 now and specify the subtype that should be used for GUIDs on a property level. For new GUIDs, subtype 4 should be used. 

This can be achieved by running the following code before creating the client: 

```csharp
BsonDefaults.GuidRepresentationMode 
= GuidRepresentationMode.V3;
```

Keep in mind that this setting requires the representation of the GUID to be specified on a property level. Otherwise, a `BsonSerializationException` will be thrown informing you that "GuidSerializer cannot serialize a Guid when GuidRepresentation is Unspecified." To fix this, add a `BsonGuidRepresentation` attribute to the property: 

```csharp
[BsonGuidRepresentation(GuidRepresentation.Standard)]
public Guid MyGuid { get; set; } = Guid.NewGuid();
```

There are various settings available for `GuidRepresentation`. For new GUIDs, `Standard` is the preferred value, while the other values (e.g., `CSharpLegacy`) support the serialization of existing values in binary subtype 3. 

For a detailed overview, see the [documentation of the driver](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/guid-serialization/). 

## Processing extra elements

Maybe you are working with existing data and only some part of the elements is relevant to your use case. Or you have older documents in your collection that contain elements that are not relevant anymore. Whatever the reason, you want to keep the POCO minimal so that it only comprises the relevant properties.  

By default, the MongoDB C# Driver is strict and raises a `FormatException` if it encounters elements in a BSON document that cannot be mapped to a property on the POCO: 

```"Element '[...]' does not match any field or property of class [...]."```
 Those elements are called "extra elements."

One way to handle this is to simply ignore extra elements by applying the `BsonIgnoreExtraElements` attribute to the POCO: 

```csharp
[BsonIgnoreExtraElements]
public class BlogPost 
{
  // ...
}
```

If you want to use this behavior on a large scale, you can again register a convention: 

```csharp
var pack = new ConventionPack();
pack.Add(new IgnoreExtraElementsConvention(true));
ConventionRegistry.Register(
  "Ignore Extra Elements Convention",
  pack, 
  t => true);
```
Be aware that if you use _replace_ when storing the document, extra properties that C# does not know about will be lost. 

On the other hand, MongoDB's flexible schema is built for handling documents with different elements. If you are interested in the extra properties or you want to safeguard for a replace, you can add a dictionary to your POCO and mark it with a `BsonExtraElements` attribute. The dictionary is filled with the content of the properties upon deserialization: 

```csharp
public class BlogPost
{
  // ...
  [BsonExtraElements()]
  public IDictionary<string, object> ExtraElements { get; set; } = new Dictionary<string, object>();
}
```
Even when replacing a document that contains an extra-elements-dictionary, the key-value pairs of the dictionary are serialized as elements so that their content is not lost (or even updated if the value in the dictionary has been changed). 

## Serializing calculated properties

Pre-calculation is key for great query performance and is a common pattern when working with MongoDB. In POCOs, this is supported by adding read-only properties, e.g.: 

```csharp
public class BlogPost
{
  // ...
  public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
  public DateTime? UpdatedAt { get; set; }
  public DateTime LastChangeAt => UpdatedAt ?? CreatedAt;
}
```

By default, the driver excludes read-only properties from serialization. This can be fixed easily by applying a `BsonElement` attribute to the property — you don't need to change the name: 

```csharp
public class BlogPost
{
  // ...
  public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
  public DateTime? UpdatedAt { get; set; }
  [BsonElement()]
  public DateTime LastChangeAt => UpdatedAt ?? CreatedAt;
}
```

After this change, the read-only property is included in the document and it can be used in indexes and queries: 

```BSON
{ 
  // ...
  "CreatedAt" : ISODate("2023-12-01T12:16:34.441Z"), 
  "UpdatedAt" : null, 
  "LastChangeAt" : ISODate("2023-12-01T12:16:34.441Z") 
}
```
## Custom serializers

Common scenarios are very well supported by the MongoDB C# Driver. If this is not enough, you can create a [custom serializer](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/#custom-serializers) that supports your specific scenario.  

Custom serializers can be used to handle documents with different data for the same element. For instance, if some documents store the year as an integer and others as a string, a custom serializer can analyze the BSON type during deserialization and read the value accordingly. 

However, this is a last resort that you will rarely need to use as the existing options offered by the MongoDB C# Driver cover the vast majority of use cases. 

## Conclusion

As you have seen, the MongoDB C# Driver offers a lot of options to tweak the mapping between POCOs and BSON documents. POCOs can follow C# conventions while at the same time building upon a schema that offers good query performance and reduced storage consumption. 

If you have questions or comments, join us in the [MongoDB Developer Community](https://www.mongodb.com/community/forums/)!

### Appendix: sample for imperative class map

```csharp
BsonClassMap.RegisterClassMap<BlogPost>(cm =>
{
  // Perform auto-mapping to include properties 
  // without specific mappings
  cm.AutoMap();
  // Serialize string as ObjectId
  cm.MapIdMember(x => x.Id)
    .SetSerializer(new StringSerializer(BsonType.ObjectId));
  // Serialize ICollection<string> as array of ObjectIds
  cm.MapMember(x => x.TopComments)
    .SetSerializer(
       new IEnumerableDeserializingAsCollectionSerializer<ICollection<string>, string, List<string>>(
         new StringSerializer(BsonType.ObjectId)));
  // Change member name
  cm.MapMember(x => x.Title).SetElementName("title");
  // Serialize Guid as binary subtype 4
  cm.MapMember(x => x.MyGuid).SetSerializer(new GuidSerializer(GuidRepresentation.Standard));
  // Store extra members in dictionary
  cm.MapExtraElementsMember(x => x.ExtraElements);
  // Include read-only property
  cm.MapMember(x => x.LastChangeAt);
});
```






Starting out with MongoDB and C#? These tips will help you get your class maps right from the beginning to support your desired schema.

How to Set Up MongoDB Class Maps for C# for Optimal Query Performance and Storage Size

Among the good news of MongoDB.local NYC '24, was the announcement that MongoDB Entity Framework Core Provider has been made [globally available](https://www.mongodb.com/blog/post/mongodb-provider-entity-framework-core-now-generally-available). The provider integrates with Entity Framework and empowers .NET developers to easily access data in MongoDB databases with a well known framework.  

This post shows how you can set up the Provider in a C# project and build an API with ASP.NET Core that offers an OData compatible endpoint. For those new to [OData](https://www.odata.org/), this is a protocol that is used to build queryable REST APIs. User interfaces can access these APIs and use them to provide tabular views that offer a rich set of user interactions, like filtering, sorting or paging. As OData is an open standard, there is a wide variety of tools that can access OData compatible endpoints, e.g. Microsoft Excel or Microsoft Power BI. 

If you want to follow along with the samples in this post, we create an endpoint that queries the movies in the sample_flix-database. The easiest way to get an instance of this sample database is to [load the sample data in a MongoDB Atlas cluster](https://www.mongodb.com/docs/atlas/sample-data/). If you do not have a cluster already, you can set up a free MongoDB Atlas M0 cluster (see this [link](https://www.mongodb.com/docs/atlas/tutorial/deploy-free-tier-cluster/) for a guide). 

While this post will use a newly created ASP.NET Core Web API project, it is perfectly fine to add OData to offer the endpoints in addition to existing REST endpoints. When creating a new project, you might want to enable OpenAPI support for an easy way to test the API later on. Also, the new project should use controllers instead of a minimal API. 

![Additional information wizard showing default values](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt0d3de225540ded04/6659ba379518af99ef667d57/Additional_Info_Wizard.png)

# Create the Entity Framework DbContext

After setting up the ASP.NET Core project, we will first define the Entity Framework DbContext and then set it up with the MongoDB Entity Framework Core Provider. 

The first step is to add the MongoDB Entity Framework Core Provider package to the project either through the UI or the `dotnet` CLI: 

    dotnet add package MongoDB.EntityFrameworkCore

Then we define the entity class that contains the properties that we want to read from the database: 

```csharp
// requires using MongoDB.Bson;
public class Movie
{
    public string Id { get; set; } = ObjectId.GenerateNewId().ToString();
    public string Title { get; set; } = string.Empty;
    public string? Plot { get; set; }
    public IEnumerable<string>? Genres { get; set; }
    public IEnumerable<string>? Cast { get; set; }
    // additional properties as required
}
```

> Some of the properties (e.g. `Plot`) are nullable reference types. This asserts that missing values in the database do not result in an error when reading the documents. 

The next step is to set up the DbContext and add the configuration for the entity. This includes binding the entity to a collection and, as we are working with existing documents that follow a different naming convention, mapping the property names of the document to the ones of the .NET POCO: 

```csharp
// requires using Microsoft.EntityFrameworkCore;
// requires using MongoDB.Bson;
// requires using MongoDB.EntityFrameworkCore.Extensions;

public class MflixDbContext : DbContext
{
    public MflixDbContext(DbContextOptions options)
        : base(options)
    {
    }

    public DbSet<Movie> Movies { get; init; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        var movieEntity = modelBuilder.Entity<Movie>();
        movieEntity.ToCollection("movies");
        movieEntity.Property(x => x.Id)
            .HasElementName("_id")
            .HasConversion<ObjectId>();
        movieEntity.Property(x => x.Title).HasElementName("title");
        movieEntity.Property(x => x.Plot).HasElementName("plot");
        movieEntity.Property(x => x.Genres).HasElementName("genres");
        movieEntity.Property(x => x.Cast).HasElementName("cast");
    }
}
```

The `Id` property deserves special attention: in the MongoDB document, the `_id` property is stored as an ObjectId. In an OData interface, using strings instead of an `ObjectId` as the identifier value is much easier. By adding value conversion, we can have the best of both worlds: ObjectIds in MongoDB and strings in .NET. 

To finalize the set up of the MongoDB Entity Framework Core Provider, we register the client, database, and `MflixDbContext` in the IoC container: 

```csharp
// requires using Microsoft.EntityFrameworkCore;
// requires using MongoDB.Driver;
// requires using MongoDBEFODataVerify;

builder.Services.AddSingleton<IMongoClient>(prov =>
{
    // Retrieve connection string from configuration
    return new MongoClient("<your MongoDB connection string>");
});
builder.Services.AddSingleton(prov =>
{
    var client = prov.GetRequiredService<IMongoClient>();
    // Retrieve database name from configuration
    return client.GetDatabase("sample_mflix");
});
builder.Services.AddDbContext<MflixDbContext>((prov, options) =>
{
    var database = prov.GetRequiredService<IMongoDatabase>();
    options.UseMongoDB(
        database.Client, 
        database.DatabaseNamespace.DatabaseName);
});
```

If you are only using Entity Framework, it would be sufficient to register `MflixDbContext` and create the client in the factory method. The above sample code registers the client and database instance separately so that you can inject them independently if required. 

With the `DbContext` set up, we could also use controller scaffolding in order to generate the code for REST controllers if needed. However, for the sake of this post we will now create an OData endpoint from scratch. 

# Add OData to the project

The first step when adding OData to a project is to reference the `Microsoft.AspNetCore.OData` package, either through the UI or using the `dotnet` CLI: 

    dotnet add package Microsoft.AspNetCore.OData

Next, we add a method that defines the EDM model for the OData interface in `Program.cs`: 

```csharp
// requires using Microsoft.OData.Edm;
// requires using Microsoft.OData.ModelBuilder;

IEdmModel GetEdmModel()
{
    var model = new ODataConventionModelBuilder();
    model.EnableLowerCamelCase();
    model.EntitySet<Movie>("Movies");
    return model.GetEdmModel();
}
```

`EnableLowerCamelCase` changes the naming convention of the properties to start with a lowercase character. This matches the behavior of JSON serialization in a standard REST API. 

We then register the OData components with the IoC container by adding the following code in `Program.cs`: 

```csharp
// requires using Microsoft.OData;

// This should be already in the code
builder.Services
    .AddControllers()
// This is new
    .AddOData(options => options
        .Select()
        .Filter()
        .OrderBy()
        .Count()
        .SetMaxTop(100)
        .AddRouteComponents("odata", GetEdmModel()));
```

The code above enables various OData operations and restricts the maximum number of entities a client can request to prevent an overly large result set. 

Lastly, we add a controller that provides the OData endpoint for our query. The name of the controller should be `MoviesController` to match the registration of the entity set in `GetEdmModel`: 

```csharp
// requires using Microsoft.AspNetCore.OData.Query;
// requires using Microsoft.AspNetCore.OData.Routing.Controllers;

public class MoviesController : ODataController
{
    private readonly MflixDbContext _dbContext;

    public MoviesController(MflixDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    [EnableQuery(
        PageSize = 1000, 
        AllowedOrderByProperties = "title, plot")]  
    public IQueryable<Movie> Get()
    {
        return _dbContext.Movies;
    }
}
```

We inject an instance of `MflixDbContext` into the controller to retrieve the movies and mark the `Get` method with the `EnableQuery` attribute. The `PageSize` property allows us to set the maximum number of results sent to the client. Using `AllowedOrderByProperties` restricts the properties that can be used in sort operations. 

> The name must match the name that is serialized - lower camel case in our sample as we called `EnableLowerCamelCase` in `GetEdmModel` earlier. There are various other options that you can use to adjust the behavior of the query endpoint. Please see the [ASP.NET Core OData documentation](https://learn.microsoft.com/en-us/odata/webapi-8/fundamentals/query-options) for details. 

# Test the endpoint

Now we are ready to test the OData endpoint and start it in the debugger. If you have enabled OpenAPI and Swagger UI in your project, you can use Swagger UI for a simple test. This is enough to check basic readiness of the endpoint and serves as a good starting point. 

For more sophisticated requests, either enter the OData URL in a browser or use a tool like Postman or `curl` with OData URLs. 

A simple request to `https://localhost:\<YOUR PORT\>/odata/Movies` should return 10 movies in the following format: 

```JSON
{
    "@odata.context": "https://localhost:7104/odata/$metadata#Movies",
    "value": [
        {
            "id": "573a1390f29313caabcd4135",
            "title": "Blacksmith Scene",
            "plot": "Three men hammer on an anvil...",
            "genres": [
                "Short"
            ],
            "cast": [
                "Charles Kayser",
                "John Ott"
            ]
        },
        // 999 more results
    ],
    "@odata.nextLink": "https://localhost:7104/odata/Movies?$skip=10"
}
```

In order to make use of OData features like paging and filtering, you can also try the following requests: 

- Filter by title:   
  `https://localhost:\<YOUR PORT\>/odata/Movies?$filter=title eq 'The Godfather'`
- Filter by part of title - case insensitive:  
  `https://localhost:\<YOUR PORT\>/odata/Movies?$filter=contains(tolower(title), 'godfather')`
- Paging with `$skip`, `$top` and `$count`:   
  `https://localhost:\<YOUR PORT\>/odata/Movies?$count=true&$top=10&$skip=10`
- Sorting with `$orderBy`:   
  `https://localhost:\<YOUR PORT\>/odata/Movies?$orderBy=title ASC`

# OData using MongoDB C# Driver

What if you already have an API and are using MongoDB C# Driver without Entity Framework? Plain and simple, all you need for OData to work is an `IQueryable<T>`. 

This can be provided easily by `IMongoCollection<T>.AsQueryable()` so that we could also build the OData endpoint like this: 

```csharp
// requires using Microsoft.AspNetCore.OData.Query;
// requires using Microsoft.AspNetCore.OData.Routing.Controllers;
// requires using MongoDB.Driver;

public class MoviesController : ODataController
{
    private readonly IMongoCollection<Movie> _collMovies;

    public MoviesController(IMongoDatabase db)
    {
        _collMovies = db.GetCollection<Movie>("movies");
    }

    [EnableQuery(
        PageSize = 1000, 
        AllowedOrderByProperties = "title, plot")]
    public IQueryable<Movie> Get()
    {
        return _collMovies.AsQueryable();
    }
}
```

Please note that you also need to configure the mapping for the `Movie` class either by adding attributes or defining the class map imperatively. 

# Advanced query options

Up to now, we have built an OData endpoint that supports basic options for filtering, sorting and paging with the Microsoft.AspNetCore.OData package. Unfortunately, this package does not support `$select` and `$expand` in your requests. If you want to go one step further and also add support for these operations, you need to rely on a package provided by MongoDB and reference **MongoDB.AspNetCore.OData** instead of the Microsoft package. All you need to do is replace `EnableQuery` with `MongoEnableQuery` and your endpoint will support these operations.

```csharp
// requires using Microsoft.AspNetCore.OData.Routing.Controllers;
// requires using MongoDB.AspNetCore.OData.Query;
// requires using MongoDB.Driver;

public class MoviesController : ODataController
{
    private readonly IMongoCollection<Movie> _collMovies;

    public MoviesController(IMongoDatabase db)
    {
        _collMovies = db.GetCollection<Movie>("movies");
    }

    // Change this from EnableQuery to MongoEnableQuery
    [MongoEnableQuery(
        PageSize = 1000, 
        AllowedOrderByProperties = "title, plot")]
    public IQueryable<Movie> Get()
    {
        return _collMovies.AsQueryable();
    }
}
```

At the time of this writing, you need to follow the approach described in the section OData using MongoDB C# Driver above and cannot use a `DbSet<T>` provided by MongoDB Entity Framework Core Provider. 

For details on the package see this [repository](https://github.com/mongodb/mongo-aspnetcore-odata) on Github.

# Summary

In this post we showed how easy it is to add powerful query options to your API, with an OData endpoint that builds on Entity Framework and MongoDB. This API can be used to provide rich query options in the UI of your apps or can be accessed from popular tools like Microsoft Excel. As both frameworks are very powerful and offer a lot of options, be sure to check out the documentation on [MongoDB Entity Framework Core Provider](https://www.mongodb.com/docs/entity-framework/current/) and [ASP.NET Core OData](https://learn.microsoft.com/en-us/odata/webapi-8/overview). 

Do you already use OData or MongoDB Entity Framework Core Provider? Let us know in the [forums](https://community.mongodb.com).


Learn how to easily add OData support to a new or existing ASP.NET Core project with the new EF Core Provider

Query Your Data With ASP.NET Core, OData, and the MongoDB Entity Framework Core Provider

In comparison to relational database management systems (RDBMS), MongoDB's flexible schema is a huge step forward when handling object-oriented data. These structures often make use of polymorphism where common base classes contain the shared fields that are available for all classes in the hierarchy; derived classes add the fields that are relevant only to the specific objects. An example might be to have several types of vehicles, like cars and motorcycles, that have some fields in common, but each type also adds some fields that make only sense if used for a type: 

![An entity class diagram showing a vehicle type and then car and motorcycle classes that extend it](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blte9072d1e9c252d99/6630bb46ba17b050b3cb6c29/Screenshot_2024-04-30_103434.png)

For RDBMS, storing an object hierarchy is a challenge. One way is to store the data in a table that contains all fields of all classes, though for each row, only a subset of fields is needed. Another approach is to create a table for the base class that contains the shared fields and add a table for each derived class that stores the columns for the specific type and references the base table. Neither of these approaches is optimal in terms of storage and when it comes to querying the data. 

However, with MongoDB's flexible schema, one can easily store documents in the same collection that do only share some but not all fields. This article shows how the [MongoDB C# driver](https://www.mongodb.com/docs/drivers/csharp/current/) makes it easy to use this for storing class hierarchies in a very natural way. 

Example use cases include storing metadata for various types of documents, e.g., offers, invoices, or other documents related to business partners in a collection. Common fields could be a document title, a summary, the date, a vector embedding, and the reference to the business partner, whereas an invoice would add fields for the line items and totals but would not add the fields for a project report. 

Another possible use case is to serve both an overview and a detail view from the same collection. We will have a closer look at how to implement this in the summary of this article. 

# Basics

When accessing a collection from C#, we use an object that implements `IMongoCollection<T>` interface. This object can be created like this: 

```csharp
var vehiclesColl = db.CreateCollection<Vehicle>("vehicles");
```

When serializing or deserializing documents, the type parameter `T` and the actual type of the object provide the MongoDB C# driver with a hint on how to map the BSON representation to a C# class and vice versa. If only documents of the same type reside in the collection, the driver uses the class map of the type. 

However, to be able to handle class hierarchies correctly, the driver needs more information. This is where the *type discriminator* comes in. When storing a document of a derived type in the collection, the driver adds a field named `_t` to the document that contains the name of the class, e.g.:

```csharp
await vehiclesColl.InsertOneAsync(new Car());
```

leads to the following document structure: 

```JSON
{
  "_id": ObjectId("660d7d43e042f8f6f2726f6a"),
  "_t": "Car",
  // ... fields for vehicle 
  // ... fields specific to car
}
```

When deserializing the document, the value of the `_t` field is used to identify the type of the object that is to be created. 

Though this works out of the box without specific configuration, it is advised to support the driver by specifying the class hierarchy explicitly by using the `BsonKnownTypes` attribute, if you are using declarative mapping: 

```csharp
[BsonKnownTypes(typeof(Car), typeof(Motorcycle))]
public abstract class Vehicle
{
    // ...
}
```

If you configure the class maps imperatively, just add a class map for each type in the hierarchy to reach the same effect. 

By default, only the name of the class is used as value for the type discriminator. Especially if the hierarchy spans several levels and you want to query for any level in the hierarchy, you should store the hierarchy as an array in the type discriminator by using the `BsonDiscriminator` attribute: 

```csharp
[BsonDiscriminator(RootClass = true)]
[BsonKnownTypes(typeof(Car), typeof(Motorcycle))]
public abstract class Vehicle
{
    // ...
}
```

This applies a different discriminator convention to the documents and stores the hierarchy as an array:

```JSON
{
  "_id": ObjectId("660d81e5825f1c064024a591"),
  "_t": [
    "Vehicle",
    "Car"
  ],
  // ...
}
```

For additional details on how to configure the class maps for polymorphic objects, see the [documentation](https://www.mongodb.com/docs/drivers/csharp/current/fundamentals/serialization/polymorphic-objects/) of the driver. 

# Querying collections with polymorphic documents

When reading objects from a collection, the MongoDB C# driver uses the type discriminator to identify the matching type and creates a C# object of the corresponding class. The following query might yield both `Car` and `Motorcycle` objects: 

```csharp
var vehiclesColl = db.GetCollection<Vehicle>("vehicles");
var vehicles = (await vehiclesColl.FindAsync(FilterDefinition<Vehicle>.Empty))
    .ToEnumerable();
```

If you are only interested in documents of a specific type, you can create another instance of `IMongoCollection<T>` that returns only these: 

```csharp
var carsColl = vehiclesColl.OfType<Car>();
var cars = (await carsColl.FindAsync(FilterDefinition<Car>.Empty))
    .ToEnumerable();
```

This new collection instance respects the corresponding type discriminator whenever an operation is performed. The following statement removes only `Car` documents from the collection but keeps the `Motorcycle` documents as they are: 

```csharp
await carsColl.DeleteManyAsync(FilterDefinition<Car>.Empty);
```

If you are using the LINQ provider brought by the MongoDB C# driver, you can also use the LINQ `OfType<T>` extension method to only retrieve the `Car` objects: 

```csharp
var cars = vehiclesColl.AsQueryable().OfType<Car>();
```

# Serving multiple views from a single collection

As promised before, we now take a closer look at a use case for polymorphism: Let's suppose we are building a system that supports monitoring sensors that are distributed over several sites. The system should provide an overview that lists all sites with their name and the last value that was reported for the site along with a timestamp. When selecting a site, the system shows detailed information for the site that consists of all the data on the overview and also lists the sensors that are located at the specific site with their last value and its timestamp. 

This can be depicted by creating a base class for the documents that contains the id of the site, a name to identify the document, and the last measurement, if available. A derived class for the site overview adds the site address; another one for the sensor detail contains the location of the sensor: 

```csharp
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

public abstract class BaseDocument
{
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; } = ObjectId.GenerateNewId().ToString();

    [BsonRepresentation(BsonType.ObjectId)]
    public string SiteId { get; set; } = ObjectId.GenerateNewId().ToString();

    public string Name { get; set; } = string.Empty;

    public Measurement? Last { get; set; }
}

public class Measurement
{
    public int Value { get; set; }

    public DateTime Timestamp { get; set; }
}

public class Address
{
  // ...
}

public class SiteOverview : BaseDocument
{
    public Address Address { get; set; } = new();
}

public class SensorDetail : BaseDocument
{
    public string Location { get; set; } = string.Empty;
}
```

When ingesting new measurements, both the site overview and the sensor detail are updated (for simplicity, we do not use a multi-document transaction): 

```csharp
async Task IngestMeasurementAsync(
    IMongoCollection<BaseDocument> overviewsColl,
    string sensorId,
    int value)
{
    var measurement = new Measurement()
    {
        Value = value,
        Timestamp = DateTime.UtcNow
    };
    var sensorUpdate = Builders<SensorDetail>
        .Update
        .Set(x => x.Last, measurement);
    var sensorDetail = await overviewsColl
        .OfType<SensorDetail>()
        .FindOneAndUpdateAsync(
            x => x.Id == sensorId,
            sensorUpdate,
            new() { ReturnDocument = ReturnDocument.After });
    if (sensorDetail != null)
    {
        var siteUpdate = Builders<SiteOverview>
            .Update
            .Set(x => x.Last, measurement);
        var siteId = sensorDetail.SiteId;
        await overviewsColl
            .OfType<SiteOverview>()
            .UpdateOneAsync(x => x.SiteId == siteId, siteUpdate);
    }
}
```

Above sample uses `FindAndUpdateAsync` to both update the sensor detail document and also retrieve the resulting document so that the site id can be determined. If the site id is known beforehand, a simple update can also be used. 

When retrieving the documents for the site overview, the following code returns all the relevant documents: 

```csharp
var siteOverviews = (await overviewsColl
        .OfType<SiteOverview>()
        .FindAsync(FilterDefinition<SiteOverview>.Empty))
    .ToEnumerable();
```

When displaying detailed data for a specific site, the following query retrieves all documents for the site by its id in a single request: 

```csharp 
var siteDetails = await (await overviewsColl
    .FindAsync(x => x.SiteId == siteId))
    .ToListAsync();
```

The result of the query can contain objects of different types; you can use the LINQ `OfType<T>` extension method on the list to discern between the types, e.g., when building a view model. 

This approach allows for efficient querying from different perspectives so that central views of the application can be served with minimum load on the server. 

# Summary

Polymorphism is an important feature of object-oriented languages and there is a wide range of use cases for it. As you can see, the MongoDB C# driver provides a solid bridge between object orientation and the MongoDB flexible document schema. If you want to dig deeper into the subject from a data modeling perspective, be sure to check out the [polymorphic pattern](https://www.mongodb.com/developer/products/mongodb/polymorphic-pattern/) part of the excellent series "Building With Patterns" on the MongoDB Developer Center. 

An article discussing when and how to use polymorphism in a C# application using the MongoDB C# Driver.

Markus Wildgruber

Content by Markus Wildgruber

Handling Complex Aggregation Pipelines With C#

MongoDB C# Aggregation Pipeline Basics

How to Set Up MongoDB Class Maps for C# for Optimal Query Performance and Storage Size

Query Your Data With ASP.NET Core, OData, and the MongoDB Entity Framework Core Provider

Using Polymorphism with MongoDB and C#