HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket


You may need to associate additional information with a rating or the rating statistics to support the use cases of your application. For example, a rating warrants a supporting explanation, so you want to store that text with the rating. Like other Optimizely Community API features, you can extend a rating with data of your design by creating a Composite. See also _Composites_ in [Discovering the platform](🔗).

## Add a composite rating

To save a Composite Rating that you defined, use the `Add<TExtension>(Rating,TExtension)` method of the `IRatingService`. This method accepts an instance of the `Rating` class and an instance of `TExtension`. It returns a new instance of `Composite<Rating,TExtension>`.

Consider the following class, which represents a sample of extension data:



In the example below, a rating is composed with an instance of this extension class:



In the above example, the request to add a rating is invoked synchronously. An example of adding a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Update a composite rating

To update a specific instance of a Composite Rating, which was previously added through the platform, use the `Update<TExtension>(RatingId, RatingValue, RatingValue, TExtension)` method of the `IRatingService`. This method accepts the ID of the rating to be updated (`RatingId`), the current value of the rating (`RatingValue`), the new value of the rating to be set (`RatingValue`), and extension data related to rating.

Note

This method accepts the current value of your `Rating`, in addition to the new value, to ensure consistency in the calculation of the statistical measures associated with that `Rating`.

Consider the following class, which represents a sample of extension data:



In the example below, an existing rating is updated with a new instance of this extension class:



If the rating to be updated does not exist or the specified current value is no longer consistent with the stored representation of that rating, a `RatingDoesNotExistException` is thrown.

In the above example, the request to update a rating is invoked synchronously. An example of updating a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Retrieve a composite rating

To retrieve a specific instance of a Composite Rating, which was previously added through the platform, use the `Get<TExtension>(RatingId)` method. This method accepts an instance of the `RatingId` class, which identifies the particular rating to be retrieved. It returns the instance of the `Composite<Rating,TExtension>` class corresponding to that identifier.



If a Composite Rating with the specified ID and extension type cannot be found, a `RatingDoesNotExistException` is thrown.

In the above example, the request to retrieve a rating is invoked synchronously. An example of retrieving a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of Composite Ratings that were previously added through the platform, use the `Get<TExtension>(CompositeCriteria<RatingFilter,TExtension>)` method. This method accepts an instance of `CompositeCriteria<RatingFilter,TExtension>`, which contains specifications to retrieve the desired ratings.

The `Filter` property of the `CompositeCriteria<RatingFilter,TExtension>` class accepts an instance of the `RatingFilter` class. This class contains specifications for refining the result set of ratings you want to retrieve.

The `ExtensionFilter` property of the `CompositeCriteria<RatingFilter,TExtension>` class accepts a `FilterExpression`, which lets you specify a Boolean expression. Use the expression to further refine the result set by values represented in your extension data. For information on this type of filter, see _Composite Criteria_ and _Filter composites_ in [Discovering the platform](🔗).

Consider the following class, which represents a sample of extension data:



In the example below, a page of ratings composed with `MyRatingExtension` is retrieved, where the `Sentiment` property of that extension data has a value of _Happy_:



In the above example, the request to retrieve ratings is invoked synchronously. An example of retrieving ratings asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



You can also apply the fields of your extension data to sort your result set. The example below demonstrates the use of an extension data field in the definition of a sorting rule.



### Add composite rating statistics

Rating statistics are automatically generated by the platform when a rating for a new referenced target is added. The platform does not automatically add composite data to the generated rating statistics. To add composite rating statistics, use the `Update<TExtension>(Reference, TExtension)` method of the `IRatingStatisticsService`. This method accepts a reference to the rated target and the extension data to be added to the rating statistics.



If the rating statistics cannot be found using the given target reference, a `RatingStatisticsDoNotExistException` is thrown.

In the above example, the request to add the extension data to the rating statistics is invoked synchronously. An example of adding composite data to rating statistics asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Update composite rating statistics

To update the extension data of composite rating statistics use the `Update<TExtension>(Reference, TExtension)` method of the `IRatingStatisticsService`. This method accepts a reference to the rated target and the updated extension data.



If the rating statistics cannot be found using the given target reference, a `RatingStatisticsDoNotExistException` is thrown.

In the above example, the request to update extension data of the rating statistics is invoked synchronously. An example of updating the extension data of rating statistics asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Retrieve composite rating statistics

To retrieve a collection of composite rating statistics, use the `Get<TExtension>(CompositeCriteria<RatingStatisticsFilter,TExtension>)` method. This method accepts an instance of `CompositeCriteria<RatingStatisticsFilter,TExtension>`, which contains specifications to retrieve the desired composite rating statistics.

The `Filter` property of the `CompositeCriteria<RatingStatisticsFilter,TExtension>` class accepts an instance of the `RatingStatisticsFilter` class. This class contains specifications for refining the result set of composite rating statistics you want to retrieve.

The `ExtensionFilter` property of the `CompositeCriteria<RatingStatisticsFilter,TExtension>` class accepts a `FilterExpression`, which lets you specify a Boolean expression. Use the expression to further refine the result set by values represented in your extension data. For information on this type of filter, see _Composite Criteria_ and _Filter composites_ in [Discovering the platform](🔗).

Consider the following class, which represents a sample of extension data:



In the example below, a page of rating statistics composed with `MyRatingStatisticsExtension` is retrieved, where the `WeightedAverage` property of that extension data has a value of _10_:



In the above example, the request to retrieve rating statistics is invoked synchronously. An example of retrieving rating statistics asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



You can also apply the fields of your extension data to sort your result set. The example below demonstrates the use of an extension data field in the definition of a sorting rule.