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.

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