Expanding Relations Using Advanced Parameters

Expanding Relations Using Advanced Parameters

You can go beyond the simple expand expression format when you want to achieve more complex expands such as such containing filtering, sorting, paging, and limiting the return fields.

For general information about the expand expression format see the Expanded Data Format help article.


When expanding one-to-many relations, you can include an optional filtering expression to narrow down on the expanded data.

Filtering the result of the expand expression is possible only when reading by ID in the base query.

Filtering can be used regardless of whether you are querying the content type that holds the relation or not.

For example, the following expand expression filters the expanded data by the Email field.

    GET https://api.everlive.com/v1/your-app-id/Activities/activityId
    X-Everlive-Expand: {
    "Likes": {
        "ReturnAs": "UsersWhoLikeThisActivity",
        "Filter": {
            "Email": {
                "$regex": "@telerik.com$"

Telerik Platform will execute the following request (in a addition to the main "get by ID") behind the scenes:

    GET https://api.everlive.com/v1/your-app-id/Users
    Authorization  Bearer your-access-token-here
    X-Everlive-Filter {"$and": [
        {"Email": { "$regex": "@telerik.com$" } },
        {"Id": { "$in" : [ "user1Id", "user2Id" ] } }

The additional query returns all users with an email in the "telerik.com" domain who liked our activity.

To invoke this request using the .NET SDK:

RegExCondition emailRegex = new RegExCondition("Email", "@telerik.com$");

FilteringDefinition filterDefinition = new FilteringDefinition();

ExpandDefinition expandDefinition = new ExpandDefinition("Likes", "UsersWhoLikeThisActivity");
expandDefinition.Filter = filterDefinition;



Similar to filtering, a standard Telerik Platform sorting expression can be added to the expand expression. It sorts the array of expanded data in case of one-to-many relations. In case of one-to-one relations, the sorting expression is ignored.

Sorting is applied only for "get by ID" requests. "Get by filter" request that return a single item are not considered a "get by ID" case.

Sorting can be used regardless of whether you are querying the content type that holds the relation or not.

Your final request should look like the following. It returns the activity with the specified ID together with all users who liked it sorted by their Email field in ascending order.

SortingDefinition sortDefinition = new SortingDefinition("Email", OrderByDirection.Ascending);

ExpandDefinition expandDefinition = new ExpandDefinition("Likes", "UsersWhoLikeThisActivity");
expandDefinition.Sort = sortDefinition;



When you are dealing with a great amount of result data you can use paging to ensure that the service returns the requested items in a timely fashion and that the response will not consume an excessive amount of bandwidth. Paging is implemented using the Skip and Take options.

The following example request returns only items 11 through 20.

Paging paging = new Paging(10, 10);

ExpandDefinition expandDefinition = new ExpandDefinition("Likes", "UsersWhoLikeThisActivity");
expandDefinition.Paging = paging;


Because the result order could be different on each request, it is strongly recommended to use sorting along with paging.

Selecting Return Fields

A fields expression is used to project the result (take only a subset of fields). It must be a valid Telerik Platform fields expression.

Fields selection can be used regardless of whether you are querying the content type that holds the relation or not.

FieldSelection and SingleField cannot be used simultaneously.

Here is an example of its usage:

FieldSelection fields = new FieldSelection("DisplayName", "Email");

ExpandDefinition expandDefinition = new ExpandDefinition("Likes", "UsersWhoLikeThisActivity");
expandDefinition.Fields = fields;


And the result:

    "Id": "activityId",
    "UsersWhoLikeThisActivity": [{
        "DisplayName": "Andy Gerald",
        "Email": "andy.gerald@telerik.com"
    }, {
        "DisplayName": "Michael Taylor",
        "Email": "michael.taylor@telerik.com"

Returning a Single Field

There are cases where you are interested in just a single field of an expanded object such as the DisplayName field of a user object. The SingleField expand option allows you to completely replace the expanded object with that field's value.

FieldSelection and SingleField cannot be used simultaneously.

The following example reads an activity by ID and adds all users who liked the activity, but instead of returning the entire user object, it replaces it with the value of the DisplayName field:

ExpandDefinition expandDefinition = new ExpandDefinition("Likes", "UsersWhoLikeThisActivity");
expandDefinition.SingleField = "DisplayName";

And the result:

    "Id": "activityId",
    "UsersWhoLikeThisActivity": [
        "Andy Gerald",
        "Michael Taylor"

Another example is expanding file metadata. Assume that you have a Books content type that stores a book collection. Each book has a field Cover of type File defined in the content type's structure that stores the Id of the book's cover image. If you want to retrieve the Uri where the image file is stored instead of retrieving its full metadata, you can do so by using SingleField like this:

ExpandDefinition expandDefinition = new ExpandDefinition("Cover", "CoverURL");
expandDefinition.SingleField = "Uri";


This request results in:

    "CoverURL": "https://bs1.cdn.telerik.com/v1/SLTCCCkPnud4GC29/0000bte0-c286-12e4-b57c-2939r6e80316",
    "CreatedAt": "2015-03-04T15:50:13.346Z",
    "ModifiedAt": "2015-03-04T15:50:13.346Z",
    "CreatedBy": "00000000-0000-0000-0000-000000000000",
    "ModifiedBy": "00000000-0000-0000-0000-000000000000",
    "Owner": "00000000-0000-0000-0000-000000000000",
    "Id": "0000f420-f286-11e4-9c5d-c5653ab2b427",
    "Meta": {
        "Permissions": {
        "CanRead": true,
        "CanUpdate": true,
        "CanDelete": true
Start a free trial Request a demo
Contact us: +1-888-365-2779
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.