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 $
:
.
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 aname
or aurn
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 |
where:
% 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 |
|
$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"} } |