Using mongoDB Query Syntax

Oracle IoT Cloud Service REST APIs use q as a query parameter and follow the mongoDB query syntax to provide the values of the q parameter. mongoDB is a open source document database. The format of the parameter values that forms your search criteria, are described in the following sections.

Definition

The search criteria contains a name of the parameter and a value that is also know as an expression. An example of using q parameter is as follows:

https://iotserver:7002/iot/api/v2/devices?q={"serialNumber":{"$like" "serial%"}}

Note:

In all the examples, iotserver will be replaced by name and port of your assigned Oracle IoT Cloud Service instance. The format of the Cloud Service instance is myinstance-myidentitydomain.iot.us.oraclecloud.com and the default port is 443.

The response to the request contains all devices whose serialNumber field starts with serial.

Here serialNumber is the name of the parameter and {"$like" : "serial%"} is the expression. The expression has two parts, the operator appears first and is prefixed by $

and then the search value is provided following a :.

Conventions for Parameter Names

• The name of the parameter cannot start with a $ symbol.

• The full path of the parameter must be provided.

  Example:

  Consider a device described in the following JSON file:

  {
      "manufacturer" : "Oracle",
      "serialNimber" : "123",
      "deviceModels" : [
          {"urn" : "example:urn", "name" : "name1"},
          {"urn" : "another:example:urn", "name" : "name2"},
   
      ]
  }
  

  The query parameter to search for a name or a urn field of device models is as follows:

  {"deviceModels.name" : "name1"}
  or
  {"deviceModels.urn" : {"$like" : "%example%"} }

Types of Operators in an Expression

Operator	Definition	Syntax
$eq	Equal expression	{"field": { "$eq":"value" } }
$gt	Greater than expression	{"field": {"$gt" : "value"} }
$gte	Greater than or equal expression	{"field": { "$gte" : "value" } }
&le	Less than expression	{"field": { "$lt" : "value" } }
$lte	Less than or equal expression	{"field": { "$lte" : "value" } }
$ne	Not equal expression	{"field": { "$ne" : "value"} }
$in	Matches any of the values specified in an array	{"field": { "$in" : ["value1", "value2", ... "valueN" ] } }
$exists	All values which is not null	{"field": {"$exists":true|false] } }
$like	matches to string pattern mentioned in value	{ "field" : { "$like" : "string pattern" } } where: string pattern may contain ' % ' or , '_' : % represents zero or more characters _ represents a single character

Operator	Definition	Syntax
$and	Joins query expressions using logical AND operation	{ "$and" : [{expression1}, {expression2}, ... {expressionN}] }
$or	Joins query expressions using logical OR operation	{ "$or" : [{expression1}, {expression2}, ... {expressionN}] }
$not	Logical not operation	{ "$not" : {expression} }

Examples of Expressions

Operator	Example
$eq	{"serialNumber" : {"$eq" : "serial-232"}} {"manufacturer" : "Oracle"}
$gt	{"temperatureMaxValue" : {"$gt" : 20}}
$gte	{"temperatureMinValue" : {"$gte" : 20}}
&le	{"temperatureMaxValue" : {"$lt" : 20}}
$lte	{"temperatureMaxValue" : {"$lte" : 20}}
$ne	{"connectivityStatus" : {"$ne" : "NEVER_HEARD_BEFORE"}}
$in	{"ledLight" : {"$in" : ["red", "blue", "green"]}}
$exists	{"wheel" : {"$exists" : true}}
$like	{"serialNumber" : {"$like" : "RS-%"}}
$and	{ "$and" : [{"manufacturer" : "Oracle"}, {"serialNumber" : {"$like" : "serial-%"}}, {"connectivityStatus" : "ONLINE"}] }
$or	{ "$or" : [{"connectivityStatus" : "OFFLINE"}, {"connectivityStatus" : "ONLINE"}] }
$not	{ "$not" : {"connectivityStatus" : "NEVER_HEARD_BEFORE"} }