Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.

MongoDB basics

Describing query, projection and updates

Querying MongoDB data

This section describes how to construct MongoDB queries based to select needed documents.

Query object is a simple JSON object, that allows you to write expressions to match properties in the documents you want to retrieve.

Matching exact values

To select all documents where some property has specific value you just need to provide property as key and your selected value.
Note that type and case must match value exactly as it is stored.

//selecting documents with did property and value "123"
{"did":"123"}
//selecting documents which have did property with "123" 
//and uid property with "abc"
{"did":"123","uid":"abc"}
//assuming there is a document with {"hasData":true} property

//this query will match it
{"hasData":true}

//this query will not match it
{"hasData":"true"}
//assuming there is a document with {"data":"Test"} property

//this query will match it
{"data":"Test"}

//this query will not match it
{"data":"test"}

This also matches values in properties has arrays. Assuming document with property like {"tags":["a","b","c"]}. Selecting documents where tags contain a value in the array would be simply as:

{"tags":"a"}

None equality

In similar manner you can query the documents which properties does not equal specific values. Same rules apply about type and case checks.

//selecting documents with did property not equal value "123"
{"did":{"$ne":"123"}}
//selecting documents which have did property not equal "123" 
//and uid property not equal "abc"
{"did":{"$ne":"123"},"uid":{"$ne":"abc"}}
//selecting documents which have did property not equal "123" 
//and uid property equal "abc"
{"did":{"$ne":"123"},"uid":"abc"}

Querying ranges

Instead of querying specific value you can query ranges of different values.
For numbers, it expresses as greater than, lesser than operators.

  • $gt - greater than
  • $lt - less than
  • $gte - greater or equal than
  • $lte - less or equal than
//qty property value greater than 20
{"qty":{"$gt":20}}

//qty property value in the ranges between 10 and 20 inclusive
{"qty":{"$gte":10,"$lte":20}}

//qty property value in the ranges between 10 and 20 inclusive
//and uid equal "abc"
{"qty":{"$gte":10,"$lte":20},"uid":"abc"}

Query sets of values

For string values we can define sets that selected documents should or should not include using operators:

  • $in - to include at least one of the values
  • $nin - does not include any of the values
//select documents where property uid equals to "abc" or "cba"
{"uid":{"$in":["abc","cba"]}}
//select documents where property uid does not equal to "abc" or "cba"
{"uid":{"$nin":["abc","cba"]}}

Checking if property exists

To check if property exists or does not exist can be done using $exists operator

//select all documents which have property data with any type except undefined
{"data":{"$exists":true}}
//select all documents which have property data undefined
{"data":{"$exists":false}}

MongoDB projection

This section describes how to use projection to return only the fields you need.

Projection is a simple JSON object, with field name as key and value as 1 or 0, to indicate, respectively, if field should be returned or not.
By default _id field is always returned, and should be explicitly excluded by specifying {_id:0}

//these fields will be excluded, all other fields returned
{"did":0,"uid":0,"custom":0} 
//these fields will be returned, including _id field
{"did":1,"uid":1,"custom":1} 
//these fields will be returned, excluding _id field
{"did":1,"uid":1,"custom":1,"_id":0} 

MongoDB updates

This section describes how to construct MongoDB update objects to change data inside database.

To change propertied of the document update object should contain operators to describe what needs to be done with specified field. These operators are:

  • $set - sets or changes the value of a property
  • $unset - removes the specified property from a document
  • $inc - increments the value of the property by the specified amount
  • $mul - multiplies the value of the property by the specified amount
  • $min - only updates the property if the specified value is less than the existing value.
  • $max - only updates the property if the specified value is greater than the existing value.
//change value of data to "123"
{"$set":{"data":"123"}}

//change value of data to "123" and uid to "abc"
{"$set":{"data":"123","uid":"abc"}}

//change value of sub property old in {"data":{"old":true}} to false 
{"$set":{"data.old":false}}
//remove property data
{"$unset":{"data":""}}

//remove properties data and uid
{"$unset":{"data":"","uid":""}}

//remove sub property old in {"data":{"old":true}}
{"$unset":{"data.old":""}}
//increment value count by 2, if it was 1, after will be 3
{"$inc":{"count":2}}

//deduct value count by 2, if it was 3, after will be 1
{"$inc":{"count":-2}}
//multiply value count by 2, if it was 2, after will be 4
{"$mul":{"count":2}}

//divide value count by 2, if it was 4, after will be 2
{"$mul":{"count":0.5}}
//assuming document 
//{"_id": 1, "highScore": 800, "lowScore": 200 }

//will update low score to 150
{ "$min": { "lowScore": 150 } }

//will not update low score to 250, because existing value is less
{ "$min": { "lowScore": 250 } }
//assuming document 
//{"_id": 1, "highScore": 800, "lowScore": 200 }

//will update high score to 1000
{ "$max": { "highScore": 1000 } }

//will not update high score to 750, because existing value is more
{ "$max": { "highScore": 750 } }
//of course you can combine operators in one object
{"$set":{"data":"123"},"$inc":{"count":2},"$min":{"lowScore":150}}

MongoDB basics

Describing query, projection and updates