Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Filtering

You can apply filters on Read, Update, and Delete data operations to alter the result of the query.

In this article:

Assembling a Filter Query

When using the Backend Services RESTful API, you need to pass the filter as a value of the X-Everlive-Filter header. Alternatively, you can send the filter as a URL parameter in the query string.

  • Using a header:

    Request:
        GET https://api.everlive.com/v1/your-app-id/type-name
    Headers:
        Authorization  Bearer your-access-token
        X-Everlive-Filter { "<field>" : "Sample Value" }
    
  • Using a query string parameter:

     https://api.everlive.com/v1/your-app-id/type-name?filter={"Author":"Sample Text"}
    

The filter expression uses MongoDB syntax. The list of supported operators includes the following:

Important

Native MongoDB operators are not supported when querying for data coming from Data Connectors, offline storage, or Kendo UI DataSource.

Comparison Logical Element Evaluation Array Projection
$eq
$gt
$gte
$lt
$lte
$ne
$in
$nin
$or
$and
$not
$nor
$exists
$type
$regex $all
$elemMatch
$size
$
$slice

Reading by Filter

To filter content type data when reading, use a normal read request with the X-Everlive-Filter added. This section contains example usage of some of the supported filtering operators.

Value Equal To/Not Equal To

The following example returns all items from the Books content type that have their Author field set to Ordinary Joe.

You can invert the logic, returning all items except for Ordinary Joe books, by replacing the $eq operator with $ne (not equal).

In the $eq case, { "Author" : { "$eq": "Ordinary Joe" } } is equivalent to { "Author" : "Ordinary Joe" }.

Request:
    GET https://api.everlive.com/v1/your-app-id/Books
Headers:
    Authorization  Bearer your-access-token
    X-Everlive-Filter { "Author" : { "$eq" : "Ordinary Joe" } }
Response:
    Status: 200 OK
    Content-Type: application/json
var filter = { "Author" : "Ordinary Joe" };

//Ajax request using jQuery
$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Books',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
              "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

Value Greater Than

The following example returns all items from the Products content type which have more than a thousand pieces on hand.

You can replace the $gt operator with any of the supported comparison operators ($gte, $lt, $lte) to achieve different logic.

Request:
    GET https://api.everlive.com/v1/your-app-id/Products
Headers:
    Authorization  Bearer your-access-token
    X-Everlive-Filter { "Inventory" : { "$gt" : 1000 } }
Response:
    Status: 200 OK
    Content-Type: application/json
var filter = { "Inventory" : { "$gt" : 1000 }
};

//Ajax request using jQuery
$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Products',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
               "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

Value in Array of Possible Matches

The following example returns all items from the Books content type that have their Author field set to Ordinary Joe or John Doe.

You can invert the logic, returning all items except for those two authors', by replacing the $in operator with $nin.

Request:
    GET https://api.everlive.com/v1/your-app-id/Books
Headers:
    Authorization  Bearer your-access-token
    X-Everlive-Filter { "Author" : { "$in" : [ "Ordinary Joe", "John Doe" ] } }
Response:
    Status: 200 OK
    Content-Type: application/json
var filter = {
    "Author" : { "$in" : [ "Ordinary Joe", "John Doe" ] }
};

//Ajax request using jQuery
$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Books',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
               "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

Compound Expressions

You can combine multiple filter criteria in an expression using the logical operators $and, $or, $nor, or $not.

The following code returns all products that have high inventory in the Pittsburgh warehouse.

Request:
    GET https://api.everlive.com/v1/your-app-id/Products
Headers:
    Authorization  Bearer your-access-token
    X-Everlive-Filter { "$and" : [ { "Inventory" : "1000" }, {"Location" : "Pittsburgh" } ] }
Response:
    Status: 200 OK
    Content-Type: application/json
var filter = { "$and" : [ { "Inventory" : "1000" }, { "Location" : "Pittsburgh"} ] };

//Ajax request using jQuery
$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Products',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
              "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

The next filter matches all people aged 20 to 30 with first name John or Jane.

    X-Everlive-Filter {
        "$and" : [
            { "$or": [ {"FirstName" : "John"}, {"FirstName" : "Jane"} ] },
            { "$and" : [ { "Age" : { "$gt" : 20 } }, { "Age" : { "$lt" : 30 } } ] }
        ]
    }

Date Range Expressions

You can use the Date JavaScript object to create the start and end dates for your query. The following example shows how to dynamically specify start and end dates relative to the current date:

var rangeStart = new Date();
rangeStart.setDate(rangeStart.getDate() - 10); // 10 days before today
var rangeEnd = new Date();
rangeEnd.setDate(rangeEnd.getDate() + 10); // 10 days after today

var filter = {  
   "$and" : [  
      {  
         "CreatedAt" : {  
            "$gt" : rangeStart // all items created after (>=) the rangeStart date
         }
      },
      {  
         "CreatedAt" : {  
            "$lt" : rangeEnd // all items created before (<=) the rangeEnd date
         }
      }
   ]
};

$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/type-name',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
              "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

Regular Expressions

You can filter values that match a regex pattern. Telerik Platform understands Perl compatible regular expressions (PCRE), version 8.39, with UTF-8 support.

Important

Regular expressions support when filtering data from Data Connectors is limited to the following use cases:

  • Starts with: ^searchstring (Example: var filter = {"name":{"$regex":"^John"}};)
  • Ends with: searchstring$ (Example: var filter = {"name":{"$regex":"John$"}};)
  • Contains: .*searchstring.* (Example: var filter = {"name":{"$regex":".*John.*"}};)

As a workaround, create a view or a stored procedure and map it to a Telerik Platform content type or cloud function respectively.

You can specify regular expression options using the $options operator.

The $options operator is not supported when filtering data from Data Connectors. Do not specify it, otherwise you will receive an incorrect result.

In the example below, the regular expression matches the results in a case-insensitive manner.

var startsWith = "^M";
// var endsWith = "v$";

var filter = {
    "Author": {
        "$regex": startsWith,
        "$options": "i"
    }
};

$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Books',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
              "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

Value Inside an Array Field

The $eq operator can also match a single value inside an array-type field but only when the array contains primitive data types: number, string, or boolean.

The following example will return only items whose Zip field contains the 15212 ZIP code, even if there are other values inside the array.

//"Zip":["11413","15212","32003"]

var filter = { "Zip" : { "$eq" : "15212" } }; // or simply { "Zip" : "15212" }

$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Clients',
    type: "GET",
    headers: {"Authorization" : "Bearer your-access-token",
              "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

Array Contains All Specified Values

This operator selects all array items that contain at least the specified elements. It matches both direct array elements and elements of nested arrays. Note that $all is simply a more convenient and compact notation that saves you the use of multiple $and operators over the same field.

Specification

{
    "MyFieldName": {
        "$all": ["Value1", "Value2", "Value3"]
    }
}

Value of Specified Type

This operator selects all content type items that contain a specified field of a specified BSON type. Use the number representation of the type to specify it in the filter. This can be useful when you want to find out what values have been stored with a particular type.

Specification

{
    "$type": {
        "MyFieldName": 3
    }
}

Field Exists

This operator selects items that contain (true) or do not contain (false) the specified field.

Specification

{
    "MyFieldName": {
        "$exists": true
    }
}

Array Element Matches Specified Criteria

Important

This section discusses the query selector $elemMatch operator pertaining to arrays, not the projection operator with the same name.

This operator selects documents that contain an array field with at least one element that matches all the specified query criteria.

Specification

In the following filter, Animals is the array field that we are testing. The code will return all items that contain an element Class with the value of Mammalia or Aves in this field.

{ "Animals": {
        "$elemMatch": {
            "Class": {  
                "$in": ["Mammalia", "Aves"]
            }
        }
    }
}

Updating by Filter

To update all items that match your filter criteria, use a normal update request with the X-Everlive-Filter added. It is very important to test the criteria beforehand because the update operation is potentially destructive with the wrong selection.

The next code defines a filter that selects all books except for those written by Ordinary Joe and then updates their publisher.

Request:
    PUT https://api.everlive.com/v1/your-app-id/Books
Headers:
    Authorization  Bearer your-access-token
    X-Everlive-Filter { "Author" : { "$ne" : "Ordinary Joe" } }
Request Body:
    { "Publisher": "Mars Publishing" }

Response:
    Status: 200 OK
    Content-Type: application/json
var filter = { "Author" : { "$ne" : "Ordinary Joe" } }

//Ajax request using jQuery
$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Books',
    type: "PUT",
    headers: {"Authorization" : "Bearer your-access-token",
              "X-Everlive-Filter" : JSON.stringify(filter) },
    contentType: "application/json",
    data: { "Publisher": "Mars Publishing" },
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

You can use a number of operators that only apply to update operations. Unlike the filter, these operators go into the request body. For example, instead of directly setting the value of a field, you could specify an increment:

// Sets the field explicitly
Request Body:
    { "Total": 1003 }

// Increments the existing field value
Request Body:
    "$inc": {
        "Total": 3
    }

The supported update operators include:

Field Modifiers

$set

This operator replaces a field value with the specified value.

Specification

{
    "$set": {
        "MyArrayField" : "NewValue"
    }
}

$inc

This operator increments or decrements the value of a Number-type field with the specified amount. Specify a positive number to request an increase or a negative for a decrease.

Specification

{
    "$inc": {
        "Quantity": -3
    }
}

Array Modifiers

The following operators update array fields.

`$`

Acts as a placeholder to update the first element that matches the query condition in an update.

Specification

{
    "$set": {
        "MyArrayField.$": "NewValue"
    }
}

$push

The operation appends one or more items to an array. It creates the specified array field if it doesn't exist.

Specification

{
    "$push": {
        "MyArrayFieldA": "NewValue",
        "MyArrayFieldB": "NewValue"
    }
}

$addToSet

Adds elements to an array only if they do not already exist in the set.

Specification

$pop

Removes the first or last item of an array.

Specification

{
    "$pop": {
        "MyArrayFieldA": -1, // removes first element
        "MyArrayFieldB": 1 // removes last element
    }
}

$pull

Removes all array elements that match the specified value.

Specification

{
    "$pull": {
        "MyArrayField": "tape"
    }
}
Before: { "MyArrayField" : [ "tape", "lp", "cd", "tape", "tape", "cd", "dvd", "lp" ] }
After: { "MyArrayField" : [ "cd", "cd", "dvd" ] }

$pullAll

Removes all matching values from an array.

Specification

{
    "$pullAll": {
        "MyArrayField": ["tape", "lp"]
    }
}
Before: { "MyArrayField" : [ "tape", "lp", "cd", "tape", "tape", "cd", "dvd", "lp" ] }
After: { "MyArrayField" : [ "cd", "cd", "dvd" ] }

$each

Adds each of the specified elements to the specified array field. Always use this operator in conjunction with $addToSet or $push.

Specification

{
   "$addToSet":{
      "MyArrayField":{
         "$each":[
            "Value1",
            "Value2"
         ]
      }
   }
}

$slice

Specifies the ultimate number of elements in an array during a $push. In other words, the $push will append the array with as many as elements as you specify, but will then only keep N elements, where N is specified using $slice. A negative value only keeps the last elements. A positive value only keeps the first elements. Always use this operator in conjunction with $each.

Specification

The following example appends three new values to MyArrayField and then trims the beginning so that only the last four elements of the resulting array remain.

{
    "$push": {
        "MyArrayField": {
            "$each": [
                "Value1",
                "Value2",
                "Value3"
            ],
            "$slice": -4
        }
    }
}

$sort

Sorts the elements in an array field during a $push. Use 1 for ascending order and -1 to specify descending. Always use this operator in conjunction with $each and $slice.

Specification

The following example adds a couple of objects to an MyArrayField and then ensures that the array elements don't exceed three and that they are sorted by the Key1 field inside the added objects in descending order.

{
    "$push": {
        "MyArrayField": {
            "$each": [{
                "Key1": "Value1"
            }, {
                "Key2": "Value2"
            }],
            "$slice": -3,
            "$sort": {
                "Key1": -1
            }
        }
    }
}

Deleting by Filter

You are advised to use deletion based on filtering criteria with extreme caution. If, due to a mistake, your filter ends up matching a wider range of data than you expected, you may lose this data irreversibly.

The following code deletes all books written by Ordinary Joe.

Request:
    DELETE https://api.everlive.com/v1/your-app-id/Books
Headers:
    Authorization  Bearer your-access-token
    X-Everlive-Filter { "Author" : "Ordinary Joe" }

Response:
    Status: 200 OK
    Content-Type: application/json
var filter = { "Author" : "Ordinary Joe" };

//Ajax request using jQuery
$.ajax({
    url: 'https://api.everlive.com/v1/your-app-id/Books',
    type: "DELETE",
    headers: {"Authorization" : "Bearer your-access-token",
               "X-Everlive-Filter" : JSON.stringify(filter) },
    success: function(data){
        alert("Items successfully deleted.");
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.