Using the QueryImplementingThingsOptimized Service
To call the QueryImplementingThingsOptimized service for Thing Shapes and Thing Templates, the following JavaScript services are available:
• QueryImplementingThingsOptimized
• QueryImplementingThingsOptimizedWithTotalCount
You can call them the same way as you would call the
QueryImplementingThings service. For more information, see
Using the QueryImplementingThings Service. For example,
ThingShapes["shape1"].QueryImplementingThingsOptimized.
WithTotalCount returns an infotable containing the result and the total number of rows, ignoring a maximum item limit or offset applied to the query. For example, if you query with maxItems set to 5, five rows are returned; however, the total number of rows might equal 100, which is the total number of rows found before applying the limit.
Parameters
The following parameters apply to QueryImplementingThingsOptimized:
• Parameters for QueryImplementingThings:
◦ EntityReference parentEntity,
◦ int nMaxItems
◦ TagCollection tagsToCompare,
◦ String nameMask,
◦ Query query,
◦ boolean withData,
◦ boolean withPermissions,
◦ Collection<String> basicPropertyNames,
◦ Collection<String> propertyNames,
• Additional parameters for QueryImplementingThingsOptimized:
◦ networkName
The network name on which to filter. The query will only return results found from Things in that network.
◦ networkParentNode
The name of the top node in the network that is specified in networkName. The query will return all children from the specified parent node in the network.
◦ networkMaxDepth
The level at which to look for children of the parent node. 1 returns direct children and 2 returns children of children. If it is set to 0 or default/null, it returns the full hierarchy of children.
◦ offset
The offset of the result by the specified value. For example, if there are 200 results in the database with an offset of 5, results 5 to 200 (for a total of 195) are returned.
You can combine offset with maxItems to simulate pagination. The further you query into a large number of results, query time may be slower.
For example, Things 1 to 1000 exist and maxItems is 5, so each page shows 5 results:
▪ Page 1: offset is 0. The first 5 results are returned since maxItems is 5.
▪ Page 2: offset is 5. Results 6 through 10 are returned.
▪ Page 3: offset is 10. Results 11 through 15 are returned.
▪ And so on.
In this example, the number of returned results is low, so query time is fast.
Restrictions
The QueryImplementingThingsOptimized service searches against the cache instead of the database, and the following restrictions apply:
• Only properties on the specified Thing Shape or Thing Template can be input. Properties can be specified using the propertyNames parameter. If a property is on the Thing but not on the specified Thing Shape, the service will throw an exception.
• Filtering or sorting on password type is not allowed.
• Things with a property that cannot be filtered due to permissions are ignored. If a property that is not filtered and not visible is requested, it will be returned as null for that Thing.
For example, you are filtering on property prop1 of a given Thing Shape, where Thing1, Thing2, and Thing3 exist. For Thing1, you cannot see prop1; therefore, Thing1 will be ignored even if its value matches the filter. Only Thing2 and Thing3 will be returned.
• Filtering or sorting on the following basic properties is not allowed: homeMashup, Avatar, projectName, and isSystemObject.