glp/0/{SID}/=query/request

To start a query, publish a query request object to the query request topic shown above.

Query provides a way to request items from the IAP/MQ feedback channel without needing to monitor the entire feedback channel. The query consists of a request and a response. The query request details the item or items of interest with absolute selection, wildcard selection and complex filter options, shapes the response with pagination controls and similar tools, and controls where the response shall be found.

The query response is published to a response endpoint provided with the query request.

Most of the examples shown for Query focus on the device object family because these are the most complex object structure in IAP/MQ, and because these are the most likely use-case for the Query API. However, nothing in this Query API is limited to the IAP/MQ device object family. The Query API and its implementations support standard and non-standard objects and properties.

Query Request Properties

The query request object has the following properties:

Field	Type	Description
corr	any	(Optional) Correlator. A verbatim copy is included with the response, if a correlator is provided.
filter	String or list of strings	The filter property provides a single filter or a list of filters. See Filtering for more information. Example: "dev/lon/*/sts"
response	String	The topic for the response publication. This is an absolute topic (not relative to the feedback or another IAP/MQ channel) allocated by the requester.
page	Number	Requested page number. Defaults to 1. A default query returns page 1 with an infinite number of results. Because those infinite results leave no further result behind, a snapshot is not allocated and a snapshot Id is not returned with the response. When the request limits the number of results and more results exist, a snapshot Id is returned with the response. Most implementations are expected to capture a snapshot at the time of the first query so that subsequent queries for the same filter can be satisfied from that snapshot without performing the search operation again, and while guaranteeing that the responses across all pages are consistent with each other regardless of changes which may have been applied to the underlying data since the first page was requested and the snapshot was created. Implementations may chose not to implement the snapshot as a buffer of result items, especially when storage resources are very limited. Such an implementation may need to perform the search and filter operation with every query request, but use the snapshot Id to detect changes to the underlying data, thus making sure that subsequent pages are consistent with the first page request, or yield an error. Requests for pages other than page 1 must include a snapshot Id. Requests which include a snapshot Id may omit the request filter, but all other request properties are accepted and honored as specified. Requests with an invalid or undefined snapshot Id, except for page 1, requests yield an error response.
items	Number	Maximum number of items per page. See page description. When items is not provided as a specific, finite, number of items, the response yields all applicable items.
snapshot	string	(Optional) Defaults to undefined. See page description above. Implementations of the query API may implement the snapshot as a short-lived temporary buffer of all responses related to the page 1 request. This method ensures that all pages are consistent at the time the first request was processed. Implementations are not required to keep such a snapshot for more than 10 minutes, and may limit the number of concurrent snapshots to 3. Temporary snapshot buffering is not required however. Implementations of the query API may chose to implement the snapshot as an integrity figure similar to an e-tag such that no temporary buffering is required to serve other pages, but a change in the underlying data is detected and voids the snapshot Id, triggering an error response.
style	string	Either “full”, “compact”, or “count”. Defaults to “full”. The Response result depends on the requested style.

Query Response

The query response object is published to the response topic indicated with the query request (always using QoS=1, retain=False).

Every query response message reports one item, or none, in the event of an error. N results are published with N query response objects in quick succession until all results are reported, or until the number of items per page have been reported.

For example, one query request might yield 15 items. The request might request page 1 with 12 items. This yields 12 responses. The remaining 3 items are delivered in response to the page 2 request, using 3 response publications.

Query Response Properties

The query response object has these properties:

Field	Type	Description
corr	any	A verbatim copy of the request correlator, if any was provided.
error	string	Undefined unless an error occurred. Example: “No such snapshot”
result	Result object	Result depends the requested style (either “count”, “full”, or “compact”). Valid only if error is null or undefined. For style == “count” the result is provided with the total response property and result is undefined. For style == “full” the result is an object with *item, path, and value* properties. *item* provides the topic of the IAP/MQ object that contains the value, relative to the IAP/MQ feedback channel. For example, a query for a device status object’s health property yields a result with item: “dev/lon/123/sts”. *path* provides the path to the value within the item. Path is always provided but can be empty if value contains the entire object published under item. Path can name a simple property within the object described with item, or it can use a slash-separated path to a nested property. For example, a query for a device status object’s health property yields a result with item: “dev/lon/123/sts”, path: “health”. *value* provides the value selected with item and path. For example, a query for a device status object’s health property yields a result with item: “dev/lon/123/sts”, path: “health”, value: “normal”. For style == “compact” the result is an object with item and *path* properties (see descriptions above). Example: { item: "...", path: "...", value: { … } }
page	Number	A default query returns page 1 with an infinite number of results. Because those infinite results leave no further result behind, a snapshot is not allocated, and a snapshot Id is not returned with the response.
item	Number	Item number within this page. The order of response items is non-deterministic; the response item number helps track completion and detect duplicates, but does not imply a specific order. The number of items reported with the response reflects the actual number of items within the page, not the maximum number of items per page requested. For example, 15 result items reported with a maximum page size of 12 as 10 items for page 1, and 3 items for page 2.
items	Number	Size of the page. See item description above.
snapshot	string	See page and snapshot descriptions in Query Properties table above.
total	Number	Reports the total number of matching items across all pages

Query Request Properties

Query Response

Query Response Properties

See also Filtering.

Browser not supported